X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FHowToReleaseLLVM.html;h=bee43493c4396f652f4110c78b9cec960018100d;hb=1d33bb310865528f5b1a303e33891366457bc0ef;hp=decb89f174cf07da126e0fa2354d830131551a05;hpb=9a0c9551fabcb032b446ac97ede00c87c25cb6a4;p=oota-llvm.git diff --git a/docs/HowToReleaseLLVM.html b/docs/HowToReleaseLLVM.html index decb89f174c..bee43493c43 100644 --- a/docs/HowToReleaseLLVM.html +++ b/docs/HowToReleaseLLVM.html @@ -11,21 +11,12 @@

NOTE: THIS DOCUMENT IS A WORK IN PROGRESS!

  1. Introduction
    2. -
  2. Release Process -
      -
    1. Overview
      2. -
    2. Merge Branches
      3. -
    3. Build LLVM
      4. -
    4. Run 'make check'
      5. -
    5. Run LLVM Test Suite
      6. -
    6. make LibDeps.txt
      7. -
    7. cvs tag
      8. -
    8. make dist
      9. -
    9. Release
      10. -
    3. +
  3. Release Process
    4. +
  4. Distribution Targets
-

Written by Reid Spencer

+

Written by Reid Spencer, + John Criswell

@@ -35,9 +26,21 @@

This document collects information about successfully releasing LLVM to the public. It is the release manager's guide to ensuring that a high quality build -of LLVM is released. Mostly, its just a bunch of reminders of things to do at +of LLVM is released. Mostly, it's just a bunch of reminders of things to do at release time so we don't inadvertently ship something that is utility deficient.

+ +

+There are three main tasks for building a release of LLVM: +

    +
  1. Create the LLVM source distribution.
    2. +
  2. Create the LLVM GCC source distribtuion.
    3. +
  3. Create a set of LLVM GCC binary distribtuions for each supported + platform. These binary distributions must include compiled versions + of the libraries found in llvm/runtime from the LLVM + source distribution created in Step 1.
    4. +
+

@@ -48,67 +51,462 @@ deficient.

Process Overview
    -
  1. Merge Branches
    2. -
  2. Build LLVM
    3. -
  3. Run 'make check'
    4. -
  4. Run LLVM Test Suite
    5. -
  5. make LibDeps.txt
    6. -
  6. cvs tag
    7. -
  7. make dist
    8. -
  8. release
    9. +
  9. Update Documentation
    10. +
  10. Merge Branches
    11. +
  11. Make LibDeps.txt
    12. +
  12. Settle LLVM HEAD
    13. +
  13. Tag LLVM and Create the Release Branch
    14. +
  14. Update LLVM Version
    15. +
  15. Build LLVM
    16. +
  16. Run 'make check'
    17. +
  17. Run LLVM Test Suite
    18. +
  18. Build the LLVM Source Distributions
    19. +
  19. Build RPM Packages (optional)
    20. +
  20. Build the LLVM GCC Binary Distribution
    21. +
  21. Update the LLVM Website
+ +
Update Documentation
+
+

+ Review the documentation and ensure that it is up to date. The Release Notes + must be updated to reflect bug fixes, new known issues, and changes in the + list of supported platforms. The Getting Started Guide should be updated to + reflect the new release version number tag avaiable from CVS and changes in + basic system requirements. +

+
+
Merge Branches
-

Merge any work done on branches intended for release into mainline.

+

+Merge any work done on branches intended for release into mainline. Finish and +commit all new features or bug fixes that are scheduled to go into the release. +Work that is not to be incorporated into the release should not be merged from +branchs or commited from developer's working directories. +

+ +

+From this point until the release branch is created, developers should +not +commit changes to the llvm and llvm-gcc CVS repositories unless it is a bug +fix for the release. +

+
+ + +
Make LibDeps.txt
+
+

Rebuild the LibDeps.txt target in utils/llvm-config. This + makes sure that the llvm-config utility remains relevant for the + release, reflecting any changes in the library dependencies.

+
+ + + +
Settle CVS HEAD
+
+

+ Use the nightly test reports and 'make check' (deja-gnu based tests) to + ensure that recent changes and merged branches have not destabilized LLVM. + Platforms which are used less often should be given special attention as they + are the most likely to break from commits from the previous step. +

+
+ + +
CVS Tag And Branch
+
+

Tag and branch the CVS HEAD using the following procedure:

+
    +
  1. + Request all developers to refrain from committing. Offenders get commit + rights taken away (temporarily). +
    2. + +
  2. + The Release Manager updates his/her llvm, llvm-test, and llvm-gcc source + trees with the + latest sources from mainline CVS. The Release Manage may want to consider + using a new working directory for this to keep current uncommitted work + separate from release work. +
    3. + +
  3. + The Release Manager tags his/her llvm, llvm-test, and llvm-gcc working + directories with + "ROOT_RELEASE_XX" where XX is the major and minor + release numbers (you can't have . in a cvs tag name). So, for Release 1.2, + XX=12 and for Release 1.10, XX=110. + +

    + cvs tag ROOT_RELEASE_XX
    +

    +
    4. + +
  4. + Immediately create cvs branches based on the ROOT_RELEASE_XX tag. The tag + should be "release_XX" (where XX matches that used for the ROOT_RELEASE_XX + tag). This is where the release distribution will be created. + +

    + cvs tag -b -r ROOT_RELEASE_XX release_XX +

    +
    5. + +
  5. + Advise developers they can work on CVS HEAD again. +
    6. + +
  6. + The Release Manager and any developers working on the release should switch + to the release branch (as all changes to the release will now be done in + the branch). The easiest way to do this is to grab another working copy + using the following commands: + +

    + cvs -d <CVS Repository> co -r release_XX llvm
    + cvs -d <CVS Repository> co -r release_XX llvm-test
    + cvs -d <CVS Repository> co -r release_XX llvm-gcc
    +

    +
    7. +
+ + +
Update LLVM Version
+
+

+ After creating the llvm release branch, update the release branch's autoconf/configure.ac + version from X.Xcvs to just X.X. Update it on mainline as well to be the next version + (X.X+1cvs). +

+
Build LLVM
-

Build LLVM

+

+ Build both debug and release (optimized) versions of LLVM on all + platforms. Ensure the build is warning and error free on each platform. +

+ +

+ Build a new version of the LLVM GCC front-end after building the LLVM tools. + Once that is complete, go back to the LLVM source tree and build and install + the llvm/runtime libraries. +

Run 'make check'
-

Run "make check" and ensure there are no unexpected failures. If there - are, resolve the failures and go back to step 2.

+

Run make check and ensure there are no unexpected failures. If + there are, resolve the failures, commit them back into the release branch, + and restart testing by re-building LLVM. +

+ +

+ Ensure that 'make check' passes on all platforms for all targets. If certain + failures cannot be resolved before release time, determine if marking them + XFAIL is appropriate. If not, fix the bug and go back. The test suite must + complete with "0 unexpected failures" for release. +

LLVM Test Suite

Run the llvm-test suite and ensure there are no unacceptable failures. - If there are, resolve the failures and go back to step 2.

+ If there are, resolve the failures and go back to + re-building LLVM. The test suite + should be run in Nightly Test mode. All tests must pass.
-
Make LibDeps.txt
+
Build the LLVM Source Distributions
-

Rebuild the LibDeps.txt target in utils/llvm-config. This makes sure that - the llvm-config utility remains relevant for the release, reflecting any - changes in the library dependencies.

+

+ Create source distributions for LLVM, LLVM GCC, and the LLVM Test Suite by + exporting the source + from CVS and archiving it. This can be done with the following commands: +

+ +

+ cvs -d <CVS Repository> export -r release_XX llvm
+ cvs -d <CVS Repository> export -r release_XX llvm-test
+ cvs -d <CVS Repository> export -r release_XX llvm-gcc
+ mkdir cfrontend; mv llvm-gcc cfrontend/src
+ tar -cvf - llvm | gzip > llvm-X.X.tar.gz
+ tar -cvf - llvm-test | gzip > llvm-test-X.X.tar.gz
+ tar -cvf - cfrontend/src | gzip > cfrontend-X.X.source.tar.gz
+

-
CVS Tag
+
Building RPM packages (optional)
-

Tag the release.

+

You can, optionally, create source and binary RPM packages for LLVM. These + may make it easier to get LLVM into a distribution. This can be done with + the following commands:

+ 
+  make dist        # Build the distribution source tarball
+  make dist-check  # Check that the source tarball can build itself.
+  cp llvm-M.m.tar.gz /usr/src/redhat/SOURCES  # Required by rpmbuild
+  make srpm # for source rpm
+  make rpm  # for binary rpm
+
+

First, use "make dist" to simply build the distribution. Any + failures need to be corrected (on the branch). Once "make dist" can be + successful, do "make dist-check". This target will do the same thing as the + 'dist' target but also test that distribution to make sure it can build itself + and runs "make check" as well. This ensures that needed files are not + missing and that the src tarball can be successfully unpacked, built, + installed, and cleaned. Once you have a reliable tarball, you need to copy + it to the /usr/src/redhat/SOURCES directory which is a requirement of the + rpmbuild tool. The last two "make" invocations just run rpmbuild to build + either a source (srpm) or binary (rpm) RPM package.

-
Run 'make dist'
+
Build the LLVM GCC Binary Distribution
-

Build the distribution, ensuring it is installable and working

+

+ Creating the LLVM GCC binary distribution requires performing the following + steps for each supported platform: +

+ +
    +
  1. + Build the LLVM GCC front-end. The LLVM GCC front-end must be installed in + a directory named cfrontend/<platform>/llvm-gcc. For + example, the Sparc/Solaris directory is named + cfrontend/sparc/llvm-gcc. +
    2. + +
  2. + Build the libraries in llvm/runtime and install them into the + created LLVM GCC installation directory. +
    3. + +
  3. + For systems with non-distributable header files (e.g. Solaris), manually + remove header files that the GCC build process has "fixed." This process + is admittedly painful, but not as bad as it looks; these header files are + almost always easily identifiable with simple grep expressions and are + installed in only a few directories in the GCC installation directory. +
    4. + +
  4. + Add the copyright files and header file fix script. +
    5. + +
  5. + Archive and compress the installation directory. These can be found in + previous releases of the LLVM-GCC front-end. +
    6. +
+ +
Update the LLVM Website
+
+

+ Check out the llvm-www module from cvs. Create a new subdirectory X.X in the + releases directory. Place the llvm, llvm-test, llvm-gcc source, and llvm-gcc + binaries in this new directory. Copy the llvm/docs and LICENSE.txt files + into this new directory. Update the releases/download.html file with the new release. + Update the releases/index.html with the new release. Finally, update the main page ( + index.html and sidebar) to point to the new release and release announcement. Make + sure this all gets commited back into cvs. +

+
+ + + + +
Distribution Targets
+ + +
Overview
+
+

The first thing you need to understand is that there are multiple make +targets to support this feature. Here's an overview, we'll delve into the +details later.

+ +

Okay, that's the basic functionality. When making a release, we want to +ensure that the tree you build the distribution from passes +dist-check. Beyond fixing the usual bugs, there is generally one +impediment to making the release in this fashion: missing files. The +dist-check process guards against that possibility. It will either +fail and that failure will indicate what's missing, or it will succeed +meaning that it has proved that the tarballs can actually succeed in +building LLVM correctly and that it passes make check.

+ +
distdir
+

This target builds the distribution directory which is the directory from +which the tarballs are generated. The distribution directory has the same +name as the release, e.g. LLVM-1.7). This target goes through the following +process: +

    +
  1. First, if there was an old distribution directory (for the current + release), it is removed in its entirety and you see Removing old + LLVM-1.7
    2. +
  2. Second, it issues a make all ENABLE_OPTIMIZED=3D1 to ensure + that the everything in your tree can be built in release mode. Often times + there are discrepancies in building between debug and release modes so it + enforces release mode first. If that fails, the distdir target + fails too. This is preceded by the message Making 'all' to verify + build.
    3. +
  3. Next, it traverses your source tree and copies it to a new directory + that has the name of the release (LLVM-M.m in our current case). + This is the directory that will get tar'd. It contains all the software + that needs to be in the distribution. During the copying process, it omits + generated files, CVS directories, and any other "cruft" that's in your + build tree. This is done to eliminate the possibility of huge distribution + tarballs that include useless or irrelevant stuff in them. This is the + trickiest part of making the distribution. Done manually you will either + include stuff that shouldn't be in the distribution or exclude stuff that + should. This step is preceded by the message Building Distribution + Directory LLVM-1.7
    4. +
  4. The distribution directory is then traversed and all CVS or + .svn directories are removed. You see: Eliminating CVS/.svn + directories from distribution
    5. +
  5. The recursive dist-hook target is executed. This gives each + directory a chance to modify the distribution in some way (more on this + below).
    6. +
  6. The distribution directory is traversed and the correct file + permissions and modes are set based on the type of file.
    7. +
+

To control the process of making the distribution directory correctly, +each Makefile can utilize two features:

+
    +
  1. EXTRA_DIST - this make variable specifies which files + it should distribute. By default, all source files are automatically + included for distribution as well as certain well known files + (see DistAlways variable in Makefile.rules for details). Each Makefile + specifies, via the EXTRA_DIST variable, which additional files + need to be distributed. Only those files that are needed to build LLVM + should be added to EXTRA_DIST. EXTRA_DIST contains a + list of file or directory names that should be distributed. For example, + the top level Makefile contains + EXTRA_DIST := test llvm.spec include. + This means that in addition to regular things that are distributed at the + top level (CREDITS.txt, LICENSE.txt, etc.) the distribution should + contain the entire test and include directories as well + as the llvm.spec file.
    2. +
  2. dist-hook - this make target can be used to alter the + content of the distribution directory. For example, in the top level + Makefile there is some logic to eliminate files in the include + subtree that are generated by the configure script. These should not be + distributed. Similarly, any dist-hook target found in any + directory can add or remove or modify things just before it gets packaged. + Any transformation is permitted. Generally, not much is needed. +
+

You will see various messages if things go wrong:

+
    +
  1. During the copying process, any files that are missing will be flagged + with: ===== WARNING: Distribution Source 'dir/file' Not Found! + These must be corrected by either adding the file or removing it from + EXTRA_DIST. +
  2. If you build the distribution with VERBOSE=1, then you might + also see: Skipping non-existent 'dir/file' in certain cases where + its okay to skip the file.
    3. +
  3. The target can fail if any of the things it does fail. Error messages + should indicate what went wrong.
    4. +
+ +
dist
+

This target does exactly what distdir target does, but also +includes assembling the tarballs. There are actually four related targets +here:

+

+ +
dist-check
+

This target checks the distribution. The basic idea is that it unpacks the +distribution tarball and ensures that it can build. It takes the following +actions:

+
    +
  1. It depends on the dist-gzip target which, if it hasn't already + been built, builds the gzip tar bundle (see dist and distdir above).
    2. +
  2. removes any pre-existing _distcheckdir at the top level.
    3. +
  3. creates a new _distcheckdir directory at the top level.
    4. +
  4. creates a build subdirectory and an install + subdirectory under _distcheckdir.
    5. +
  5. unzips and untars the release tarball into _distcheckdir, + creating LLVM-1.7 directory (from the tarball).
    6. +
  6. in the build subdirectory, it configures with appropriate options to build + from the unpacked source tarball into the build directory with + installation in the install directory.
    7. +
  7. runs make all
    8. +
  8. runs make check
    9. +
  9. runs make install
    10. +
  10. runs make uninstall
    11. +
  11. runs make dist
    12. +
  12. runs make clean
    13. +
  13. runs make dist-clean
    14. +
+

If it can pass all that, the distribution will be deemed distribution +worth y and you will see:

+

===== LLVM-1.7.tar.gz Ready For Distribution =====
+

This means the tarball should then be tested on other platforms and have the +nightly test run against it. If those all pass, THEN it is ready for +distribution.

+

+A note about disk space: using dist-check will easily triple the +amount of disk space your build tree is using. You might want to check +available space before you begin.

+ +
dist-clean
+

dist-clean

+

In addition to doing a normal clean, this target will clean up the +files and directories created by the distribution targets. In particular the +distribution directory (LLVM-X.X), check directory +(_distcheckdir), and the various tarballs will be removed. You do +this after the release has shipped and you no longer need this stuff in your +build tree.