Mercurial > hg > CbC > CbC_llvm

comparison docs/HowToReleaseLLVM.rst @ 120:1172e4bd9c6f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
update 4.0.0
author mir3636
date Fri, 25 Nov 2016 19:14:25 +0900
parents 7d135dc70f03
children 803732b1fca8
comparison
equal deleted inserted replaced
101:34baf5011add 120:1172e4bd9c6f
1 ================================= 1 =================================
2 How To Release LLVM To The Public 2 How To Release LLVM To The Public
3 ================================= 3 =================================
4 4
5 .. contents::
6 :local:
7 :depth: 1
8
9 Introduction 5 Introduction
10 ============ 6 ============
11 7
12 This document contains information about successfully releasing LLVM --- 8 This document contains information about successfully releasing LLVM ---
13 including subprojects: e.g., ``clang`` and ``dragonegg`` --- to the public. It 9 including sub-projects: e.g., ``clang`` and ``compiler-rt`` --- to the public.
14 is the Release Manager's responsibility to ensure that a high quality build of 10 It is the Release Manager's responsibility to ensure that a high quality build
15 LLVM is released. 11 of LLVM is released.
16 12
17 If you're looking for the document on how to test the release candidates and 13 If you're looking for the document on how to test the release candidates and
18 create the binary packages, please refer to the :doc:`ReleaseProcess` instead. 14 create the binary packages, please refer to the :doc:`ReleaseProcess` instead.
19 15
20 .. _timeline: 16 .. _timeline:
44 fixed. Patches are merged from mainline into the release branch. Also, all 40 fixed. Patches are merged from mainline into the release branch. Also, all
45 features need to be completed during this time. Any features not completed at 41 features need to be completed during this time. Any features not completed at
46 the end of the first round of testing will be removed or disabled for the 42 the end of the first round of testing will be removed or disabled for the
47 release. 43 release.
48 44
49 * Generate and send out the second release candidate sources. Only *critial* 45 * Generate and send out the second release candidate sources. Only *critical*
50 bugs found during this testing phase will be fixed. Any bugs introduced by 46 bugs found during this testing phase will be fixed. Any bugs introduced by
51 merged patches will be fixed. If so a third round of testing is needed. 47 merged patches will be fixed. If so a third round of testing is needed.
52 48
53 * The release notes are updated. 49 * The release notes are updated.
54 50
87 new TableGen feature, etc. 83 new TableGen feature, etc.
88 84
89 #. Verify that the current Subversion trunk is in decent shape by 85 #. Verify that the current Subversion trunk is in decent shape by
90 examining nightly tester and buildbot results. 86 examining nightly tester and buildbot results.
91 87
92 #. Create the release branch for ``llvm``, ``clang``, the ``test-suite``, and 88 #. Create the release branch for ``llvm``, ``clang``, and other sub-projects,
93 ``dragonegg`` from the last known good revision. The branch's name is 89 from the last known good revision. The branch's name is
94 ``release_XY``, where ``X`` is the major and ``Y`` the minor release 90 ``release_XY``, where ``X`` is the major and ``Y`` the minor release
95 numbers. The branches should be created using the following commands: 91 numbers. Use ``utils/release/tag.sh`` to tag the release.
96
97 ::
98
99 $ svn copy https://llvm.org/svn/llvm-project/llvm/trunk \
100 https://llvm.org/svn/llvm-project/llvm/branches/release_XY
101
102 $ svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
103 https://llvm.org/svn/llvm-project/cfe/branches/release_XY
104
105 $ svn copy https://llvm.org/svn/llvm-project/dragonegg/trunk \
106 https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY
107
108 $ svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
109 https://llvm.org/svn/llvm-project/test-suite/branches/release_XY
110 92
111 #. Advise developers that they may now check their patches into the Subversion 93 #. Advise developers that they may now check their patches into the Subversion
112 tree again. 94 tree again.
113 95
114 #. The Release Manager should switch to the release branch, because all changes 96 #. The Release Manager should switch to the release branch, because all changes
118 :: 100 ::
119 101
120 $ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XY llvm-X.Y 102 $ svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XY llvm-X.Y
121 103
122 $ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XY clang-X.Y 104 $ svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XY clang-X.Y
123
124 $ svn co https://llvm.org/svn/llvm-project/dragonegg/branches/release_XY dragonegg-X.Y
125 105
126 $ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XY test-suite-X.Y 106 $ svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XY test-suite-X.Y
127 107
128 Update LLVM Version 108 Update LLVM Version
129 ^^^^^^^^^^^^^^^^^^^ 109 ^^^^^^^^^^^^^^^^^^^
153 $ ./export.sh -release X.Y.Z -rc $RC 133 $ ./export.sh -release X.Y.Z -rc $RC
154 134
155 This will generate source tarballs for each LLVM project being validated, which 135 This will generate source tarballs for each LLVM project being validated, which
156 can be uploaded to the website for further testing. 136 can be uploaded to the website for further testing.
157 137
158 Building the Release
159 --------------------
160
161 The builds of ``llvm``, ``clang``, and ``dragonegg`` *must* be free of
162 errors and warnings in Debug, Release+Asserts, and Release builds. If all
163 builds are clean, then the release passes Build Qualification.
164
165 The ``make`` options for building the different modes:
166
167 +-----------------+---------------------------------------------+
168 | Mode | Options |
169 +=================+=============================================+
170 | Debug | ``ENABLE_OPTIMIZED=0`` |
171 +-----------------+---------------------------------------------+
172 | Release+Asserts | ``ENABLE_OPTIMIZED=1`` |
173 +-----------------+---------------------------------------------+
174 | Release | ``ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1`` |
175 +-----------------+---------------------------------------------+
176
177 Build LLVM
178 ^^^^^^^^^^
179
180 Build ``Debug``, ``Release+Asserts``, and ``Release`` versions
181 of ``llvm`` on all supported platforms. Directions to build ``llvm``
182 are :doc:`here <GettingStarted>`.
183
184 Build Clang Binary Distribution 138 Build Clang Binary Distribution
185 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 139 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
186 140
187 Creating the ``clang`` binary distribution (Debug/Release+Asserts/Release) 141 Creating the ``clang`` binary distribution requires following the instructions
188 requires performing the following steps for each supported platform: 142 :doc:`here <ReleaseProcess>`.
189 143
190 #. Build clang according to the directions `here 144 That process will perform both Release+Asserts and Release builds but only
191 <http://clang.llvm.org/get_started.html>`__. 145 pack the Release build for upload. You should use the Release+Asserts sysroot,
192 146 normally under ``final/Phase3/Release+Asserts/llvmCore-3.8.1-RCn.install/``,
193 #. Build both a Debug and Release version of clang. The binary will be the 147 for test-suite and run-time benchmarks, to make sure nothing serious has
194 Release build. 148 passed through the net. For compile-time benchmarks, use the Release version.
195 149
196 #. Package ``clang`` (details to follow). 150 The minimum required version of the tools you'll need are :doc:`here <GettingStarted>`
197
198 Target Specific Build Details
199 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
200
201 The table below specifies which compilers are used for each Arch/OS combination
202 when qualifying the build of ``llvm``, ``clang``, and ``dragonegg``.
203
204 +--------------+---------------+----------------------+
205 | Architecture | OS | compiler |
206 +==============+===============+======================+
207 | x86-32 | Mac OS 10.5 | gcc 4.0.1 |
208 +--------------+---------------+----------------------+
209 | x86-32 | Linux | gcc 4.2.X, gcc 4.3.X |
210 +--------------+---------------+----------------------+
211 | x86-32 | FreeBSD | gcc 4.2.X |
212 +--------------+---------------+----------------------+
213 | x86-32 | mingw | gcc 3.4.5 |
214 +--------------+---------------+----------------------+
215 | x86-64 | Mac OS 10.5 | gcc 4.0.1 |
216 +--------------+---------------+----------------------+
217 | x86-64 | Linux | gcc 4.2.X, gcc 4.3.X |
218 +--------------+---------------+----------------------+
219 | x86-64 | FreeBSD | gcc 4.2.X |
220 +--------------+---------------+----------------------+
221 | ARMv7 | Linux | gcc 4.6.X, gcc 4.7.X |
222 +--------------+---------------+----------------------+
223 151
224 Release Qualification Criteria 152 Release Qualification Criteria
225 ------------------------------ 153 ------------------------------
226 154
227 A release is qualified when it has no regressions from the previous release (or 155 A release is qualified when it has no regressions from the previous release (or
228 baseline). Regressions are related to correctness first and performance second. 156 baseline). Regressions are related to correctness first and performance second.
229 (We may tolerate some minor performance regressions if they are deemed 157 (We may tolerate some minor performance regressions if they are deemed
230 necessary for the general quality of the compiler.) 158 necessary for the general quality of the compiler.)
231 159
232 **Regressions are new failures in the set of tests that are used to qualify 160 More specifically, Clang/LLVM is qualified when it has a clean test with all
161 supported sub-projects included (``make check-all``), per target, and it has no
162 regressions with the ``test-suite`` in relation to the previous release.
163
164 Regressions are new failures in the set of tests that are used to qualify
233 each product and only include things on the list. Every release will have 165 each product and only include things on the list. Every release will have
234 some bugs in it. It is the reality of developing a complex piece of 166 some bugs in it. It is the reality of developing a complex piece of
235 software. We need a very concrete and definitive release criteria that 167 software. We need a very concrete and definitive release criteria that
236 ensures we have monotonically improving quality on some metric. The metric we 168 ensures we have monotonically improving quality on some metric. The metric we
237 use is described below. This doesn't mean that we don't care about other 169 use is described below. This doesn't mean that we don't care about other
238 criteria, but these are the criteria which we found to be most important and 170 criteria, but these are the criteria which we found to be most important and
239 which must be satisfied before a release can go out.** 171 which must be satisfied before a release can go out.
240 172
241 Qualify LLVM 173 Official Testing
242 ^^^^^^^^^^^^ 174 ----------------
243 175
244 LLVM is qualified when it has a clean test run without a front-end. And it has 176 A few developers in the community have dedicated time to validate the release
245 no regressions when using either ``clang`` or ``dragonegg`` with the 177 candidates and volunteered to be the official release testers for each
246 ``test-suite`` from the previous release. 178 architecture.
247 179
248 Qualify Clang 180 These will be the ones testing, generating and uploading the official binaries
249 ^^^^^^^^^^^^^ 181 to the server, and will be the minimum tests *necessary* for the release to
250 182 proceed.
251 ``Clang`` is qualified when front-end specific tests in the ``llvm`` regression 183
252 test suite all pass, clang's own test suite passes cleanly, and there are no 184 This will obviously not cover all OSs and distributions, so additional community
253 regressions in the ``test-suite``. 185 validation is important. However, if community input is not reached before the
254 186 release is out, all bugs reported will have to go on the next stable release.
255 Specific Target Qualification Details 187
256 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 188 The official release managers are:
257 189
258 +--------------+-------------+----------------+-----------------------------+ 190 * Major releases (X.0): Hans Wennborg
259 | Architecture | OS | clang baseline | tests | 191 * Stable releases (X.n): Tom Stellard
260 +==============+=============+================+=============================+ 192
261 | x86-32 | Linux | last release | llvm regression tests, | 193 The official release testers are volunteered from the community and have
262 | | | | clang regression tests, | 194 consistently validated and released binaries for their targets/OSs. To contact
263 | | | | test-suite (including spec) | 195 them, you should email the ``release-testers@lists.llvm.org`` mailing list.
264 +--------------+-------------+----------------+-----------------------------+ 196
265 | x86-32 | FreeBSD | last release | llvm regression tests, | 197 The official testers list is in the file ``RELEASE_TESTERS.TXT``, in the ``LLVM``
266 | | | | clang regression tests, | 198 repository.
267 | | | | test-suite |
268 +--------------+-------------+----------------+-----------------------------+
269 | x86-32 | mingw | none | QT |
270 +--------------+-------------+----------------+-----------------------------+
271 | x86-64 | Mac OS 10.X | last release | llvm regression tests, |
272 | | | | clang regression tests, |
273 | | | | test-suite (including spec) |
274 +--------------+-------------+----------------+-----------------------------+
275 | x86-64 | Linux | last release | llvm regression tests, |
276 | | | | clang regression tests, |
277 | | | | test-suite (including spec) |
278 +--------------+-------------+----------------+-----------------------------+
279 | x86-64 | FreeBSD | last release | llvm regression tests, |
280 | | | | clang regression tests, |
281 | | | | test-suite |
282 +--------------+-------------+----------------+-----------------------------+
283 | ARMv7A | Linux | last release | llvm regression tests, |
284 | | | | clang regression tests, |
285 | | | | test-suite |
286 +--------------+-------------+----------------+-----------------------------+
287 199
288 Community Testing 200 Community Testing
289 ----------------- 201 -----------------
290 202
291 Once all testing has been completed and appropriate bugs filed, the release 203 Once all testing has been completed and appropriate bugs filed, the release
292 candidate tarballs are put on the website and the LLVM community is notified. 204 candidate tarballs are put on the website and the LLVM community is notified.
293 Ask that all LLVM developers test the release in 2 ways: 205
206 We ask that all LLVM developers test the release in any the following ways:
294 207
295 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang`` 208 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``
296 binary. Build LLVM. Run ``make check`` and the full LLVM test suite (``make 209 binary. Build LLVM. Run ``make check`` and the full LLVM test suite (``make
297 TEST=nightly report``). 210 TEST=nightly report``).
298 211
299 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the ``clang`` sources. Compile 212 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the ``clang`` sources. Compile
300 everything. Run ``make check`` and the full LLVM test suite (``make 213 everything. Run ``make check`` and the full LLVM test suite (``make
301 TEST=nightly report``). 214 TEST=nightly report``).
302 215
303 Ask LLVM developers to submit the test suite report and ``make check`` results 216 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``
304 to the list. Verify that there are no regressions from the previous release. 217 binary. Build whole programs with it (ex. Chromium, Firefox, Apache) for
305 The results are not used to qualify a release, but to spot other potential 218 your platform.
306 problems. For unsupported targets, verify that ``make check`` is at least 219
307 clean. 220 #. Download ``llvm-X.Y``, ``llvm-test-X.Y``, and the appropriate ``clang``
221 binary. Build *your* programs with it and check for conformance and
222 performance regressions.
223
224 #. Run the :doc:`release process <ReleaseProcess>`, if your platform is
225 *different* than that which is officially supported, and report back errors
226 only if they were not reported by the official release tester for that
227 architecture.
228
229 We also ask that the OS distribution release managers test their packages with
230 the first candidate of every release, and report any *new* errors in Bugzilla.
231 If the bug can be reproduced with an unpatched upstream version of the release
232 candidate (as opposed to the distribution's own build), the priority should be
233 release blocker.
308 234
309 During the first round of testing, all regressions must be fixed before the 235 During the first round of testing, all regressions must be fixed before the
310 second release candidate is tagged. 236 second release candidate is tagged.
311 237
312 If this is the second round of testing, the testing is only to ensure that bug 238 In the subsequent stages, the testing is only to ensure that bug
313 fixes previously merged in have not created new major problems. *This is not 239 fixes previously merged in have not created new major problems. *This is not
314 the time to solve additional and unrelated bugs!* If no patches are merged in, 240 the time to solve additional and unrelated bugs!* If no patches are merged in,
315 the release is determined to be ready and the release manager may move onto the 241 the release is determined to be ready and the release manager may move onto the
316 next stage. 242 next stage.
317 243
244 Reporting Regressions
245 ---------------------
246
247 Every regression that is found during the tests (as per the criteria above),
248 should be filled in a bug in Bugzilla with the priority *release blocker* and
249 blocking a specific release.
250
251 To help manage all the bugs reported and which ones are blockers or not, a new
252 "[meta]" bug should be created and all regressions *blocking* that Meta. Once
253 all blockers are done, the Meta can be closed.
254
255 If a bug can't be reproduced, or stops being a blocker, it should be removed
256 from the Meta and its priority decreased to *normal*. Debugging can continue,
257 but on trunk.
258
318 Release Patch Rules 259 Release Patch Rules
319 ------------------- 260 -------------------
320 261
321 Below are the rules regarding patching the release branch: 262 Below are the rules regarding patching the release branch:
322 263
323 #. Patches applied to the release branch may only be applied by the release 264 #. Patches applied to the release branch may only be applied by the release
324 manager. 265 manager, the official release testers or the code owners with approval from
266 the release manager.
325 267
326 #. During the first round of testing, patches that fix regressions or that are 268 #. During the first round of testing, patches that fix regressions or that are
327 small and relatively risk free (verified by the appropriate code owner) are 269 small and relatively risk free (verified by the appropriate code owner) are
328 applied to the branch. Code owners are asked to be very conservative in 270 applied to the branch. Code owners are asked to be very conservative in
329 approving patches for the branch. We reserve the right to reject any patch 271 approving patches for the branch. We reserve the right to reject any patch
330 that does not fix a regression as previously defined. 272 that does not fix a regression as previously defined.
331 273
332 #. During the remaining rounds of testing, only patches that fix critical 274 #. During the remaining rounds of testing, only patches that fix critical
333 regressions may be applied. 275 regressions may be applied.
334 276
335 #. For dot releases all patches must mantain both API and ABI compatibility with 277 #. For dot releases all patches must maintain both API and ABI compatibility with
336 the previous major release. Only bugfixes will be accepted. 278 the previous major release. Only bug-fixes will be accepted.
337 279
338 Merging Patches 280 Merging Patches
339 ^^^^^^^^^^^^^^^ 281 ^^^^^^^^^^^^^^^
340 282
341 The ``utils/release/merge.sh`` script can be used to merge individual revisions 283 The ``utils/release/merge.sh`` script can be used to merge individual revisions
342 into any one of the llvm projects. To merge revision ``$N`` into project 284 into any one of the llvm projects. To merge revision ``$N`` into project
343 ``$PROJ``, do: 285 ``$PROJ``, do:
344 286
345 #. ``svn co http://llvm.org/svn/llvm-project/$PROJ/branches/release_XX 287 #. ``svn co https://llvm.org/svn/llvm-project/$PROJ/branches/release_XX
346 $PROJ.src`` 288 $PROJ.src``
347 289
348 #. ``$PROJ.src/utils/release/merge.sh --proj $PROJ --rev $N`` 290 #. ``$PROJ.src/utils/release/merge.sh --proj $PROJ --rev $N``
349 291
350 #. Run regression tests. 292 #. Run regression tests.
392 The website must be updated before the release announcement is sent out. Here 334 The website must be updated before the release announcement is sent out. Here
393 is what to do: 335 is what to do:
394 336
395 #. Check out the ``www`` module from Subversion. 337 #. Check out the ``www`` module from Subversion.
396 338
397 #. Create a new subdirectory ``X.Y`` in the releases directory. 339 #. Create a new sub-directory ``X.Y`` in the releases directory.
398 340
399 #. Commit the ``llvm``, ``test-suite``, ``clang`` source, ``clang binaries``, 341 #. Commit the ``llvm``, ``test-suite``, ``clang`` source and binaries in this
400 ``dragonegg`` source, and ``dragonegg`` binaries in this new directory. 342 new directory.
401 343
402 #. Copy and commit the ``llvm/docs`` and ``LICENSE.txt`` files into this new 344 #. Copy and commit the ``llvm/docs`` and ``LICENSE.txt`` files into this new
403 directory. The docs should be built with ``BUILD_FOR_WEBSITE=1``. 345 directory. The docs should be built with ``BUILD_FOR_WEBSITE=1``.
404 346
405 #. Commit the ``index.html`` to the ``release/X.Y`` directory to redirect (use 347 #. Commit the ``index.html`` to the ``release/X.Y`` directory to redirect (use
415 into Subversion. 357 into Subversion.
416 358
417 Announce the Release 359 Announce the Release
418 ^^^^^^^^^^^^^^^^^^^^ 360 ^^^^^^^^^^^^^^^^^^^^
419 361
420 Have Chris send out the release announcement when everything is finished. 362 Send an email to the list announcing the release, pointing people to all the
421 363 relevant documentation, download pages and bugs fixed.
364