Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / e15192b36bb5e99838d3f70bf79f7b8bed7a75b9 / . / docs / HowToReleaseLLVM.html
blob: b6a5fd458cd9a61d31a88f3d4783909731c05033 [file] [log] [blame]
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <title>How To Release LLVM To The Public</title>
6 <link rel="stylesheet" href="llvm.css" type="text/css">
7</head>
8<body>
9
10<div class="doc_title">How To Release LLVM To The Public</div>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]11<ol>
12 <li><a href="#introduction">Introduction</a></li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]13 <li><a href="#introduction">Release Timeline</a></li>
Misha Brukman8ebd7f92006-04-10 21:43:05 +0000[diff] [blame]14 <li><a href="#process">Release Process</a></li>
Reid Spencer852239c2006-04-11 22:02:18 +0000[diff] [blame]15 <li><a href="#dist_targets">Distribution Targets</a></li>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]16</ol>
17<div class="doc_author">
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]18 <p>Written by <a href="mailto:rspencer@x10sys.com">Reid Spencer</a>,
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]19 <a href="mailto:criswell@cs.uiuc.edu">John Criswell</a>,
20 <a href="mailto:tonic@nondot.org">Tanya Lattner</a></p>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]21</div>
22
23<!-- *********************************************************************** -->
24<div class="doc_section"><a name="introduction">Introduction</a></div>
25<!-- *********************************************************************** -->
26
27<div class="doc_text">
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]28 <p>
29 This document collects information about successfully releasing LLVM to the
30 public. It is the release manager's guide to ensuring that a high quality
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]31 build of LLVM is released.
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]32 </p>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]33
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]34 <p>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]35 The following is the basic criteria for releasing LLVM:
Bill Wendlingd4fb7932007-07-23 04:44:02 +0000[diff] [blame]36 </p>
37
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]38 <ol>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]39 <li>Successful configure and build.</li>
40 <li>Clean 'make check'.</li>
41 <li>No regressions in the testsuite from the previous release. This may
42 include performance regressions for major benchmarks.</li>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]43 </ol>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]44</div>
45
46<!-- *********************************************************************** -->
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]47<div class="doc_section"><a name="process">Release Timeline</a></div>
48<!-- *********************************************************************** -->
49<div class="doc_text">
50The release manager should attempt to have a release every 3-4 months because LLVM
51does time based releases (instead of feature based). The release schedule should
52be roughly as follows:
53<ol>
54<li>Set code freeze and branch creation date for 3 months after last release
55date. Announce release schedule to the LLVM community and update the website.</li>
56<li>Create release branch and begin release process. </li>
57<li>Send out pre-release for first round of testing. Testing will last 7-10 days.
58During the first round of testing, regressions should be found and fixed. Patches
59are merged from mainline to the release branch.</li>
60<li>Generate and send out second pre-release. Bugs found during this time will
61not be fixed unless absolutely critical. Bugs introduce by patches merged in
62will be fixed and if so, a 3rd round of testing is needed.</li>
63<li>The release notes should be updated during the first and second round of
64pre-release testing.</li>
65<li>Finally, release!</li>
66</ol>
67</div>
68
69
70<!-- *********************************************************************** -->
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]71<div class="doc_section"><a name="process">Release Process</a></div>
72<!-- *********************************************************************** -->
73
74<!-- ======================================================================= -->
75<div class="doc_subsection"><a name="overview">Process Overview</a></div>
76<div class="doc_text">
77 <ol>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]78 <li><a href="#branch">Create Release Branch</a></li>
Tanya Lattner9ceece52006-08-10 00:23:05 +0000[diff] [blame]79 <li><a href="#verchanges">Update LLVM Version </a></li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]80 <li><a href="#dist">Build the LLVM Source Distributions</a></li>
Misha Brukman8ebd7f92006-04-10 21:43:05 +0000[diff] [blame]81 <li><a href="#build">Build LLVM</a></li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]82 <li><a href="#llvmgccbin">Build the LLVM GCC Binary Distribution</a></li>
83 <li><a href="#rpm">Build RPM Packages (optional)</a></li>
Misha Brukman8ebd7f92006-04-10 21:43:05 +0000[diff] [blame]84 <li><a href="#check">Run 'make check'</a></li>
85 <li><a href="#test">Run LLVM Test Suite</a></li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]86 <li><a href="#prerelease">Pre-Release Testing</a></li>
87 <li><a href="#tag">Tag the LLVM Release Branch</a></li>
88 <li><a href="#updocs">Update Documentation</a></li>
89 <li><a href="#updemo">Update the LLVM Demo Page</a></li>
Tanya Lattner9ceece52006-08-10 00:23:05 +0000[diff] [blame]90 <li><a href="#webupdates">Update the LLVM Website</a></li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]91 <li><a href="#announce">Announce the Release</a></li>
92
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]93 </ol>
94</div>
95
96<!-- ======================================================================= -->
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]97<div class="doc_subsection"><a name="branch">Create Release Branch</a></div>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]98<div class="doc_text">
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]99<p>Branch the Subversion HEAD using the following procedure:</p>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]100 <ol>
101 <li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]102 <p>Verify that the current Subversion HEAD is in decent shape by examining nightly
103 tester results.</p></li>
104 <li>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]105 <p>Request all developers to refrain from committing. Offenders get commit
106 rights taken away (temporarily).</p></li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]107 <li>
Bill Wendlingc8be0a42008-07-22 01:37:48 +0000[diff] [blame]108 <p> Create the release branch for <tt>llvm</tt>, <tt>llvm-gcc4.2</tt>, and
109 the <tt>test-suite</tt>. The branch name will be <tt>release_XX</tt>,
110 where <tt>XX</tt> is the major and minor release numbers. These branches can
111 be created without checking out anything from subversion.
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]112 </p>
113
114 <div class="doc_code">
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]115<pre>
116svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]117 https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XX</i>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]118svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/trunk \
119 https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i>
120svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]121 https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i>
122</pre>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]123 </div>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]124
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]125 <li>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]126 <p>Advise developers they can work on Subversion HEAD again.</p></li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]127
128 <li>
129 <p>The Release Manager should switch to the release branch (as all changes
130 to the release will now be done in the branch). The easiest way to do this
131 is to grab another working copy using the following commands:</p>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]132
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]133<div class="doc_code">
134<pre>
135svn co https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XX</i>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]136svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]137svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i>
138</pre>
Bill Wendlingd4fb7932007-07-23 04:44:02 +0000[diff] [blame]139</div></li>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]140
Bill Wendlingd4fb7932007-07-23 04:44:02 +0000[diff] [blame]141 </ol>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]142</div>
143
144<!-- ======================================================================= -->
Tanya Lattner9ceece52006-08-10 00:23:05 +0000[diff] [blame]145<div class="doc_subsection"><a name="verchanges">Update LLVM Version</a></div>
146<div class="doc_text">
147 <p>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]148 After creating the LLVM release branch, update the release branches'
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]149 autoconf/configure.ac version from X.Xsvn to just X.X. Update it on mainline
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]150 as well to be the next version (X.X+1svn). Regenerated the configure script
151 for both. This must be done for both llvm and the test-suite.
Tanya Lattner9ceece52006-08-10 00:23:05 +0000[diff] [blame]152 </p>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]153 <p>In addition, the version number of all the Bugzilla components must be
154 updated for the next release.
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]155 </p>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]156</div>
157
158<!-- ======================================================================= -->
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]159<div class="doc_subsection"><a name="dist">Build the LLVM Source Distributions</a></div>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]160<div class="doc_text">
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]161 <p>
162 Create source distributions for LLVM, LLVM GCC, and the LLVM Test Suite by
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]163 exporting the source from Subversion and archiving it. This can be done with
164 the following commands:
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]165 </p>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]166
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]167<div class="doc_code">
168<pre>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]169svn export https://llvm.org/svn/llvm-project/llvm/branches/release_<i>XX</i> llvm-X.X
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]170svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_<i>XX</i> llvm-gcc4.2-X.X.source
171svn export https://llvm.org/svn/llvm-project/test-suite/branches/release_<i>XX</i> llvm-test-X.X
172tar -cvf - llvm-X.X | gzip &gt; llvm-X.X.tar.gz
173tar -cvf - llvm-test-X.X | gzip &gt; llvm-test-X.X.tar.gz
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]174tar -cvf - llvm-gcc4.2-X.X.source | gzip &gt; llvm-gcc-4.2-X.X.source.tar.gz
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]175</pre>
176</div>
Reid Spencer103febe2006-08-16 00:54:50 +0000[diff] [blame]177</div>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]178
Reid Spencer103febe2006-08-16 00:54:50 +0000[diff] [blame]179<!-- ======================================================================= -->
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]180<div class="doc_subsection"><a name="build">Build LLVM</a></div>
181<div class="doc_text">
182 <p>
183 Build both debug and release (optimized) versions of LLVM on all
184 platforms. Ensure the build is warning and error free on each platform.
185 Note that when building the LLVM GCC Binary, use a release build of LLVM.
186 </p>
187</div>
188
189<!-- ======================================================================= -->
190<div class="doc_subsection"><a name="llvmgccbin">Build the LLVM GCC Binary Distribution</a></div>
191<div class="doc_text">
192 <p>
193 Creating the LLVM GCC binary distribution (release/optimized) requires
194 performing the following steps for each supported platform:
195 </p>
196
197 <ol>
198 <li>
199 Build the LLVM GCC front-end by following the directions in the README.LLVM
200 file. Be sure to build with LLVM_VERSION_INFO=X.X, where X is the major and
201 minor release numbers.
202 </li>
203
204 <li>
205 Copy the installation directory to a directory named for the specific target.
206 For example on Red Hat Enterprise Linux, the directory would be named
207 <tt>llvm-gcc4.0-2.1-x86-linux-RHEL4</tt>. Archive and compress the new directory.
208 </li>
209 </ol>
210</div>
211
212<!-- ======================================================================= -->
213<div class="doc_subsection"><a name="check">Run 'make check'</a></div>
214<div class="doc_text">
215 <p>
216 Using the newly built llvm-gcc and llvm, reconfigure llvm to locate llvm-gcc.
217 Run <tt>make check</tt> and ensure there are no unexpected failures. If there
218 are, resolve the failures or file a bug. If there is a fix commited to mainline,
219 merge back into the release branch, and restart testing by
220 <a href="#build">re-building LLVM</a> and <a href="#build">llvm-gcc</a>. If no
221 fix will be made, XFAIL the test and commit back to the release branch.
222 </p>
223
224 <p>
225 Ensure that '<tt>make check</tt>' passes on all platforms for all targets. The
226 test suite must complete with "0 unexpected failures" before sending out the
227 pre-releases for testing.
228 </p>
229</div>
230
231<!-- ======================================================================= -->
232<div class="doc_subsection"><a name="test">LLVM Test Suite</a></div>
233<div class="doc_text">
234 <p>
235 Run the <tt>llvm-test</tt> suite and ensure there are no unacceptable
236 failures. Unacceptable failures are regression from the previous release
237 and (optionally) major performance regressions from the previous release.
238 If a regression is found a bug is filled, but the pre-releases may still go
239 out.</p>
240</div>
241
242<!-- ======================================================================= -->
Reid Spencer103febe2006-08-16 00:54:50 +0000[diff] [blame]243<div class="doc_subsection"><a name="rpm">Building RPM packages (optional)</a></div>
244<div class="doc_text">
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]245 <p>
246 You can, optionally, create source and binary RPM packages for LLVM. These may
247 make it easier to get LLVM into a distribution. This can be done with the
248 following commands:
249 </p>
250
251<div class="doc_code">
252<pre>
253make dist # Build the distribution source tarball
254make dist-check # Check that the source tarball can build itself.
255cp llvm-M.m.tar.gz /usr/src/redhat/SOURCES # Required by rpmbuild
256make srpm # for source rpm
257make rpm # for binary rpm
258</pre>
259</div>
260
261 <p>
262 First, use <tt>make dist</tt> to simply build the distribution. Any failures
263 need to be corrected (on the branch). Once <tt>make dist</tt> can be
264 successful, do <tt>make dist-check</tt>. This target will do the same thing as
265 the 'dist' target but also test that distribution to make sure it can build
266 itself and runs <tt>make check</tt> as well. This ensures that needed files
267 are not missing and that the src tarball can be successfully unpacked, built,
268 installed, and cleaned. Once you have a reliable tarball, you need to copy it
269 to the <tt>/usr/src/redhat/SOURCES</tt> directory which is a requirement of
270 the rpmbuild tool. The last two <tt>make</tt> invocations just run rpmbuild to
271 build either a source (<tt>srpm</tt>) or binary (<tt>rpm</tt>) RPM package.
272 </p>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]273</div>
274
275<!-- ======================================================================= -->
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]276<div class="doc_subsection"><a name="prerelease">Pre-Release Testing</a></div>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]277<div class="doc_text">
278 <p>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]279 Once all testing has been completed and appropriate bugs filed, the pre-release
280 tar balls may be put on the website and the LLVM community is notified. Ask that
281 all LLVM developers test the release in 2 ways:</p>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]282 <ol>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]283 <li>Download llvm-X.X, llvm-test-X.X, and the appropriate llvm-gcc4 binary.
284 Run "make check" and the full llvm-test suite (make TEST=nightly report).<li>
285 <li>Download llvm-X.X, llvm-test-X.X, and the llvm-gcc4 source. Compile
286 everything. Run "make check" and the full llvm-test suite (make TEST=nightly
287 report).</li>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]288 </ol>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]289 <p>Ask LLVM developers to submit the report and make check results to the list.
290 Verify that there are no regressions from the previous release. For
291 unsupported targets, verify that make check at least is clean.</p>
292
293 <p>The first round of pre-release testing will be the longest. During this time,
294 all regressions must be fixed before the second pre-release is created (repeat
295 steps 4-8).</p>
296
297 <p>If this is the second round of testing, this is only to ensure the bug fixes
298 previously merged in have not created new major problems. This is not the time
299 to solve additional and unrelated bugs. If no patches are merged in, the release
300 is determined to be ready and the release manager may move onto the next step.</p>
John Criswellfe48c802006-04-11 20:24:28 +0000[diff] [blame]301</div>
302
Tanya Lattner9ceece52006-08-10 00:23:05 +0000[diff] [blame]303
304<!-- ======================================================================= -->
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]305<div class="doc_subsection"><a name="tag">Tag the Release Branch</a></div>
306<div class="doc_text">
307 <p>Tag the release branch using the following procedure:</p>
308<div class="doc_code">
309<pre>
310svn copy https://llvm.org/svn/llvm-project/llvm/branches/release_XX \
311 https://llvm.org/svn/llvm-project/llvm/tags/RELEASE_<i>XX</i>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]312svn copy https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX \
313 https://llvm.org/svn/llvm-project/llvm-gcc-4.2/tags/RELEASE_<i>XX</i>
314svn copy https://llvm.org/svn/llvm-project/test-suite/branches/release_XX \
315 https://llvm.org/svn/llvm-project/test-suite/tags/RELEASE_<i>XX</i>
316</pre>
317</div>
318</div>
319
320<!-- ======================================================================= -->
321<div class="doc_subsection"><a name="updocs">Update Documentation</a></div>
322<div class="doc_text">
323 <p>
324 Review the documentation and ensure that it is up to date. The Release Notes
325 must be updated to reflect bug fixes, new known issues, and changes in the
326 list of supported platforms. The Getting Started Guide should be updated to
327 reflect the new release version number tag avaiable from Subversion and
328 changes in basic system requirements. Merge both changes from mainline into
329 the release branch.
330 </p>
331</div>
332
333<!-- ======================================================================= -->
334<div class="doc_subsection"><a name="updemo">Update the LLVM Demo Page</a></div>
335<div class="doc_text">
336 <p>
337 The LLVM demo page must be updated to use the new release. This consists of
338 using the llvm-gcc binary and building LLVM. Update the website demo page
339 configuration to use the new release.</p>
340</div>
341
342<!-- ======================================================================= -->
Tanya Lattner9ceece52006-08-10 00:23:05 +0000[diff] [blame]343<div class="doc_subsection"><a name="webupdates">Update the LLVM Website</a></div>
344<div class="doc_text">
345 <p>
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]346 The website must be updated before the release announcement is sent out. Here is
347 what to do:</p>
348 <ol>
349 <li> Check out the <tt>website</tt> module from CVS. </li>
350 <li> Create a new subdirectory X.X in the releases directory. </li>
351 <li> Commit the <tt>llvm</tt>, <tt>test-suite</tt>, <tt>llvm-gcc</tt> source,
352 and <tt>llvm-gcc</tt> binaries in this new directory. </li>
353 <li> Copy and commit the <tt>llvm/docs</tt> and <tt>LICENSE.txt</tt>
354 files into this new directory. The docs should be built with BUILD_FOR_WEBSITE=1.</li>
355 <li> Commit the index.html to the release/X.X directory to redirect (use from previous
356 release. </li>
357 <li> Update the <tt>releases/download.html</tt> file with the new release. </li>
358 <li>Update the <tt>releases/index.html</tt> with the new release and link to
359 release documentation.</li>
360 <li> Finally, update the main page (<tt>index.html</tt> and sidebar) to
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]361 point to the new release and release announcement. Make sure this all gets
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]362 commited back into Subversion.</li>
363 </ol>
Tanya Lattner9ceece52006-08-10 00:23:05 +0000[diff] [blame]364</div>
365
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]366<!-- ======================================================================= -->
367<div class="doc_subsection"><a name="announce">Announce the Release</a></div>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]368<div class="doc_text">
Tanya Lattner76385652007-09-28 22:50:54 +0000[diff] [blame]369 <p>Have Chris send out the release announcement when everything is finished.</p>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]370</div>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]371
372<!-- *********************************************************************** -->
Reid Spencer852239c2006-04-11 22:02:18 +0000[diff] [blame]373<div class="doc_section"><a name="dist_targets">Distribution Targets</a></div>
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]374<!-- *********************************************************************** -->
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]375
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]376<!-- ======================================================================= -->
377<div class="doc_subsection">Overview</div>
378<div class="doc_text">
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]379 <p>
380 The first thing you need to understand is that there are multiple make targets
381 to support this feature. Here's an overview, we'll delve into the details
382 later.
383 </p>
384
385 <ul>
386 <li><b>distdir</b> - builds the distribution directory from which the
387 distribution will be packaged</li>
388 <li><b>dist</b> - builds each of the distribution tarballs (tar.gz,
389 tar.bzip2, .zip). These can be built individually as well, with separate
390 targets.</li>
391 <li><b>dist-check</b> - this is identical to <tt>dist</tt> but includes a
392 check on the distribution that ensures the tarball can: unpack
393 successfully, compile correctly, pass '<tt>make check</tt>', and pass
394 '<tt>make clean</tt>'.</li>
395 <li><b>dist-clean</b>- this just does a normal clean but also cleans up the
396 stuff generated by the other three <tt>dist</tt> targets (above).</li>
397 </ul>
398
399 <p>
400 Okay, that's the basic functionality. When making a release, we want to ensure
401 that the tree you build the distribution from passes
402 <tt>dist-check</tt>. Beyond fixing the usual bugs, there is generally one
403 impediment to making the release in this fashion: missing files. The
404 <tt>dist-check</tt> process guards against that possibility. It will either
405 fail and that failure will indicate what's missing, or it will succeed meaning
406 that it has proved that the tarballs can actually succeed in building LLVM
407 correctly and that it passes <tt>make check</tt>.
408 </p>
409</div>
410
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]411<!-- ======================================================================= -->
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]412
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]413<div class="doc_subsection">distdir</div>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]414<div class="doc_text">
415 <p>
416 This target builds the distribution directory which is the directory from
417 which the tarballs are generated. The distribution directory has the same
418 name as the release, e.g. LLVM-1.7). This target goes through the following
419 process:
420 </p>
421
422 <ol>
423 <li>First, if there was an old distribution directory (for the current
424 release), it is removed in its entirety and you see <tt>Removing old
425 LLVM-1.7</tt></li>
426 <li>Second, it issues a <tt>make all ENABLE_OPTIMIZED=3D1</tt> to ensure
427 that the everything in your tree can be built in release mode. Often
428 times there are discrepancies in building between debug and release
429 modes so it enforces release mode first. If that fails, the
430 <tt>distdir</tt> target fails too. This is preceded by the message
431 <tt>Making 'all' to verify build</tt>.</li>
432 <li>Next, it traverses your source tree and copies it to a new directory
433 that has the name of the release (<tt>LLVM-M.m</tt> in our current
434 case). This is the directory that will get tar'd. It contains all the
435 software that needs to be in the distribution. During the copying
Chris Lattnerb4d2cac2007-07-25 06:15:23 +0000[diff] [blame]436 process, it omits generated files, SVN directories, and any other
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]437 "cruft" that's in your build tree. This is done to eliminate the
438 possibility of huge distribution tarballs that include useless or
439 irrelevant stuff in them. This is the trickiest part of making the
440 distribution. Done manually you will either include stuff that
441 shouldn't be in the distribution or exclude stuff that should. This
442 step is preceded by the message <tt>Building Distribution Directory
443 LLVM-1.7</tt></li>
444 <li>The distribution directory is then traversed and all <tt>CVS</tt> or
445 <tt>.svn</tt> directories are removed. You see: <tt>Eliminating CVS/.svn
446 directories from distribution</tt></li>
447 <li>The recursive <tt>dist-hook</tt> target is executed. This gives each
448 directory a chance to modify the distribution in some way (more on this
449 below).</li>
450 <li>The distribution directory is traversed and the correct file
451 permissions and modes are set based on the type of file.</li>
452 </ol>
453
454 <p>
455 To control the process of making the distribution directory correctly, each
456 Makefile can utilize two features:
457 </p>
458
459 <ol>
460 <li><b><tt>EXTRA_DIST</tt></B> - this make variable specifies which files
461 it should distribute. By default, all source files are automatically
462 included for distribution as well as certain <tt>well known</tt> files
463 (see DistAlways variable in Makefile.rules for details). Each Makefile
464 specifies, via the <tt>EXTRA_DIST</tt> variable, which additional files
465 need to be distributed. Only those files that are needed to build LLVM
466 should be added to <tt>EXTRA_DIST</tt>. <tt>EXTRA_DIST</tt> contains a
467 list of file or directory names that should be distributed. For example,
468 the top level Makefile contains <tt>EXTRA_DIST := test llvm.spec
469 include</tt>. This means that in addition to regular things that are
470 distributed at the top level (<tt>CREDITS.txt, LICENSE.txt</tt>, etc.)
471 the distribution should contain the entire <tt>test</tt> and
472 <tt>include</tt> directories as well as the <tt>llvm.spec</tt> file.</li>
473 <li><b><tt>dist-hook</tt></B> - this make target can be used to alter the
474 content of the distribution directory. For example, in the top level
475 Makefile there is some logic to eliminate files in the <tt>include</tt>
476 subtree that are generated by the configure script. These should not be
477 distributed. Similarly, any <tt>dist-hook</tt> target found in any
478 directory can add or remove or modify things just before it gets
479 packaged. Any transformation is permitted. Generally, not much is
480 needed.</li>
481 </ol>
482
483 <p>
484 You will see various messages if things go wrong:
485 </p>
486
487 <ol>
488 <li>During the copying process, any files that are missing will be flagged
489 with: <tt>===== WARNING: Distribution Source 'dir/file' Not Found!</tt>
490 These must be corrected by either adding the file or removing it from
491 <tt>EXTRA_DIST</tt>.</li>
492 <li>If you build the distribution with <tt>VERBOSE=1</tt>, then you might
493 also see: <tt>Skipping non-existent 'dir/file'</tt> in certain cases
494 where it's okay to skip the file.</li>
495 <li>The target can fail if any of the things it does fail. Error messages
496 should indicate what went wrong.</li>
497 </ol>
498</div>
499
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]500<!-- ======================================================================= -->
501<div class="doc_subsection">dist</div>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]502<div class="doc_text">
503 <p>
504 This target does exactly what <tt>distdir</tt> target does, but also includes
505 assembling the tarballs. There are actually four related targets here:
506 </p>
507
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]508 <ul>
509 <li><b><tt>dist-gzip</tt></b>: package the gzipped distribution tar
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]510 file. The distribution directory is packaged into a single file ending
511 in <tt>.tar.gz</tt> which is gzip compressed.</li>
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]512 <li><b><tt>dist-bzip2</tt></b>: package the bzip2 distribution tar file.
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]513 The distribution directory is packaged into a single file ending in
514 <tt>.tar.bzip2</tt> which is bzip2 compressed.</li>
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]515 <li><b><tt>dist-zip</tt></b>: package the zip distribution file. The
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]516 distribution directory is packaged into a single file ending in
517 <tt>.zip</tt> which is zip compressed.</li>
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]518 <li><b><tt>dist</tt></b>: does all three, dist-gzip, dist-bzip2,
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]519 dist-zip</li>
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]520 </ul>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]521</div>
522
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]523<!-- ======================================================================= -->
524<div class="doc_subsection">dist-check</div>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]525<div class="doc_text">
526 <p>
527 This target checks the distribution. The basic idea is that it unpacks the
528 distribution tarball and ensures that it can build. It takes the following
529 actions:
530 </p>
531
532 <ol>
533 <li>It depends on the <tt>dist-gzip</tt> target which, if it hasn't already
534 been built, builds the gzip tar bundle (see dist and distdir
535 above).</li>
536 <li>removes any pre-existing <tt>_distcheckdir</tt> at the top level.</li>
537 <li>creates a new <tt>_distcheckdir</tt> directory at the top level.</li>
538 <li>creates a <tt>build</tt> subdirectory and an <tt>install</tt>
539 subdirectory under <tt>_distcheckdir</tt>.</li>
540 <li>unzips and untars the release tarball into <tt>_distcheckdir</tt>,
541 creating <tt>LLVM-1.7</tt> directory (from the tarball).</li>
542 <li>in the build subdirectory, it configures with appropriate options to
543 build from the unpacked source tarball into the <tt>build</tt> directory
544 with installation in the <tt>install</tt> directory.</li>
545 <li>runs <tt>make all</tt></li>
546 <li>runs <tt>make </tt><tt>check</tt></li>
547 <li>runs <tt>make install</tt></li>
548 <li>runs <tt>make uninstall</tt></li>
549 <li>runs <tt>make dist</tt></li>
550 <li>runs <tt>make clean</tt></li>
551 <li>runs <tt>make dist-clean</tt></li>
552 </ol>
553
554 <p>
555 If it can pass all that, the distribution will be deemed distribution worth y
556 and you will see:
557 </p>
558
559 <pre>===== LLVM-1.7.tar.gz Ready For Distribution =====</pre>
560
561 <p>
562 This means the tarball should then be tested on other platforms and have the
563 nightly test run against it. If those all pass, THEN it is ready for
564 distribution.
565 </p>
566
567 <p>
568 A note about disk space: using <tt>dist-check</tt> will easily triple the
569 amount of disk space your build tree is using. You might want to check
570 available space before you begin.
571 </p>
572</div>
573
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]574<!-- ======================================================================= -->
575<div class="doc_subsection">dist-clean</div>
Bill Wendling462fc8a2007-07-23 04:41:42 +0000[diff] [blame]576<div class="doc_text">
577 <p>
578 In addition to doing a normal <tt>clean</tt>, this target will clean up the
579 files and directories created by the distribution targets. In particular the
580 distribution directory (<tt>LLVM-X.X</tt>), check directory
581 (<tt>_distcheckdir</tt>), and the various tarballs will be removed. You do
582 this after the release has shipped and you no longer need this stuff in your
583 build tree.
584 </p>
Reid Spencer2425e4c2006-04-11 21:59:37 +0000[diff] [blame]585</div>
586
587<!-- *********************************************************************** -->
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]588<hr>
589<address>
590 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]591 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]592 <a href="http://validator.w3.org/check/referer"><img
Misha Brukmanf00ddb02008-12-11 18:23:24 +0000[diff] [blame]593 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]594 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
Misha Brukmanf00ddb02008-12-11 18:23:24 +0000[diff] [blame]595 <br>
Reid Spencercf427e82006-03-23 06:45:42 +0000[diff] [blame]596 Last modified: $Date$
597</address>
598</body>
599</html>