-<!-- *********************************************************************** -->
-<div class="doc_section"><a name="dist_targets">Distribution Targets</a></div>
-<!-- *********************************************************************** -->
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">Overview</div>
-<div class="doc_text">
- <p>
- 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.
- </p>
-
- <ul>
- <li><b>distdir</b> - builds the distribution directory from which the
- distribution will be packaged</li>
- <li><b>dist</b> - builds each of the distribution tarballs (tar.gz,
- tar.bzip2, .zip). These can be built individually as well, with separate
- targets.</li>
- <li><b>dist-check</b> - this is identical to <tt>dist</tt> but includes a
- check on the distribution that ensures the tarball can: unpack
- successfully, compile correctly, pass '<tt>make check</tt>', and pass
- '<tt>make clean</tt>'.</li>
- <li><b>dist-clean</b>- this just does a normal clean but also cleans up the
- stuff generated by the other three <tt>dist</tt> targets (above).</li>
- </ul>
-
- <p>
- Okay, that's the basic functionality. When making a release, we want to ensure
- that the tree you build the distribution from passes
- <tt>dist-check</tt>. Beyond fixing the usual bugs, there is generally one
- impediment to making the release in this fashion: missing files. The
- <tt>dist-check</tt> 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 <tt>make check</tt>.
- </p>
-</div>
-
-<!-- ======================================================================= -->
-
-<div class="doc_subsection">distdir</div>
-<div class="doc_text">
- <p>
- 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:
- </p>
-
- <ol>
- <li>First, if there was an old distribution directory (for the current
- release), it is removed in its entirety and you see <tt>Removing old
- LLVM-1.7</tt></li>
- <li>Second, it issues a <tt>make all ENABLE_OPTIMIZED=3D1</tt> 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
- <tt>distdir</tt> target fails too. This is preceded by the message
- <tt>Making 'all' to verify build</tt>.</li>
- <li>Next, it traverses your source tree and copies it to a new directory
- that has the name of the release (<tt>LLVM-M.m</tt> 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 <tt>Building Distribution Directory
- LLVM-1.7</tt></li>
- <li>The distribution directory is then traversed and all <tt>CVS</tt> or
- <tt>.svn</tt> directories are removed. You see: <tt>Eliminating CVS/.svn
- directories from distribution</tt></li>
- <li>The recursive <tt>dist-hook</tt> target is executed. This gives each
- directory a chance to modify the distribution in some way (more on this
- below).</li>
- <li>The distribution directory is traversed and the correct file
- permissions and modes are set based on the type of file.</li>
- </ol>
-
- <p>
- To control the process of making the distribution directory correctly, each
- Makefile can utilize two features:
- </p>
-
- <ol>
- <li><b><tt>EXTRA_DIST</tt></B> - this make variable specifies which files
- it should distribute. By default, all source files are automatically
- included for distribution as well as certain <tt>well known</tt> files
- (see DistAlways variable in Makefile.rules for details). Each Makefile
- specifies, via the <tt>EXTRA_DIST</tt> variable, which additional files
- need to be distributed. Only those files that are needed to build LLVM
- should be added to <tt>EXTRA_DIST</tt>. <tt>EXTRA_DIST</tt> contains a
- list of file or directory names that should be distributed. For example,
- the top level Makefile contains <tt>EXTRA_DIST := test llvm.spec
- include</tt>. This means that in addition to regular things that are
- distributed at the top level (<tt>CREDITS.txt, LICENSE.txt</tt>, etc.)
- the distribution should contain the entire <tt>test</tt> and
- <tt>include</tt> directories as well as the <tt>llvm.spec</tt> file.</li>
- <li><b><tt>dist-hook</tt></B> - 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 <tt>include</tt>
- subtree that are generated by the configure script. These should not be
- distributed. Similarly, any <tt>dist-hook</tt> 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.</li>
- </ol>
-
- <p>
- You will see various messages if things go wrong:
- </p>
-
- <ol>
- <li>During the copying process, any files that are missing will be flagged
- with: <tt>===== WARNING: Distribution Source 'dir/file' Not Found!</tt>
- These must be corrected by either adding the file or removing it from
- <tt>EXTRA_DIST</tt>.</li>
- <li>If you build the distribution with <tt>VERBOSE=1</tt>, then you might
- also see: <tt>Skipping non-existent 'dir/file'</tt> in certain cases
- where it's okay to skip the file.</li>
- <li>The target can fail if any of the things it does fail. Error messages
- should indicate what went wrong.</li>
- </ol>
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">dist</div>
-<div class="doc_text">
- <p>
- This target does exactly what <tt>distdir</tt> target does, but also includes
- assembling the tarballs. There are actually four related targets here:
- </p>
-
- <ul>
- <li><b><tt>dist-gzip</tt></b>: package the gzipped distribution tar
- file. The distribution directory is packaged into a single file ending
- in <tt>.tar.gz</tt> which is gzip compressed.</li>
- <li><b><tt>dist-bzip2</tt></b>: package the bzip2 distribution tar file.
- The distribution directory is packaged into a single file ending in
- <tt>.tar.bzip2</tt> which is bzip2 compressed.</li>
- <li><b><tt>dist-zip</tt></b>: package the zip distribution file. The
- distribution directory is packaged into a single file ending in
- <tt>.zip</tt> which is zip compressed.</li>
- <li><b><tt>dist</tt></b>: does all three, dist-gzip, dist-bzip2,
- dist-zip</li>
- </ul>
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">dist-check</div>
-<div class="doc_text">
- <p>
- 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:
- </p>
-
- <ol>
- <li>It depends on the <tt>dist-gzip</tt> target which, if it hasn't already
- been built, builds the gzip tar bundle (see dist and distdir
- above).</li>
- <li>removes any pre-existing <tt>_distcheckdir</tt> at the top level.</li>
- <li>creates a new <tt>_distcheckdir</tt> directory at the top level.</li>
- <li>creates a <tt>build</tt> subdirectory and an <tt>install</tt>
- subdirectory under <tt>_distcheckdir</tt>.</li>
- <li>unzips and untars the release tarball into <tt>_distcheckdir</tt>,
- creating <tt>LLVM-1.7</tt> directory (from the tarball).</li>
- <li>in the build subdirectory, it configures with appropriate options to
- build from the unpacked source tarball into the <tt>build</tt> directory
- with installation in the <tt>install</tt> directory.</li>
- <li>runs <tt>make all</tt></li>
- <li>runs <tt>make </tt><tt>check</tt></li>
- <li>runs <tt>make install</tt></li>
- <li>runs <tt>make uninstall</tt></li>
- <li>runs <tt>make dist</tt></li>
- <li>runs <tt>make clean</tt></li>
- <li>runs <tt>make dist-clean</tt></li>
- </ol>
-
- <p>
- If it can pass all that, the distribution will be deemed distribution worth y
- and you will see:
- </p>
-
- <pre>===== LLVM-1.7.tar.gz Ready For Distribution =====</pre>
-
- <p>
- 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.
- </p>
-
- <p>
- A note about disk space: using <tt>dist-check</tt> will easily triple the
- amount of disk space your build tree is using. You might want to check
- available space before you begin.
- </p>
-</div>
-
-<!-- ======================================================================= -->
-<div class="doc_subsection">dist-clean</div>
-<div class="doc_text">
- <p>
- In addition to doing a normal <tt>clean</tt>, this target will clean up the
- files and directories created by the distribution targets. In particular the
- distribution directory (<tt>LLVM-X.X</tt>), check directory
- (<tt>_distcheckdir</tt>), 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.
- </p>
-</div>
-