diff --git a/docs/HowToReleaseLLVM.html b/docs/HowToReleaseLLVM.html index 7d9f196da0e..0648bc8842c 100644 --- a/docs/HowToReleaseLLVM.html +++ b/docs/HowToReleaseLLVM.html @@ -12,9 +12,11 @@
  1. Introduction
  2. Release Process
    3. +
  3. Distribution Make Targets
-

Written by Reid Spencer

+

Written by Reid Spencer, + John Criswell

@@ -273,7 +275,6 @@ fix for the release.
Release

Release the distribution tarball to the public. This consists of generating @@ -290,6 +291,172 @@ fix for the release.

--> + +
Distribution Make 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.

+
+