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