llvm.org GIT mirror llvm / 4b9e1d2
First steps to document new release plan. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@79376 91177308-0d34-0410-b5e6-96231b3b80d8 Tanya Lattner 10 years ago
1 changed file(s) with 181 addition(s) and 336 deletion(s). Raw diff Collapse all Expand all
99
How To Release LLVM To The Public
1010
1111
  • Introduction
  • 12
  • Qualification Criteria
  • 1213
  • Release Timeline
  • 1314
  • Release Process
  • 14
  • Distribution Targets
  • 1515
    1616
    17

    Written by Reid Spencer,

    18 John Criswell,
    19 <a href="mailto:tonic@nondot.org">Tanya Lattner

    17 <p>Written by Tanya Lattner,
    18 Reid Spencer,
    19 John Criswell
    20

    2021
    2122
    2223
    2526
    2627
    2728

    28 This document collects information about successfully releasing LLVM to the
    29 public. It is the release manager's guide to ensuring that a high quality
    29 This document collects information about successfully releasing LLVM
    30 (including subprojects llvm-gcc and Clang) to the public.
    31 It is the release manager's responsibility to ensure that a high quality
    3032 build of LLVM is released.
    3133

    32
    33

    34 The following is the basic criteria for releasing LLVM:
    35

    36
    37
    38
  • Successful configure and build.
  • 39
  • Clean 'make check'.
  • 40
  • No regressions in the testsuite from the previous release. This may
  • 41 include performance regressions for major benchmarks.
    42
    4334
    4435
    4536
    4637
    4738
    4839
    49 The release manager should attempt to have a release every 3-4 months because LLVM
    50 does time based releases (instead of feature based). The release schedule should
    51 be roughly as follows:
    40

    LLVM is released on a time based schedule (currently every 6 months). We

    41 do not have dot releases because of the nature of LLVM incremental
    42 developement philosophy. The release schedule is roughly as follows:
    43

    5244
    53
  • Set code freeze and branch creation date for 3 months after last release
  • 45
  • Set code freeze and branch creation date for 6 months after last code freeze
  • 5446 date. Announce release schedule to the LLVM community and update the website.
    5547
  • Create release branch and begin release process.
  • 5648
  • Send out pre-release for first round of testing. Testing will last 7-10 days.
  • 7062
    7163
    7264
    73
    74
    75
    76 >
    65
    >
    66
    67
  • Release Administrative Tasks
  • 68
    7769
  • Create Release Branch
  • 78
  • Update LLVM Version
  • 70
  • Update Version Numbers
  • 71
    72
  • Building the Release
  • 73
    7974
  • Build the LLVM Source Distributions
  • 8075
  • Build LLVM
  • 81
  • Build the LLVM GCC Binary Distribution
  • 82
  • Build RPM Packages (optional)
  • 83
  • Run 'make check'
  • 84
  • Run LLVM Test Suite
  • 85
  • Pre-Release Testing
  • 76
  • Build the LLVM-GCC Binary Distribution
  • 77
  • Build the Clang Binary Distribution
  • 78
  • Target Specific Build Details
  • 79
    80
    81
  • Release Qualification Criteria
  • 82
    83
  • Qualify LLVM
  • 84
  • Qualify LLVM-GCC
  • 85
  • Qualify Clang
  • 86
  • Specific Target Qualification Details
  • 87
    88
    89
  • Community Testing
  • 90
  • Release Patch Rules
  • 91
    92
    93
  • Release final tasks
  • 94
    8695
  • Tag the LLVM Release Branch
  • 8796
  • Update Documentation
  • 8897
  • Update the LLVM Demo Page
  • 8998
  • Update the LLVM Website
  • 9099
  • Announce the Release
  • 100
    91101
    92102
    93103
    94104
    95105
    96
    106
    107 Release Administrative Tasks
    108
    109
    110 This section describes a few administrative tasks that need to be done for the
    111 release process to begin. Specifically, it involves creating the release branch,
    112 resetting version numbers, and creating the release tarballs for the release
    113 team to begin testing.
    114
    115
    116
    117
    97118
    98119

    Branch the Subversion HEAD using the following procedure:

    99120
    100121
  • 101

    Verify that the current Subversion HEAD is in decent shape by examining nightly

    102 tester results.

    122

    Verify that the current Subversion HEAD is in decent shape by examining

    123 nightly tester or buildbot results.

    103124
  • 104125

    Request all developers to refrain from committing. Offenders get commit

    105126 rights taken away (temporarily).

    106127
  • 107

    Create the release branch for llvm, llvm-gcc4.2, and

    108 the test-suite. The branch name will be release_XX,
    109 where XX is the major and minor release numbers. These branches can
    110 be created without checking out anything from subversion.
    128

    Create the release branch for llvm, llvm-gcc4.2,

    129 clang, and the test-suite. The branch name will be
    130 release_XX,where XX is the major and minor release numbers.
    131 Clang will have a different release number than llvm/
    132 llvm-gcc4 since its first release was years later
    133 (still deciding if this will be true or not). These branches
    134 can be created without checking out anything from subversion.
    111135

    112136
    113137
    118142 https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX
    119143 svn copy https://llvm.org/svn/llvm-project/test-suite/trunk \
    120144 https://llvm.org/svn/llvm-project/test-suite/branches/release_XX
    145 svn copy https://llvm.org/svn/llvm-project/cfe/trunk \
    146 https://llvm.org/svn/llvm-project/cfe/branches/release_XX
    121147
    122148
    123149
    134160 svn co https://llvm.org/svn/llvm-project/llvm/branches/release_XX
    135161 svn co https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX
    136162 svn co https://llvm.org/svn/llvm-project/test-suite/branches/release_XX
    163 svn co https://llvm.org/svn/llvm-project/cfe/branches/release_XX
    137164
    138165
    139166
    141168
    142169
    143170
    144
    171
    145172
    146173

    147174 After creating the LLVM release branch, update the release branches'
    149176 as well to be the next version (X.X+1svn). Regenerated the configure script
    150177 for both. This must be done for both llvm and the test-suite.
    151178

    179

    FIXME: Add a note about clang.

    152180

    In addition, the version number of all the Bugzilla components must be

    153181 updated for the next release.
    154182

    155183
    156184
    157185
    158
    159
    160

    161 Create source distributions for LLVM, LLVM GCC, and the LLVM Test Suite by
    162 exporting the source from Subversion and archiving it. This can be done with
    163 the following commands:
    186
    187
    188

    189 Create source distributions for LLVM, LLVM GCC, Clang, and the LLVM Test
    190 Suite by exporting the source from Subversion and archiving it. This can be
    191 done with the following commands:
    164192

    165193
    166194
    168196 svn export https://llvm.org/svn/llvm-project/llvm/branches/release_XX llvm-X.X
    169197 svn export https://llvm.org/svn/llvm-project/llvm-gcc-4.2/branches/release_XX llvm-gcc4.2-X.X.source
    170198 svn export https://llvm.org/svn/llvm-project/test-suite/branches/release_XX llvm-test-X.X
    171 tar -cvf - llvm-X.X | gzip > llvm-X.X.tar.gz
    172 tar -cvf - llvm-test-X.X | gzip > llvm-test-X.X.tar.gz
    173 tar -cvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz
    199 svn export https://llvm.org/svn/llvm-project/cfe/branches/release_XX clang-X.X
    200 tar -czvf - llvm-X.X | gzip > llvm-X.X.tar.gz
    201 tar -czvf - llvm-test-X.X | gzip > llvm-test-X.X.tar.gz
    202 tar -czvf - llvm-gcc4.2-X.X.source | gzip > llvm-gcc-4.2-X.X.source.tar.gz
    203 tar -czvf - clang-X.X.source | gzip > clang-X.X.source.tar.gz
    174204
    175205
    176206
    177207
    178208
    179
    209
    210 Building the Release
    211
    212
    213 Info about this. Criteria for a successful build.
    214
    215
    216
    217
    180218
    181219

    182220 Build both debug and release (optimized) versions of LLVM on all
    186224
    187225
    188226
    189
    227
    190228
    191229

    192230 Creating the LLVM GCC binary distribution (release/optimized) requires
    203241
  • 204242 Copy the installation directory to a directory named for the specific target.
    205243 For example on Red Hat Enterprise Linux, the directory would be named
    206 llvm-gcc4.0-2.1-x86-linux-RHEL4. Archive and compress the new directory.
    244 llvm-gcc4.2-2.6-x86-linux-RHEL4. Archive and compress the new directory.
    207245
    208246
    209247
    210248
    211249
    212
    213
    214

    215 Using the newly built llvm-gcc and llvm, reconfigure llvm to locate llvm-gcc.
    216 Run make check and ensure there are no unexpected failures. If there
    217 are, resolve the failures or file a bug. If there is a fix commited to mainline,
    218 merge back into the release branch, and restart testing by
    219 re-building LLVM and llvm-gcc. If no
    220 fix will be made, XFAIL the test and commit back to the release branch.
    221

    222
    223

    224 Ensure that 'make check' passes on all platforms for all targets. The
    225 test suite must complete with "0 unexpected failures" before sending out the
    226 pre-releases for testing.
    227

    228
    229
    230
    231
    232
    233

    234 Run the llvm-test suite and ensure there are no unacceptable
    235 failures. Unacceptable failures are regression from the previous release
    236 and (optionally) major performance regressions from the previous release.
    237 If a regression is found a bug is filled, but the pre-releases may still go
    238 out.

    239
    240
    241
    242
    243
    244

    245 You can, optionally, create source and binary RPM packages for LLVM. These may
    246 make it easier to get LLVM into a distribution. This can be done with the
    247 following commands:
    248

    249
    250
    251
    
                      
                    
    252 make dist # Build the distribution source tarball
    253 make dist-check # Check that the source tarball can build itself.
    254 cp llvm-M.m.tar.gz /usr/src/redhat/SOURCES # Required by rpmbuild
    255 make srpm # for source rpm
    256 make rpm # for binary rpm
    257
    258
    259
    260

    261 First, use make dist to simply build the distribution. Any failures
    262 need to be corrected (on the branch). Once make dist can be
    263 successful, do make dist-check. This target will do the same thing as
    264 the 'dist' target but also test that distribution to make sure it can build
    265 itself and runs make check as well. This ensures that needed files
    266 are not missing and that the src tarball can be successfully unpacked, built,
    267 installed, and cleaned. Once you have a reliable tarball, you need to copy it
    268 to the /usr/src/redhat/SOURCES directory which is a requirement of
    269 the rpmbuild tool. The last two make invocations just run rpmbuild to
    270 build either a source (srpm) or binary (rpm) RPM package.
    271

    272
    273
    274
    275
    250
    251
    252

    253 Creating the Clang binary distribution (release/optimized) requires
    254 performing the following steps for each supported platform:
    255

    256
    257
    258
  • 259 Instructions how to build it.
    260
    261
    262
  • 263 Instructions on how to package
    264
    265
    266
    267
    268
    269
    270
    271 Details
    272
    273

    274 Specify what is used to build llvm, llvm-gcc, clang on each target.
    275

    276
    277
    278
    279
    280
    281 Building the Release
    282
    283
    284 How to qualify the release.
    285
    286
    287
    288
    289
    290
    291

    292 Details

    293
    294
    295
    296
    297
    298

    299 Details.

    300
    301
    302
    303
    304
    305

    306 Details.

    307
    308
    309
    310
    311 Qualification Details
    312
    313

    314 Details

    315
    316
    317
    318
    276319
    277320

    278321 Once all testing has been completed and appropriate bugs filed, the pre-release
    299342 is determined to be ready and the release manager may move onto the next step.

    300343
    301344
    302
    303
    304 <div class="doc_subsection">Tag the Release Branch>
    345 <!-- ======================================================================= -->
    346
    347
    348
    349

    350 Details

    351
    352
    353
    354
    355
    356
    357
    358

    359 Details

    360
    361
    362
    363
    364
    305365
    306366

    Tag the release branch using the following procedure:

    307367
    317377
    318378
    319379
    320
    380
    321381
    322382

    323383 Review the documentation and ensure that it is up to date. The Release Notes
    339399
    340400
    341401
    342
    402
    343403
    344404

    345405 The website must be updated before the release announcement is sent out. Here is
    363423
    364424
    365425
    366
    426
    367427
    368428

    Have Chris send out the release announcement when everything is finished.

    369
    370
    371
    372
    373
    374
    375
    376
    Overview
    377
    378

    379 The first thing you need to understand is that there are multiple make targets
    380 to support this feature. Here's an overview, we'll delve into the details
    381 later.
    382

    383
    384
    385
  • distdir - builds the distribution directory from which the
  • 386 distribution will be packaged
    387
  • dist - builds each of the distribution tarballs (tar.gz,
  • 388 tar.bzip2, .zip). These can be built individually as well, with separate
    389 targets.
    390
  • dist-check - this is identical to dist but includes a
  • 391 check on the distribution that ensures the tarball can: unpack
    392 successfully, compile correctly, pass 'make check', and pass
    393 'make clean'.
    394
  • dist-clean- this just does a normal clean but also cleans up the
  • 395 stuff generated by the other three dist targets (above).
    396
    397
    398

    399 Okay, that's the basic functionality. When making a release, we want to ensure
    400 that the tree you build the distribution from passes
    401 dist-check. Beyond fixing the usual bugs, there is generally one
    402 impediment to making the release in this fashion: missing files. The
    403 dist-check process guards against that possibility. It will either
    404 fail and that failure will indicate what's missing, or it will succeed meaning
    405 that it has proved that the tarballs can actually succeed in building LLVM
    406 correctly and that it passes make check.
    407

    408
    409
    410
    411
    412
    distdir
    413
    414

    415 This target builds the distribution directory which is the directory from
    416 which the tarballs are generated. The distribution directory has the same
    417 name as the release, e.g. LLVM-1.7). This target goes through the following
    418 process:
    419

    420
    421
    422
  • First, if there was an old distribution directory (for the current
  • 423 release), it is removed in its entirety and you see Removing old
    424 LLVM-1.7
    425
  • Second, it issues a make all ENABLE_OPTIMIZED=3D1 to ensure
  • 426 that the everything in your tree can be built in release mode. Often
    427 times there are discrepancies in building between debug and release
    428 modes so it enforces release mode first. If that fails, the
    429 distdir target fails too. This is preceded by the message
    430 Making 'all' to verify build.
    431
  • Next, it traverses your source tree and copies it to a new directory
  • 432 that has the name of the release (LLVM-M.m in our current
    433 case). This is the directory that will get tar'd. It contains all the
    434 software that needs to be in the distribution. During the copying
    435 process, it omits generated files, SVN directories, and any other
    436 "cruft" that's in your build tree. This is done to eliminate the
    437 possibility of huge distribution tarballs that include useless or
    438 irrelevant stuff in them. This is the trickiest part of making the
    439 distribution. Done manually you will either include stuff that
    440 shouldn't be in the distribution or exclude stuff that should. This
    441 step is preceded by the message Building Distribution Directory
    442 LLVM-1.7
    443
  • The distribution directory is then traversed and all CVS or
  • 444 .svn directories are removed. You see: Eliminating CVS/.svn
    445 directories from distribution
    446
  • The recursive dist-hook target is executed. This gives each
  • 447 directory a chance to modify the distribution in some way (more on this
    448 below).
    449
  • The distribution directory is traversed and the correct file
  • 450 permissions and modes are set based on the type of file.
    451
    452
    453

    454 To control the process of making the distribution directory correctly, each
    455 Makefile can utilize two features:
    456

    457
    458
    459
  • EXTRA_DIST - this make variable specifies which files
  • 460 it should distribute. By default, all source files are automatically
    461 included for distribution as well as certain well known files
    462 (see DistAlways variable in Makefile.rules for details). Each Makefile
    463 specifies, via the EXTRA_DIST variable, which additional files
    464 need to be distributed. Only those files that are needed to build LLVM
    465 should be added to EXTRA_DIST. EXTRA_DIST contains a
    466 list of file or directory names that should be distributed. For example,
    467 the top level Makefile contains EXTRA_DIST := test llvm.spec
    468 include. This means that in addition to regular things that are
    469 distributed at the top level (CREDITS.txt, LICENSE.txt, etc.)
    470 the distribution should contain the entire test and
    471 include directories as well as the llvm.spec file.
    472
  • dist-hook - this make target can be used to alter the
  • 473 content of the distribution directory. For example, in the top level
    474 Makefile there is some logic to eliminate files in the include
    475 subtree that are generated by the configure script. These should not be
    476 distributed. Similarly, any dist-hook target found in any
    477 directory can add or remove or modify things just before it gets
    478 packaged. Any transformation is permitted. Generally, not much is
    479 needed.
    480
    481
    482

    483 You will see various messages if things go wrong:
    484

    485
    486
    487
  • During the copying process, any files that are missing will be flagged
  • 488 with: ===== WARNING: Distribution Source 'dir/file' Not Found!
    489 These must be corrected by either adding the file or removing it from
    490 EXTRA_DIST.
    491
  • If you build the distribution with VERBOSE=1, then you might
  • 492 also see: Skipping non-existent 'dir/file' in certain cases
    493 where it's okay to skip the file.
    494
  • The target can fail if any of the things it does fail. Error messages
  • 495 should indicate what went wrong.
    496
    497
    498
    499
    500
    dist
    501
    502

    503 This target does exactly what distdir target does, but also includes
    504 assembling the tarballs. There are actually four related targets here:
    505

    506
    507
    508
  • dist-gzip: package the gzipped distribution tar
  • 509 file. The distribution directory is packaged into a single file ending
    510 in .tar.gz which is gzip compressed.
    511
  • dist-bzip2: package the bzip2 distribution tar file.
  • 512 The distribution directory is packaged into a single file ending in
    513 .tar.bzip2 which is bzip2 compressed.
    514
  • dist-zip: package the zip distribution file. The
  • 515 distribution directory is packaged into a single file ending in
    516 .zip which is zip compressed.
    517
  • dist: does all three, dist-gzip, dist-bzip2,
  • 518 dist-zip
    519
    520
    521
    522
    523
    dist-check
    524
    525

    526 This target checks the distribution. The basic idea is that it unpacks the
    527 distribution tarball and ensures that it can build. It takes the following
    528 actions:
    529

    530
    531
    532
  • It depends on the dist-gzip target which, if it hasn't already
  • 533 been built, builds the gzip tar bundle (see dist and distdir
    534 above).
    535
  • removes any pre-existing _distcheckdir at the top level.
  • 536
  • creates a new _distcheckdir directory at the top level.
  • 537
  • creates a build subdirectory and an install
  • 538 subdirectory under _distcheckdir.
    539
  • unzips and untars the release tarball into _distcheckdir,
  • 540 creating LLVM-1.7 directory (from the tarball).
    541
  • in the build subdirectory, it configures with appropriate options to
  • 542 build from the unpacked source tarball into the build directory
    543 with installation in the install directory.
    544
  • runs make all
  • 545
  • runs make check
  • 546
  • runs make install
  • 547
  • runs make uninstall
  • 548
  • runs make dist
  • 549
  • runs make clean
  • 550
  • runs make dist-clean
  • 551
    552
    553

    554 If it can pass all that, the distribution will be deemed distribution worth y
    555 and you will see:
    556

    557
    558
    ===== LLVM-1.7.tar.gz Ready For Distribution =====
    559
    560

    561 This means the tarball should then be tested on other platforms and have the
    562 nightly test run against it. If those all pass, THEN it is ready for
    563 distribution.
    564

    565
    566

    567 A note about disk space: using dist-check will easily triple the
    568 amount of disk space your build tree is using. You might want to check
    569 available space before you begin.
    570

    571
    572
    573
    574
    dist-clean
    575
    576

    577 In addition to doing a normal clean, this target will clean up the
    578 files and directories created by the distribution targets. In particular the
    579 distribution directory (LLVM-X.X), check directory
    580 (_distcheckdir), and the various tarballs will be removed. You do
    581 this after the release has shipped and you no longer need this stuff in your
    582 build tree.
    583

    584429
    585430
    586431