1 README for MAKING BINUTILS RELEASES 2 3 This is a collection of notes on how to perform a binutils release. A 4 lot of this information can also be found in the maintain.texi file in 5 the gnulib project: 6 7 https://www.gnu.org/software/gnulib/ 8 9 It is useful to have a cloned copy of the sources of this project as 10 it also contains an upload script used to install tarballs on the GNU 11 FTP server. 12 13 Make sure that you have upload authority on sourceware and fencepost. 14 See the maintain.texi file for details on how to obtain these 15 permissions. 16 17 Note - when performing a release it is helpful to edit this document 18 as you go, updating the example commands so that they are ready for 19 the release that follows. 20 21 ------------------------------------------------- 22 How to perform a release. 23 ------------------------------------------------- 24 25 1. Choose dates for the branch and release. Weekends are better 26 because they are less busy. It is typical to leave two weeks 27 between creating the branch and creating the release. 28 29 Send an email out warning contributors about the forthcoming 30 branch and release. 31 32 2. When the branch date is near: Update the libiberty and config 33 directories and the top level Makefile and configure files. Also 34 consider updating the toplevel libtool files. 35 36 ------------------------------------------------- 37 How to create the release branch. 38 ------------------------------------------------- 39 40 Approx time to complete from here: 2 hours ... 41 42 2.5 If you have not built from the sources recently then now is the 43 time to check that they still work... 44 45 3. When branch day arrives add markers for the upcoming release to 46 the NEWS files in gas, ld, and binutils. No need to update NEWS 47 in the gold directory - it has its own release numbering. 48 49 Likewise for the ChangeLog files in: bfd, binutils, cpu, 50 elfcpp, gas, gold, gprof, include, ld, libctf, opcodes and toplevel. 51 52 Add a note of the name of the new branch to binutils/BRANCHES. 53 54 Commit these changes. 55 56 4. Create the release branch using: 57 58 git branch binutils-2_45-branch 59 git push origin binutils-2_45-branch 60 61 If you get a message like: 62 63 remote: fatal: Invalid revision range 0000000000000000000000000000000000000000..f974f26cb16cc6fe3946f163c787a05e713fb77b 64 65 It appears that this can be ignored... 66 67 5. Make sure that the branch is there. IE check out the branch sources: 68 69 git clone ssh://sourceware.org/git/binutils-gdb.git -b binutils-2_45-branch 2.45 70 71 If you get a message about being in a "detached head" state, something 72 has gone wrong... 73 74 Keep the checked out sources - they are going to be needed in future 75 steps. 76 77 6. Update "BINUTILS_BRANCH" in gdbadmin's crontab: 78 79 Log in as gdbadmin on sourceware.org, and then: 80 81 $ cd crontab 82 $ vi crontab 83 [change BINUTILS_BRANCH] 84 $ cvs ci crontab 85 $ crontab crontab 86 87 If you do not have access to this account, please feel free to 88 ask Joel Brobecker <brobecker AT adacore DOT com>. 89 90 7. Rename the current HEAD version entry in Bugzilla, and create a 91 new one. E.g. rename "2.45 (HEAD)" to 2.45, and create 92 "2.46 (HEAD)": 93 94 https://sourceware.org/bugzilla/editversions.cgi?product=binutils 95 96 8. Update bfd/version.m4 on HEAD to indicate that is now a snapshot 97 of the next release and the BRANCH to indicate that it is almost 98 ready for the release. 99 100 So if the release is going to be 2.45 then the version number on 101 the BRANCH should be set to 2.44.90 - ie almost, but not quite 2.45, 102 and the version number on the MAINLINE should be set to 2.45.50 - 103 ie half way to 2.46 release. 104 105 So the BRANCH bfd/version.m4 has: 106 107 m4_define([BFD_VERSION], [2.44.90]) 108 109 and the MAINLINE has: 110 111 m4_define([BFD_VERSION], [2.45.50]) 112 113 Regenerate various files on both branch and HEAD by configuring 114 with "--enable-maintainer-mode --enable-gold --enable-shared" and then building 115 with "make -j1 all-binutils all-gas all-gold all-gprof all-gprofng all-ld" 116 117 Add ChangeLog entries for the updated files. Commit the changes. 118 Make sure that this includes the .pot files as well as the 119 configure and makefiles. 120 121 9. Create an initial pre-release: 122 123 a. Remove any auto-generated files, in order to force the 124 src-release script to rebuild them. 125 126 cd <branch-sources> 127 git clean -fdx 128 129 b. Create a source tarball of the BRANCH sources: 130 131 If this is an EVEN numbered release: 132 133 ./src-release.sh -x binutils_with_gold 134 135 If this is an ODD numbered release: 136 137 ./src-release.sh -x binutils 138 139 FIXME: Not sure if the following steps are needed... 140 141 Add a .dirstamp file to the gas/doc subdirectory: 142 143 touch -d `date +%Y-%m-%d` binutils-2.44.90/gas/doc/.dirstamp 144 tar rvf binutils-2.44.90.tar binutils-2.44.90/gas/doc/.dirstamp 145 rm binutils-2.44.90.tar.xz 146 xz -9 -k binutils-2.44.90.tar 147 148 ...END OF FIXME 149 150 c. Build a test target using this tarball. 151 152 cp binutils-*.tar.xz /dev/shm 153 pushd /dev/shm 154 tar xvf binutils-*.tar.xz 155 mkdir build 156 cd build 157 ../binutils-*/configure --quiet --enable-gold 158 make 159 popd 160 161 If there are problems, fix them. 162 163 d. Upload the pre-release snapshot to the sourceware FTP site: 164 165 scp binutils-2.44.90.tar.xz sourceware.org:/var/ftp/pub/binutils/snapshots 166 ssh sourceware.org sha256sum ~ftp/pub/binutils/snapshots/binutils-2.44.90.tar.xz 167 168 Paranoia: Compare the checksum with the local version. 169 170 e. Clean up the source directory again. 171 172 git clean -fdx 173 174 10. Tell the Translation Project where to find the new tarball. 175 <coordinator (a] translationproject.org> 176 qv: https://translationproject.org/html/maintainers.html 177 178 ------------------------------------------------------------------------ 179 Dear Translation Project 180 181 The 2.45 release branch has been created for the GNU Binutils project. 182 183 A snapshot of the branch sources can be found here: 184 185 https://sourceware.org/pub/binutils/snapshots/binutils-2.44.90.tar.xz 186 187 We hope to make the official release of the sources on the <DATE> 188 although that could change if there are important bugs that need to 189 be fixed before the release. 190 ------------------------------------------------------------------------ 191 192 11. Announce the availability of the snapshot and the branch on the 193 binutils mailing list. Set a date for when the release will 194 actually happen. Something like: 195 196 ------------------------------------------------------------------------ 197 Hi Everyone, 198 199 The <NEW_VERSION> branch has now been created: 200 201 git clone git://sourceware.org/git/binutils-gdb.git -b binutils-<NEW_VERSION>-branch 202 203 A snapshot of the sources is also available here: 204 205 https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz 206 207 Please could all patches for the branch be run by me. 208 The rules for the branch are: 209 210 * No new features. 211 * Target specific bug fixes are OK. 212 * Generic bug fixes are OK if they are important and widely tested. 213 * Documentation updates/fixes are OK. 214 * Translation updates are OK. 215 * Fixes for testsuite failures are OK. 216 217 Ideally I would like to make the release happen in two weeks time, 218 i.e. <DATE>. Which I hope will be enough time for everyone 219 to get their final fixes in. 220 ------------------------------------------------------------------------ 221 222 12. Build various different toolchains, test them and nag 223 maintainers to fix any testsuite failures for their 224 architectures... 225 226 ============================================================================== 227 ============================================================================== 228 229 For the next few weeks, monitor the mailing list for new translations 230 and respond to any requests to have patches applied to the branch. 231 232 ============================================================================== 233 ============================================================================== 234 235 Then, a couple of weeks later ... 236 237 ------------------------------------------------- 238 How to create the release. 239 ------------------------------------------------- 240 241 20. Make sure that the branch sources still build, test and install 242 correctly. Make sure that the sources are clean, without any 243 patch files (.reg .orig *~) left over. 244 245 cd <branch> 246 git pull 247 git clean -fdx 248 cd <builds> 249 make 250 251 21. a. Update the release number in bfd/version.m4 on the release 252 branch to a whole new minor version number, without a point 253 value. Eg "2.44.90" becomes "2.45". NB/ Not: "2.45.00" 254 255 b. Change bfd/development.sh to set all values to "false". 256 257 c. Regenerate the configure and makefiles. And *info* files. 258 259 cd <build-configured-with-enable-maintainer-mode> 260 make -j1 all-gas all-ld all-binutils all-gprof all-gold all-gprofng all-libctf 261 make info 262 263 d. Create a ChangeLog from the git refs for all of the commits 264 from when changelog entries were no longer required: 265 266 gitlog-to-changelog --since=2021-07-03 > ChangeLog.git 267 git add ChangeLog.git 268 269 The gitlog-to-changelog script is part of the sources 270 of the "config" project. 271 272 Add an entry for ChangeLog.git to the src-release.sh script's 273 DEVO_SUPPORT list, so that it is included in the release. 274 275 FIXME: it would be better if the ChangeLog.git file was permanently 276 added to the src-release.sh script, but this mean that it would have 277 to exist in the master repository, and that the GDB project would 278 need to agree to have it there. 279 280 e. Add ChangeLog entries for all of the updates and add a 281 "this-is-the-2.43-release" comment and commit. 282 283 git add . 284 git commit -m "This is the 2.45 release" 285 git push 286 287 22. Check that your file creation mask will create the 288 correct file permissions. Eg: 289 290 % umask 291 22 292 293 Remove any spurious autom4te.cache files left over from the 294 reconfiguring: 295 296 git clean -fdx 297 298 23. Note - check to see if any new files have been added to the top 299 level of the source directory, but which are not in the 300 DEVO_SUPPORT variable in the src-release.sh script. If they are 301 needed then add them. 302 303 PARANOIA: Check that there are no pending commits: 304 305 git status 306 307 Then create the release tarballs: 308 309 If this is an EVEN numbered release: 310 311 ./src-release.sh -b -g -l -x -z binutils_with_gold 312 313 If this is an ODD numbered release: 314 315 ./src-release.sh -b -g -l -x -z binutils 316 317 OR ... for a more reproducible tarball: 318 319 ./src-release.sh -b -g -l -x -z \ 320 -r `git log -1 --format=%cd --date=format:%F bfd/version.m4` \ 321 [binutils | binutils_with_gold] 322 323 24. Check that the files in the tarballs have the correct 324 permissions. 325 326 tar tvf binutils-*.tar | grep -e "---" 327 328 Also check that the man files are not empty. (cf PR 28144). 329 330 tar tvf binutils-*.tar | grep -e "\.1" 331 332 25. Sanity check the release on x86_64-pc-linux-gnu by building and 333 running the testsuites (gas, gold, binutils and ld). 334 Make the source directory read-only before building. 335 Also test 'make install'. 336 Also build the html and pdf documentation files. 337 If necessary fix any problems. 338 339 pushd /dev/shm 340 mkdir delme 341 cd delme 342 tar xvf <path-to-sources>/binutils-2.*.tar.lz 343 chmod -R -w binutils-2.* 344 mkdir build 345 cd build 346 ../binutils-2.*/configure --quiet --enable-gold --prefix=`pwd`/install --enable-plugins --enable-shared 347 348 make -j1 all-gas all-ld all-binutils all-gprof all-gprofng 349 make check-gas check-binutils check-ld 350 make install-gas install-ld install-binutils install-gprofng 351 352 If this is an ODD numbered release: 353 354 make -j1 all-gold 355 make check-gold 356 make install-gold 357 358 Needed for step 29... 359 360 make html pdf html-libctf pdf-libctf html-libsframe pdf-libsframe 361 362 popd 363 364 26. Tag the branch with the new release number: 365 [optional: add "-u XXXXX" to sign with a gpg key] 366 enter a tag message such as: "Official GNU Binutils 2.4x release" 367 368 git tag -a <TAG> -u <Your Key> 369 eg: 370 git tag -a binutils-2_44 -u DD9E3C4F <=== Be careful to get the tag right 371 or: 372 git tag -a binutils-2_44 -u DD9E3C4F -m "Official GNU Binutils 2.44 release" 373 374 NB/ If you do sign the binaries make sure to use a key 375 that has been published with the FSF. 376 377 Then push the release: 378 379 git push origin binutils-2_44 380 381 If you get an error message along the lines of: 382 "Invalid revision range ..." 383 you can ignore it. 384 385 27. Upload the tarballs to ftp.gnu.org. 386 387 gnupload --to ftp.gnu.org:binutils binutils-2.44.tar.* 388 389 Be prepared to provide the password for the key, if you 390 signed the binaries. 391 392 The gnupload script is in the build-aux/ directory of the gnulib 393 project's srouces. It uses the ncftp package for transmitting 394 the files. 395 396 NB/ This step can be done in PARALLEL with step 28. 397 398 Check for an email response from the upload. If necessary 399 fix any problems. (The response might take a while, so 400 proceed with the next steps if you are confident that 401 everything is OK). 402 403 28. Upload the tarballs (and signatures) to sourceware.org: 404 405 sftp sourceware.org 406 cd /sourceware/ftp/pub/binutils/releases 407 put binutils-2.4*.tar.* 408 chmod 644 binutils-2.4*.tar.* 409 quit 410 411 29. Update web pages. For sourceware.org: 412 413 Clone the documentation (if you have not already done so): 414 415 git clone ssh://sourceware.org/git/binutils-htdocs 416 417 Create a new docs sub-directory and move into it: 418 419 cd binutils-htdocs 420 mkdir docs-2.45 421 cd docs-2.45 422 423 Copy the index.html from the previous release 424 425 cp ../docs/index.html . 426 427 Update the index.html file to reference this new release and to 428 point back to the current (now old) release. Update the last 429 modified date as well. 430 431 If necessary make the html documentation locally with the "make 432 html" command. (This should have been done by step 25 above). 433 434 Copy in the documentation files: 435 436 cp -r <build-dir>/gas/doc/as . 437 cp <build-dir>/gas/doc/as.html . 438 cp <build-dir>/gas/doc/as.pdf . 439 440 cp -r <build-dir>/bfd/doc/bfd . 441 cp <build-dir>/bfd/doc/bfd.html . 442 cp <build-dir>/bfd/doc/bfd.pdf . 443 444 cp -r <build-dir>/binutils/binutils_html binutils [NB/ Path not like others] 445 cp <build-dir>/binutils/doc/binutils.html . 446 cp <build-dir>/binutils/doc/binutils.pdf . 447 448 cp -r <build-dir>/gprof/doc/gprof . 449 cp <build-dir>/gprof/gprof.html . [NB/ Path not like others] 450 cp <build-dir>/gprof/gprof.pdf . [NB/ Path not like others] 451 452 cp -r <build-dir>/ld/doc/ld . 453 cp <build-dir>/ld/ld.html . [NB/ Path not like others] 454 cp <build-dir>/ld/ld.pdf . [NB/ Path not like others] 455 456 [NB/ The gprofng documentation does not have a node-per-page selection] 457 cp <build-dir>/gprofng/doc/gprof.html . 458 cp <build-dir>/gprofng/doc/gprof.pdf . 459 460 cp <build-dir>/libctf/doc/ctf-spec.html . 461 cp <build-dir>/libctf/doc/ctf-spec.pdf . 462 463 cp <build-dir>/libsframe/doc/sframe-spec.html . 464 cp <build-dir>/libsframe/doc/sframe-spec.pdf . 465 466 Update the symbolic link. 467 468 cd .. [Should now be in be in binutils-htdocs/ ] 469 rm docs 470 ln -s docs-2.45 docs 471 472 Edit index.html file to change the links to point to the new 473 release, mention any new features, update dates and so on. 474 475 Check that the new web page is correct: 476 477 file:///<path-to-binutils-htdocs>/index.html 478 479 Add the new directories and files, commit and push the changes: 480 481 git add . 482 git commit -m"Update documenation for the 2.45 release" 483 git push 484 485 486 29.1 For the www.gnu.org site you have to email webmasters (a] gnu.org 487 and ask them to copy the change(s): 488 --------------------------------------- 489 Hi FSF Webmasters, 490 491 Please could the GNU Binutils webpage at: 492 493 https://www.gnu.org/software/binutils/binutils.html 494 495 be updated to indicate that there is now a newer version available 496 (2.4x). I have already updated the related page on the Sourceware 497 website so this might be useful as a template: 498 499 https://sourceware.org/binutils/ 500 501 Thanks very much. 502 503 Cheers 504 -------------------------------------- 505 506 30. Send emails to binutils (a] sourceware.org, info-gnu (a] gnu.org and 507 David Edelsohn <dje.gcc (a] gmail.com> announcing the new release. 508 Sign the email and include the checksum: 509 510 sha256sum binutils-2.4*.tar.* 511 512 (The email to Davis is so that he can update the GNU Toolchain 513 social media). Something like this: 514 ----------------------------------------------------------------------- 515 Hi Everyone, 516 517 We are pleased to announce that version 2.4x of the GNU Binutils project 518 sources have been released and are now available for download at: 519 520 https://ftp.gnu.org/gnu/binutils 521 https://sourceware.org/pub/binutils/releases/ 522 523 checksums: xxxx 524 525 These tarballs were made with the "-r <date>" option supported by 526 the src-release.sh script. This attempts to make reproducible 527 tarballs by sorting the files and passing the "--mtime=<date>" option 528 to tar. The date used for these tarballs was obtained by running: 529 530 git log -1 --format=%cd --date=format:%F bfd/version.m4 531 532 This release contains numerous bug fixes, and also the 533 following new features: 534 535 <extract info from the NEWS files> 536 537 For more information see: 538 539 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=gas/NEWS;;hb=refs/tags/binutils-2_4x 540 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=ld/NEWS;hb=refs/tags/binutils-2_4x 541 https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=binutils/NEWS;hb=refs/tags/binutils-2_4x 542 543 Our thanks go out to all of the binutils contributors, past and 544 present, for helping to make this release possible. 545 546 ----------------------------------------------------------------------- 547 548 31. Clean up the source tree: 549 550 git clean -fdx . 551 552 32. Edit bfd/development.sh on the branch and set the development flag 553 to "true". (Leave the experimental flag set to "false"). Also bump 554 the version in bfd/version.m4 by adding a trailing .0, so that the 555 date suffix keeps the version lower than the trunk version. 556 Regenerate files. Commit these changes. 557 558 33. Email the binutils list telling everyone that the 2.4x branch 559 is now open for business as usual and that patches no longer 560 need special approval. 561 562 34. Examine the bfd/config.bfd file in the mainline sources and move 563 any pending obsolete targets into the definitely obsolete 564 section. Create a changelog entry and commit. 565 566 Sit back and relax, you are all done. 567 568 -------------------------------------------------------------------------- 569 How to perform a POINT release. 570 -------------------------------------------------------------------------- 571 572 A point release is easier than a normal release since a lot of the 573 work has already been done. The branch has been created, the 574 translations updated and the documentation uploaded. So the procedure 575 looks like this: 576 577 0. Decide that a point release is necessary. 578 579 Usually this only happens when a sufficient number of serious 580 bugs have been found and fixed since the previous release, and a 581 new official release is not imminent. 582 583 1. Tell the community that a point release is happening. Ask 584 maintainers to ensure that their ports are up to date on the 585 release branch. Ask the community if there are any bug fixes 586 which are missing from the branch. Allow some time for the 587 responses to this step. 588 589 2. Make sure that the branch sources build, test and install 590 correctly. 591 592 2.5 Prepare a list of the bugs which have been fixed. This 593 will be needed for step 9. 594 595 3. In the branch sources: 596 597 a. Update the minor release number in bfd/version.m4. 598 b. Edit bfd/development.sh, set "development=false". 599 c. Regenerate the configure files. 600 d. Remove spurious autom4te.cache files: 601 602 git clean -fdx 603 604 e. Update the changelog: 605 606 gitlog-to-changelog --since=2021-07-03 > ChangeLog.git 607 608 f. Commit the updates along with a "this-is-the-2.4x.y-release" 609 comment. 610 611 git add . 612 git commit -m"..." 613 git push 614 615 f. Tag the branch with the new release number. Optional: add 616 "-u XXXXX" to sign with a gpg key, and -m "..." for a 617 comment. eg: 618 619 git tag -a binutils-2_43_1 620 or: 621 git tag -a binutils-2_43_1 -u DD9E3C4F -m "Official GNU Binutils 2.43.1 release" 622 623 Then push it: 624 625 git push origin binutils-2_43_1 626 627 g. Check that your file creation mask will create the 628 correct file permissions. Ie: 629 630 umask 022 631 632 h. Create the release tarballs: 633 634 ./src-release.sh -b -g -l -x -z [ binutils | binutils_with_gold ] 635 or: 636 ./src-release.sh -b -g -l -x -z 637 -r `git log -1 --format=%cd --date=format:%F bfd/version.m4` 638 [ binutils | binutils_with_gold ] 639 640 i. Check that the files in the tarballs have the correct 641 permissions. 642 643 tar tvf binutils-*.tar.xz | grep -e "---" 644 645 4. [If paranoid - upload the tarballs to one of the FTP servers and 646 ask people to test it before going on to step 5]. 647 648 5. Upload the tarballs to ftp.gnu.org. 649 650 gnupload --to ftp.gnu.org:binutils binutils-*.tar.* 651 652 The gnupload script is in the gnulib/build-aux directory. 653 654 6. Upload the tarballs to sourceware.org: 655 656 sftp sourceware.org 657 cd /sourceware/ftp/pub/binutils/releases 658 put binutils-*.tar.* 659 chmod 644 binutils-*.tar.* 660 quit 661 662 It is OK to upload the signatures as well. 663 664 7. Clean the source tree again 665 666 git clean -fdx 667 668 Edit bfd/development.sh and set "development=true". 669 670 Commit this change. 671 672 8. Update web pages. For sourceware.org: 673 674 * Clone the binutils documentation: git clone ssh://sourceware.org/git/binutils-htdocs 675 * Edit index.html and update the latest release number (if this 676 is a latest release). 677 * Add new documentation (if necessary). 678 * Commit and push the changes. 679 680 For the www.gnu.org site you have to email webmasters (a] gnu.org 681 and ask them to make the change(s). 682 683 9. Send an emails to the binutils list, info-gnu (a] gnu.org and 684 David Edelsohn <dje.gcc (a] gmail.com> announcing the new release. 685 (The email to Davis is so that he can update the GNU Toolchain 686 social media). Something like this: 687 688 ------------------------------------------------------------------------ 689 Hi Everyone, 690 691 We are pleased to announce that version 2.4x.y of the GNU Binutils 692 project sources have been released and are now available for download at: 693 694 https://ftp.gnu.org/gnu/binutils 695 https://sourceware.org/pub/binutils/releases/ 696 697 This is a point release over the previous 2.4x version, containing bug 698 fixes but no new features. 699 700 Our thanks go out to all of the binutils contributors, past and 701 present, for helping to make this release possible. 702 703 Here is a list of the bugs that have been fixed: 704 xx 705 xx 706 xx 707 xx 708 -------------------------------------------------------------------------- 709 710 10. Create a new Bugzilla entry for the point release. 711 712 https://sourceware.org/bugzilla/editversions.cgi?product=binutils 713 714 And a new milestone too: 715 716 https://sourceware.org/bugzilla/editmilestones.cgi?product=binutils 717 719 Copyright (C) 2017-2025 Free Software Foundation, Inc. 720 721 Copying and distribution of this file, with or without modification, 722 are permitted in any medium without royalty provided the copyright 723 notice and this notice are preserved. 724
Indexes created Sun Apr 19 00:22:55 UTC 2026