From: Tanya Lattner Date: Tue, 18 Aug 2009 22:33:28 +0000 (+0000) Subject: First steps to document new release plan. X-Git-Url: http://plrg.eecs.uci.edu/git/?a=commitdiff_plain;h=4b9e1d291c83a35b08253d88861e736b2a6b45c8;p=oota-llvm.git First steps to document new release plan. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@79376 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/HowToReleaseLLVM.html b/docs/HowToReleaseLLVM.html index b6a5fd458cd..0fd5903a10a 100644 --- a/docs/HowToReleaseLLVM.html +++ b/docs/HowToReleaseLLVM.html @@ -10,14 +10,15 @@
How To Release LLVM To The Public
  1. Introduction
    2. +
  2. Qualification Criteria
  3. Release Timeline
  4. Release Process
    5. -
  5. Distribution Targets
-

Written by Reid Spencer, - John Criswell, - Tanya Lattner

+

Written by Tanya Lattner, + Reid Spencer, + John Criswell +

@@ -26,32 +27,23 @@

- This document collects information about successfully releasing LLVM to the - public. It is the release manager's guide to ensuring that a high quality + This document collects information about successfully releasing LLVM + (including subprojects llvm-gcc and Clang) to the public. + It is the release manager's responsibility to ensure that a high quality build of LLVM is released.

- -

- The following is the basic criteria for releasing LLVM: -

- -
    -
  1. Successful configure and build.
    2. -
  2. Clean 'make check'.
    3. -
  3. No regressions in the testsuite from the previous release. This may - include performance regressions for major benchmarks.
    4. -
Release Timeline
-The release manager should attempt to have a release every 3-4 months because LLVM -does time based releases (instead of feature based). The release schedule should -be roughly as follows: +

LLVM is released on a time based schedule (currently every 6 months). We + do not have dot releases because of the nature of LLVM incremental + developement philosophy. The release schedule is roughly as follows: +

    -
  1. Set code freeze and branch creation date for 3 months after last release +
  2. Set code freeze and branch creation date for 6 months after last code freeze date. Announce release schedule to the LLVM community and update the website.
  3. Create release branch and begin release process.
  4. Send out pre-release for first round of testing. Testing will last 7-10 days. @@ -71,44 +63,76 @@ pre-release testing.
    5. Release Process
    - -
    Process Overview
      +
    1. Release Administrative Tasks
      2. +
      1. Create Release Branch
        2. -
      2. Update LLVM Version
        3. +
      3. Update Version Numbers
        4. +
      +
    2. Building the Release
      3. +
      1. Build the LLVM Source Distributions
      2. Build LLVM
        3. -
      3. Build the LLVM GCC Binary Distribution
        4. -
      4. Build RPM Packages (optional)
        5. -
      5. Run 'make check'
        6. -
      6. Run LLVM Test Suite
        7. -
      7. Pre-Release Testing
        8. +
      8. Build the LLVM-GCC Binary Distribution
        9. +
      9. Build the Clang Binary Distribution
        10. +
      10. Target Specific Build Details
        11. +
      + +
    3. Release Qualification Criteria
      4. +
        +
      1. Qualify LLVM
        2. +
      2. Qualify LLVM-GCC
        3. +
      3. Qualify Clang
        4. +
      4. Specific Target Qualification Details
        5. +
      + +
    4. Community Testing
      5. +
    5. Release Patch Rules
      6. + + +
    6. Release final tasks
      7. +
      1. Tag the LLVM Release Branch
      2. Update Documentation
      3. Update the LLVM Demo Page
      4. Update the LLVM Website
      5. Announce the Release
        6. +
    -
    Create Release Branch
    +
    +Release Administrative Tasks
    + +
    +This section describes a few administrative tasks that need to be done for the +release process to begin. Specifically, it involves creating the release branch, + resetting version numbers, and creating the release tarballs for the release + team to begin testing. +
    + + +
    Create Release Branch

    Branch the Subversion HEAD using the following procedure:

    1. -

      Verify that the current Subversion HEAD is in decent shape by examining nightly - tester results.

      2. +

      Verify that the current Subversion HEAD is in decent shape by examining + nightly tester or buildbot results.

    2. Request all developers to refrain from committing. Offenders get commit rights taken away (temporarily).

    3. -

      Create the release branch for llvm, llvm-gcc4.2, and - the test-suite. The branch name will be release_XX, - where XX is the major and minor release numbers. These branches can - be created without checking out anything from subversion. +

      Create the release branch for llvm, llvm-gcc4.2, + clang, and the test-suite. The branch name will be + release_XX,where XX is the major and minor release numbers. + Clang will have a different release number than llvm/ + llvm-gcc4 since its first release was years later + (still deciding if this will be true or not). These branches + can be created without checking out anything from subversion.

      @@ -119,6 +143,8 @@ svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk \ https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \ https://llvm.org/svn/llvm-project/test-suite/branches/release_XX +svn copy https://llvm.org/svn/llvm-project/cfe/trunk \ + https://llvm.org/svn/llvm-project/cfe/branches/release_XX
      @@ -135,6 +161,7 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XX svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XX +svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XX
    @@ -142,7 +169,7 @@ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XX
-
Update LLVM Version
+
Update LLVM Version

After creating the LLVM release branch, update the release branches' @@ -150,18 +177,19 @@ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XX as well to be the next version (X.X+1svn). Regenerated the configure script for both. This must be done for both llvm and the test-suite.

+

FIXME: Add a note about clang.

In addition, the version number of all the Bugzilla components must be updated for the next release.

-
Build the LLVM Source Distributions
+
Build the LLVM Source Distributions

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

@@ -169,15 +197,25 @@ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XX svn export https://llvm.org/svn/llvm-project/llvm/branches/release_XX llvm-X.X svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX llvm-gcc4.2-X.X.source svn export https://llvm.org/svn/llvm-project/test-suite/branches/release_XX llvm-test-X.X -tar -cvf - llvm-X.X | gzip > llvm-X.X.tar.gz -tar -cvf - llvm-test-X.X | gzip > llvm-test-X.X.tar.gz -tar -cvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz +svn export https://llvm.org/svn/llvm-project/cfe/branches/release_XX clang-X.X +tar -czvf - llvm-X.X | gzip > llvm-X.X.tar.gz +tar -czvf - llvm-test-X.X | gzip > llvm-test-X.X.tar.gz +tar -czvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz +tar -czvf - clang-X.X.source | gzip > clang-X.X.source.tar.gz
-
Build LLVM
+
+Building the Release
+ +
+Info about this. Criteria for a successful build. +
+ + +
Build LLVM

Build both debug and release (optimized) versions of LLVM on all @@ -187,7 +225,7 @@ tar -cvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz

-
Build the LLVM GCC Binary Distribution
+
Build the LLVM GCC Binary Distribution

Creating the LLVM GCC binary distribution (release/optimized) requires @@ -204,76 +242,81 @@ tar -cvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz

  • Copy the installation directory to a directory named for the specific target. For example on Red Hat Enterprise Linux, the directory would be named - llvm-gcc4.0-2.1-x86-linux-RHEL4. Archive and compress the new directory. + llvm-gcc4.2-2.6-x86-linux-RHEL4. Archive and compress the new directory.
    • -
    Run 'make check'
    +
    Build Clang Binary Distribution

    - Using the newly built llvm-gcc and llvm, reconfigure llvm to locate llvm-gcc. - Run make check and ensure there are no unexpected failures. If there - are, resolve the failures or file a bug. If there is a fix commited to mainline, - merge back into the release branch, and restart testing by - re-building LLVM and llvm-gcc. If no - fix will be made, XFAIL the test and commit back to the release branch. + Creating the Clang binary distribution (release/optimized) requires + performing the following steps for each supported platform:

    +
      +
    1. + Instructions how to build it. +
      2. + +
    2. + Instructions on how to package +
      3. +
    +
    + + + +
    Target Specific Build +Details
    +

    - Ensure that 'make check' passes on all platforms for all targets. The - test suite must complete with "0 unexpected failures" before sending out the - pre-releases for testing. + Specify what is used to build llvm, llvm-gcc, clang on each target.

    + -
    LLVM Test Suite
    +
    +Building the Release
    + +
    +How to qualify the release. +
    + + + +
    Qualify LLVM

    - Run the llvm-test suite and ensure there are no unacceptable - failures. Unacceptable failures are regression from the previous release - and (optionally) major performance regressions from the previous release. - If a regression is found a bug is filled, but the pre-releases may still go - out.

    + Details

    -
    Building RPM packages (optional)
    +
    Qualify LLVM-GCC

    - 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: -

    + Details.

    +
    -
    -
    -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
-
    + +
    Qualify Clang
    +
    +

    + Details.

    + +
    Specific Target +Qualification Details
    +

    - 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. -

    + Details

    -
    Pre-Release Testing
    +
    Community Testing

    Once all testing has been completed and appropriate bugs filed, the pre-release @@ -300,9 +343,26 @@ make rpm # for binary rpm is determined to be ready and the release manager may move onto the next step.

    + +
    Release Patch Rules +
    +
    +

    + Details

    +
    + + + +
    Release Final Tasks +
    +
    +

    + Details

    +
    + -
    Tag the Release Branch
    +
    Tag the Release Branch

    Tag the release branch using the following procedure:

    @@ -318,7 +378,7 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \
    -
    Update Documentation
    +
    Update Documentation

    Review the documentation and ensure that it is up to date. The Release Notes @@ -340,7 +400,7 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \

    -
    Update the LLVM Website
    +
    Update the LLVM Website

    The website must be updated before the release announcement is sent out. Here is @@ -364,226 +424,11 @@ svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \

    -
    Announce the Release
    +
    Announce the Release

    Have Chris send out the release announcement when everything is finished.

    - -
    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. -

    - -
      -
    • distdir - builds the distribution directory from which the - distribution will be packaged
      • -
    • dist - builds each of the distribution tarballs (tar.gz, - tar.bzip2, .zip). These can be built individually as well, with separate - targets.
      • -
    • dist-check - this is identical to dist but includes a - check on the distribution that ensures the tarball can: unpack - successfully, compile correctly, pass 'make check', and pass - 'make clean'.
      • -
    • dist-clean- this just does a normal clean but also cleans up the - stuff generated by the other three dist targets (above).
      • -
    - -

    - 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, SVN 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.
      3. -
    - -

    - 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. -
    2. If you build the distribution with VERBOSE=1, then you might - also see: Skipping non-existent 'dir/file' in certain cases - where it's 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-gzip: package the gzipped distribution tar - file. The distribution directory is packaged into a single file ending - in .tar.gz which is gzip compressed.
      • -
    • dist-bzip2: package the bzip2 distribution tar file. - The distribution directory is packaged into a single file ending in - .tar.bzip2 which is bzip2 compressed.
      • -
    • dist-zip: package the zip distribution file. The - distribution directory is packaged into a single file ending in - .zip which is zip compressed.
      • -
    • dist: does all three, dist-gzip, dist-bzip2, - dist-zip
      • -
    -
    - - -
    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
    -
    -

    - 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. -

    -
    -