diff --git a/llvm/docs/HowToReleaseLLVM.html b/llvm/docs/HowToReleaseLLVM.html
index b6a5fd458cd9..0fd5903a10ad 100644
--- a/llvm/docs/HowToReleaseLLVM.html
+++ b/llvm/docs/HowToReleaseLLVM.html
@@ -10,14 +10,15 @@
How To Release LLVM To The Public
- Introduction
+ - Qualification Criteria
- Release Timeline
- Release Process
- - Distribution Targets
@@ -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:
-
-
-
- - Successful configure and build.
- - Clean 'make check'.
- - No regressions in the testsuite from the previous release. This may
- include performance regressions for major benchmarks.
-
-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:
+
-- Set code freeze and branch creation date for 3 months after last release
+
- 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.
- Create release branch and begin release process.
- Send out pre-release for first round of testing. Testing will last 7-10 days.
@@ -71,44 +63,76 @@ pre-release testing.
-
-
-
+
+
+
+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.
+
+
+
+
Branch the Subversion HEAD using the following procedure:
-
-
Verify that the current Subversion HEAD is in decent shape by examining nightly
- tester results.
+ Verify that the current Subversion HEAD is in decent shape by examining
+ nightly tester or buildbot results.
-
Request all developers to refrain from committing. Offenders get commit
rights taken away (temporarily).
-
-
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
-
+
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.
-
+
- 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
-
+
+
+
+Info about this. Criteria for a successful build.
+
+
+
+
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
-
+
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.
-
+
- 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:
+
+ -
+ Instructions how to build it.
+
+
+ -
+ Instructions on how to package
+
+
+
+
+
+
+
+
- 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.
+
+
+
+
+
+How to qualify the release.
+
+
+
+
+
+
+
-
+
- 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.
-
+
- 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.
-
+ Details.
-
+
+
+
+
+
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.
+
+
+
+
-
+
+
+
+
+
+
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 \
-
+
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 \
-
+
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 \
-
+
Have Chris send out the release announcement when everything is finished.
-
-
-
-
-
-
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:
-
-
-
- - 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
- - 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.
- - 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
- - The distribution directory is then traversed and all CVS or
- .svn directories are removed. You see: Eliminating CVS/.svn
- directories from distribution
- - The recursive dist-hook target is executed. This gives each
- directory a chance to modify the distribution in some way (more on this
- below).
- - The distribution directory is traversed and the correct file
- permissions and modes are set based on the type of file.
-
-
-
- To control the process of making the distribution directory correctly, each
- Makefile can utilize two features:
-
-
-
- - 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.
- - 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:
-
-
-
- - 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.
- - 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.
- - The target can fail if any of the things it does fail. Error messages
- should indicate what went wrong.
-
-
-
-
-
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:
-
-
-
- - 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).
- - removes any pre-existing _distcheckdir at the top level.
- - creates a new _distcheckdir directory at the top level.
- - creates a build subdirectory and an install
- subdirectory under _distcheckdir.
- - unzips and untars the release tarball into _distcheckdir,
- creating LLVM-1.7 directory (from the tarball).
- - 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.
- - runs make all
- - runs make check
- - runs make install
- - runs make uninstall
- - runs make dist
- - runs make clean
- - runs make dist-clean
-
-
-
- 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.
-
-
-