From 68cb31901c590cabceee6e6356d62c84142114cb Mon Sep 17 00:00:00 2001 From: mike-m Date: Thu, 6 May 2010 23:45:43 +0000 Subject: Overhauled llvm/clang docs builds. Closes PR6613. NOTE: 2nd part changeset for cfe trunk to follow. *** PRE-PATCH ISSUES ADDRESSED - clang api docs fail build from objdir - clang/llvm api docs collide in install PREFIX/ - clang/llvm main docs collide in install - clang/llvm main docs have full of hard coded destination assumptions and make use of absolute root in static html files; namely CommandGuide tools hard codes a website destination for cross references and some html cross references assume website root paths *** IMPROVEMENTS - bumped Doxygen from 1.4.x -> 1.6.3 - splits llvm/clang docs into 'main' and 'api' (doxygen) build trees - provide consistent, reliable doc builds for both main+api docs - support buid vs. install vs. website intentions - support objdir builds - document targets with 'make help' - correct clean and uninstall operations - use recursive dir delete only where absolutely necessary - added call function fn.RMRF which safeguards against botched 'rm -rf'; if any target (or any variable is evaluated) which attempts to remove any dirs which match a hard-coded 'safelist', a verbose error will be printed and make will error-stop. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@103213 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/HowToReleaseLLVM.html | 523 --------------------------------------------- 1 file changed, 523 deletions(-) delete mode 100644 docs/HowToReleaseLLVM.html (limited to 'docs/HowToReleaseLLVM.html') diff --git a/docs/HowToReleaseLLVM.html b/docs/HowToReleaseLLVM.html deleted file mode 100644 index c0ad6c9381..0000000000 --- a/docs/HowToReleaseLLVM.html +++ /dev/null @@ -1,523 +0,0 @@ - - - - How To Release LLVM To The Public - - - - -
How To Release LLVM To The Public
-
    -
  1. Introduction
    2. -
  2. Qualification Criteria
    3. -
  3. Release Timeline
    4. -
  4. Release Process
    5. -
-
-

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

-
- - -
Introduction
- - -
-

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

-
- - -
Release Timeline
- -
-

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 - development philosophy. The release schedule is roughly as follows: -

-
    -
  1. 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.
    2. -
  2. Create release branch and begin release process.
    3. -
  3. Send out pre-release for first round of testing. Testing will last 7-10 days. -During the first round of testing, regressions should be found and fixed. Patches -are merged from mainline to the release branch.
    4. -
  4. Generate and send out second pre-release. Bugs found during this time will -not be fixed unless absolutely critical. Bugs introduce by patches merged in -will be fixed and if so, a 3rd round of testing is needed.
    5. -
  5. The release notes should be updated during the first and second round of -pre-release testing.
    6. -
  6. Finally, release!
    7. -
-
- - - -
Release Process
- - -
-
    -
  1. Release Administrative Tasks
    2. -
      -
    1. Create Release Branch
      2. -
    2. Update Version Numbers
      3. -
    -
  2. Building the Release
    3. -
      -
    1. Build the LLVM Source Distributions
      2. -
    2. Build LLVM
      3. -
    3. Build the LLVM-GCC Binary Distribution
      4. -
    4. Build the Clang Binary Distribution
      5. -
    5. Target Specific Build Details
      6. -
    - -
  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. Update Documentation
      2. -
    2. Tag the LLVM Release Branch
      3. -
    3. Update the LLVM Demo Page
      4. -
    4. Update the LLVM Website
      5. -
    5. Announce the Release
      6. -
    - -
-
- - -
-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 or buildbot results.

    2. -
  2. -

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

    3. -
  3. -

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

    - -
    -
    -svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
-         https://llvm.org/svn/llvm-project/llvm/branches/release_XX
-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
-
    -
    - -
  4. -

    Advise developers they can work on Subversion HEAD again.

    5. - -
  5. -

    The Release Manager 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:

    - -
    -
    -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
-
    -
    6. - -
-
- - -
Update LLVM Version
-
-

- After creating the LLVM release branch, update the release branches' - autoconf/configure.ac version from X.Xsvn to just X.X. Update it on mainline - 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
-
-

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

- -
-
-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
-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 | gzip > clang-X.X.tar.gz
-
-
-
- - -
-Building the Release
- -
-The build of llvm, llvm-gcc, and clang must be free -of errors and warnings in both debug, release, and release-asserts builds. -If all builds are clean, then the release passes build qualification. - -
    -
  1. debug: ENABLE_OPTIMIZED=0
    2. -
  2. release: ENABLE_OPTIMIZED=1
    3. -
  3. release-asserts: ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1
    4. -
-
- - -
Build LLVM
-
-

- Build both debug, release (optimized), and release-asserts versions of - LLVM on all supported platforms. Direction to build llvm are - here. -

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

- Creating the LLVM GCC binary distribution (release/optimized) requires - performing the following steps for each supported platform: -

- -
    -
  1. - Build the LLVM GCC front-end by following the directions in the README.LLVM - file. The frontend must be compiled with c, c++, objc (mac only), - objc++ (mac only) and fortran support.
    2. -
  2. Please boostrap as well.
    3. -
  3. Be sure to build with LLVM_VERSION_INFO=X.X, where X is the major and - minor release numbers. -
    4. - -
  4. - 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.2-2.6-x86-linux-RHEL4. Archive and compress the new directory. -
    5. -
-
- - -
Build Clang -Binary Distribution
-
-

- Creating the Clang binary distribution (debug/release/release-asserts) requires - performing the following steps for each supported platform: -

- -
    -
  1. - Build clang according to the directions - here. -
    2. - -
  2. Build both a debug and release version of clang, but the binary - will be a release build.
    3. - -
  3. - Package clang (details to follow). -
    4. -
-
- - - -
Target Specific Build -Details
-
-

- The table below specifies which compilers are used for each arch/os combination - when qualifying the build of llvm, llvm-gcc, clang. -

- -

- - - - - - - - - - -
ArchitectureOScompiler
x86-32Mac OS 10.5gcc 4.0.1
x86-32Linuxgcc 4.2.X, gcc 4.3.X
x86-32FreeBSDgcc 4.2.X
x86-32mingwgcc 3.4.5
x86-64Mac OS 10.5gcc 4.0.1
x86-64Linuxgcc 4.2.X, gcc 4.3.X
x86-64FreeBSDgcc 4.2.X
-

- -
- - - -
-Building the Release
- -
- A release is qualified when it has no regressions from the previous - release (or baseline). Regressions are related to correctness only and not - performance at this time. Regressions are new failures in the set of tests that - are used to qualify each product and only include things on the list. - Ultimately, there is no end to the number of possible bugs in a release. We - need a very concrete and definitive release criteria that ensures we have - monotonically improving quality on some metric. The metric we use is - described below. This doesn't mean that we don't care about other things, - but this are things that must be satisfied before a release can go out -
- - - -
Qualify LLVM
-
-

- LLVM is qualified when it has a clean dejagnu test run without a frontend and - it has no regressions when using either llvm-gcc or clang - with the test-suite from the previous release. -

-
- - -
Qualify LLVM-GCC
-
-

- LLVM-GCC is qualified when front-end specific tests in the - llvm dejagnu test suite all pass and there are no regressions in - the test-suite.

-

We do not use the gcc dejagnu test suite as release criteria.

-
- - -
Qualify Clang
-
- Clang is qualified when front-end specific tests in the - llvm dejagnu test suite all pass, clang's own test suite passes - cleanly, and there are no regressions in the test-suite.

-
- - -
Specific Target -Qualification Details
-
-

- - - - - - - -
ArchitectureOSllvm-gcc baselineclang baseline - tests
x86-32Linuxlast releaselast releasellvm dejagnu, clang tests, test-suite (including spec)
x86-32FreeBSDnonelast releasellvm dejagnu, clang tests, test-suite
x86-32mingwlast releasenoneQT
x86-64Mac OS 10.Xlast releaselast releasellvm dejagnu, clang tests, test-suite (including spec)
x86-64Linuxlast releaselast releasellvm dejagnu, clang tests, test-suite (including spec)
x86-64FreeBSDnonelast releasellvm dejagnu, clang tests, test-suite

-
- - -
Community Testing
-
-

- Once all testing has been completed and appropriate bugs filed, the pre-release - tar balls may be put on the website and the LLVM community is notified. Ask that - all LLVM developers test the release in 2 ways:

-
    -
  1. Download llvm-X.X, llvm-test-X.X, and the appropriate llvm-gcc4 - and/or clang binary. Build LLVM. - Run "make check" and the full llvm-test suite (make TEST=nightly report).
    2. -
  2. Download llvm-X.X, llvm-test-X.X, and the llvm-gcc4 and/or clang source. - Compile everything. Run "make check" and the full llvm-test suite (make TEST=nightly - report).
    3. -
-

Ask LLVM developers to submit the report and make check results to the list. - Attempt to verify that there are no regressions from the previous release. - The results are not used to qualify a release, but to spot other potential - problems. For unsupported targets, verify that make check at least is - clean.

- -

During the first round of testing time, - all regressions must be fixed before the second pre-release is created.

- -

If this is the second round of testing, this is only to ensure the bug - fixes previously merged in have not created new major problems. This is not - the time to solve additional and unrelated bugs. If no patches are merged in, - the release is determined to be ready and the release manager may move onto - the next step. -

-
- - -
Release Patch Rules -
-
-

- Below are the rules regarding patching the release branch.

-

-

  • Patches applied to the release branch are only applied by the release - manager.
    • -
  • During the first round of testing, patches that fix regressions or that - are small and relatively risk free (verified by the appropriate code owner) - are applied to the branch. Code owners are asked to be very conservative in - approving patches for the branch and we reserve the right to reject any patch - that does not fix a regression as previously defined.
    • -
  • During the remaining rounds of testing, only patches that fix regressions - may be applied.
    • - -

    -
    - - - -
    Release Final Tasks -
    -
    -

    - The final stages of the release process involving taging the release branch, - updating documentation that refers to the release, and updating the demo - page.

    -

    FIXME: Add a note if anything needs to be done to the clang website. - Eventually the websites will be merged hopefully.

    -
    - - - -
    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 Subversion and - changes in basic system requirements. Merge both changes from mainline into - the release branch. -

    -
    - - -
    Tag the Release Branch
    -
    -

    Tag the release branch using the following procedure:

    -
    -
    -svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XX \
-         https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_XX
-svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX \
-         https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_XX
-svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \
-         https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_XX
-
    -
    -
    - - - - -
    Update the LLVM Demo Page
    -
    -

    - The LLVM demo page must be updated to use the new release. This consists of - using the llvm-gcc binary and building LLVM. Update the website demo page - configuration to use the new release.

    -
    - - -
    Update the LLVM Website
    -
    -

    - The website must be updated before the release announcement is sent out. Here is - what to do:

    -
      -
    1. Check out the website module from CVS.
      2. -
    2. Create a new subdirectory X.X in the releases directory.
      3. -
    3. Commit the llvm, test-suite, llvm-gcc source, - clang source, clang binaries, - and llvm-gcc binaries in this new directory.
      4. -
    4. Copy and commit the llvm/docs and LICENSE.txt - files into this new directory. The docs should be built with BUILD_FOR_WEBSITE=1.
      5. -
    5. Commit the index.html to the release/X.X directory to redirect (use from previous - release.
      6. -
    6. Update the releases/download.html file with the new release.
      7. -
    7. Update the releases/index.html with the new release and link to - release documentation.
      8. -
    8. Finally, update the main page (index.html and sidebar) to - point to the new release and release announcement. Make sure this all gets - committed back into Subversion.
      9. -
    -
    - - -
    Announce the Release
    -
    -

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

    -
    - - -
    -
    - Valid CSS - Valid HTML 4.01 - The LLVM Compiler Infrastructure -
    - Last modified: $Date$ -
    - - -- cgit v1.2.3