| README for MAKING BINUTILS RELEASES |
| |
| This is a collection of notes on how to perform a binutils release. A |
| lot of this information can also be found in the maintain.texi file in |
| the gnulib project: |
| |
| https://www.gnu.org/software/gnulib/ |
| |
| It is useful to have a cloned copy of the sources of this project as |
| it also contains an upload script used to install tarballs on the GNU |
| FTP server. |
| |
| Make sure that you have upload authority on sourceware and fencepost. |
| See the maintain.texi file for details on how to obtain these |
| permissions. |
| |
| Note - when performing a release it is helpful to edit this document |
| as you go, updating the example commands so that they are ready for |
| the release that follows. |
| |
| ------------------------------------------------- |
| How to perform a release. |
| ------------------------------------------------- |
| |
| 1. Choose dates for the branch and release. Weekends are better |
| because they are less busy. It is typical to leave two weeks |
| between creating the branch and creating the release. |
| |
| Send an email out warning contributors about the forthcoming |
| branch and release. |
| |
| 2. When the branch date is near: Update the libiberty and config |
| directories and the top level Makefile and configure files. Also |
| consider updating the toplevel libtool files. |
| |
| ------------------------------------------------- |
| How to create the release branch. |
| ------------------------------------------------- |
| |
| Approx time to complete from here: 2 hours ... |
| |
| 2.5 If you have not built from the sources recently then now is the |
| time to check that they still work... |
| |
| 3. When branch day arrives add markers for the upcoming release to |
| the NEWS files in gas, ld, and binutils. No need to update NEWS |
| in the gold directory - it has its own release numbering. |
| |
| Likewise for the ChangeLog files in: bfd, binutils, cpu, |
| elfcpp, gas, gold, gprof, include, ld, libctf, opcodes and toplevel. |
| |
| Add a note of the name of the new branch to binutils/BRANCHES. |
| |
| Commit these changes. |
| |
| 4. Create the release branch using: |
| |
| git branch binutils-2_44-branch |
| git push origin binutils-2_44-branch |
| |
| If you get a message like: |
| |
| remote: fatal: Invalid revision range 0000000000000000000000000000000000000000..f974f26cb16cc6fe3946f163c787a05e713fb77b |
| |
| It appears that this can be ignored... |
| |
| 5. Make sure that the branch is there. IE check out the branch sources: |
| |
| git clone ssh://sourceware.org/git/binutils-gdb.git -b binutils-2_44-branch 2.44 |
| |
| If you get a message about being in a "detached head" state, something |
| has gone wrong... |
| |
| Keep the checked out sources - they are going to be needed in future |
| steps. |
| |
| 6. Update "BINUTILS_BRANCH" in gdbadmin's crontab: |
| |
| Log in as gdbadmin on sourceware.org, and then: |
| |
| $ cd crontab |
| $ vi crontab |
| [change BINUTILS_BRANCH] |
| $ cvs ci crontab |
| $ crontab crontab |
| |
| If you do not have access to this account, please feel free to |
| ask Joel Brobecker <brobecker AT adacore DOT com>. |
| |
| 7. Rename the current HEAD version entry in Bugzilla, and create a |
| new one. E.g. rename "2.44 (HEAD)" to 2.44, and create |
| "2.45 (HEAD)": |
| |
| https://sourceware.org/bugzilla/editversions.cgi?product=binutils |
| |
| 8. Update bfd/version.m4 on HEAD to indicate that is now a snapshot |
| of the next release and the BRANCH to indicate that it is almost |
| ready for the release. |
| |
| So if the release is going to be 2.44 then the version number on |
| the BRANCH should be set to 2.43.90 - ie almost, but not quite 2.44, |
| and the version number on the MAINLINE should be set to 2.44.50 - |
| ie half way to 2.45 release. |
| |
| So the BRANCH bfd/version.m4 has: |
| |
| m4_define([BFD_VERSION], [2.43.90]) |
| |
| and the MAINLINE has: |
| |
| m4_define([BFD_VERSION], [2.44.50]) |
| |
| Regenerate various files on both branch and HEAD by configuring |
| with "--enable-maintainer-mode --enable-gold --enable-shared" and then building |
| with "make -j1 all-binutils all-gas all-gold all-gprof all-gprofng all-ld" |
| |
| Add ChangeLog entries for the updated files. Commit the changes. |
| Make sure that this includes the .pot files as well as the |
| configure and makefiles. |
| |
| 9. Create an initial pre-release: |
| |
| a. Remove any auto-generated files, in order to force the |
| src-release script to rebuild them. |
| |
| cd <branch-sources> |
| git clean -fdx |
| |
| b. Create a source tarball of the BRANCH sources: |
| |
| ./src-release.sh -x binutils |
| |
| FIXME: Not sure if the following steps are needed... |
| |
| Add a .dirstamp file to the gas/doc subdirectory: |
| |
| touch -d `date +%Y-%m-%d` binutils-2.43.90/gas/doc/.dirstamp |
| tar rvf binutils-2.43.90.tar binutils-2.43.90/gas/doc/.dirstamp |
| rm binutils-2.43.90.tar.xz |
| xz -9 -k binutils-2.43.90.tar |
| |
| ...END OF FIXME |
| |
| c. Build a test target using this tarball. |
| |
| cp binutils-*.tar.xz /dev/shm |
| pushd /dev/shm |
| tar xvf binutils-*.tar.xz |
| mkdir build |
| cd build |
| ../binutils-*/configure --quiet --enable-gold |
| make |
| popd |
| |
| If there are problems, fix them. |
| |
| d. Upload the pre-release snapshot to the sourceware FTP site: |
| |
| scp binutils-2.43.90.tar.xz sourceware.org:/var/ftp/pub/binutils/snapshots |
| ssh sourceware.org sha256sum ~ftp/pub/binutils/snapshots/binutils-2.43.90.tar.xz |
| |
| Paranoia: Compare the checksum with the local version. |
| |
| e. Clean up the source directory again. |
| |
| git clean -fdx |
| |
| 10. Tell the Translation Project where to find the new tarball. |
| <coordinator@translationproject.org> |
| qv: https://translationproject.org/html/maintainers.html |
| |
| ------------------------------------------------------------------------ |
| Dear Translation Project |
| |
| The 2.43 release branch has been created for the GNU Binutils project. |
| |
| A snapshot of the branch sources can be found here: |
| |
| https://sourceware.org/pub/binutils/snapshots/binutils-2.42.90.tar.xz |
| |
| We hope to make the official release of the sources on the <DATE> |
| although that could change if there are important bugs that need to |
| be fixed before the release. |
| ------------------------------------------------------------------------ |
| |
| 11. Announce the availability of the snapshot and the branch on the |
| binutils mailing list. Set a date for when the release will |
| actually happen. Something like: |
| |
| ------------------------------------------------------------------------ |
| Hi Everyone, |
| |
| The <NEW_VERSION> branch has now been created: |
| |
| git clone git://sourceware.org/git/binutils-gdb.git -b binutils-<NEW_VERSION>-branch |
| |
| A snapshot of the sources is also available here: |
| |
| https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz |
| |
| Please could all patches for the branch be run by me. |
| The rules for the branch are: |
| |
| * No new features. |
| * Target specific bug fixes are OK. |
| * Generic bug fixes are OK if they are important and widely tested. |
| * Documentation updates/fixes are OK. |
| * Translation updates are OK. |
| * Fixes for testsuite failures are OK. |
| |
| Ideally I would like to make the release happen in two weeks time, |
| i.e. <DATE>. Which I hope will be enough time for everyone |
| to get their final fixes in. |
| ------------------------------------------------------------------------ |
| |
| 12. Build various different toolchains, test them and nag |
| maintainers to fix any testsuite failures for their |
| architectures... |
| |
| ============================================================================== |
| ============================================================================== |
| |
| For the next few weeks, monitor the mailing list for new translations |
| and respond to any requests to have patches applied to the branch. |
| |
| ============================================================================== |
| ============================================================================== |
| |
| Then, a couple of weeks later ... |
| |
| ------------------------------------------------- |
| How to create the release. |
| ------------------------------------------------- |
| |
| 20. Make sure that the branch sources still build, test and install |
| correctly. Make sure that the sources are clean, without any |
| patch files (.reg .orig *~) left over. |
| |
| cd <branch> |
| git pull |
| git clean -fdx |
| cd <builds> |
| make |
| |
| 21. a. Update the release number in bfd/version.m4 on the release |
| branch to a whole new minor version number, without a point |
| value. Eg "2.43.90" becomes "2.44". NB/ Not: "2.44.00" |
| |
| b. Change bfd/development.sh to set all values to "false". |
| |
| c. Regenerate the configure and makefiles. And *info* files. |
| |
| cd <build-configured-with-enable-maintainer-mode> |
| make -j1 all-gas all-ld all-binutils all-gprof all-gold all-gprofng all-libctf |
| make info |
| |
| d. Create a ChangeLog from the git refs for all of the commits |
| from when changelog entries were no longer required: |
| |
| gitlog-to-changelog --since=2021-07-03 > ChangeLog.git |
| git add ChangeLog.git |
| |
| The gitlog-to-changelog script is part of the sources |
| of the "config" project. |
| |
| Add an entry for ChangeLog.git to the src-release.sh script's |
| DEVO_SUPPORT list, so that it is included in the release. |
| |
| FIXME: it would be better if the ChangeLog.git file was permanently |
| added to the src-release.sh script, but this mean that it would have |
| to exist in the master repository, and that the GDB project would |
| need to agree to have it there. |
| |
| e. Add ChangeLog entries for all of the updates and add a |
| "this-is-the-2.43-release" comment and commit. |
| |
| git add . |
| git commit -m "this-is-the-2.44-release" |
| git push |
| |
| 22. Check that your file creation mask will create the |
| correct file permissions. Eg: |
| |
| % umask |
| 22 |
| |
| Remove any spurious autom4te.cache files left over from the |
| reconfiguring: |
| |
| git clean -fdx |
| |
| 23. Note - check to see if any new files have been added to the top |
| level of the source directory, but which are not in the |
| DEVO_SUPPORT variable in the src-release.sh script. If they are |
| needed then add them. |
| |
| PARANOIA: Check that there are no pending commits: |
| |
| git status |
| |
| Then create the release tarballs: |
| |
| ./src-release.sh -b -g -l -x -z binutils |
| |
| OR ... for a more reproducible tarball: |
| |
| ./src-release.sh -b -g -l -x -z -r `git log -1 --format=%cd --date=format:%F bfd/version.m4` binutils |
| |
| 24. Check that the files in the tarballs have the correct |
| permissions. |
| |
| tar tvf binutils-*.tar.xz | grep -e "---" |
| |
| Also check that the man files are not empty. (cf PR 28144). |
| |
| tar tvf binutils-*.tar.xz | grep -e "\.1" |
| |
| 25. Sanity check the release on x86_64-pc-linux-gnu by building and |
| running the testsuites (gas, gold, binutils and ld). |
| Make the source directory read-only before building. |
| Also test 'make install'. |
| Also build the html and pdf documentation files. |
| If necessary fix any problems. |
| |
| pushd /dev/shm |
| mkdir delme |
| cd delme |
| tar xvf <path-to-sources>/binutils-2.*.tar.lz |
| chmod -R -w binutils-2.* |
| mkdir build |
| cd build |
| ../binutils-2.*/configure --quiet --enable-gold --prefix=`pwd`/install --enable-plugins --enable-shared |
| make -j1 all-gas all-gold all-ld all-binutils all-gprof all-gprofng |
| make check-gas check-binutils check-ld check-gold |
| make install-gas install-gold install-ld install-binutils install-gprofng |
| |
| # Needed for step 29... |
| make html pdf html-libctf pdf-libctf html-libsframe pdf-libsframe |
| |
| popd |
| |
| 26. Tag the branch with the new release number: |
| [optional: add "-u XXXXX" to sign with a gpg key] |
| enter a tag message such as: "Official GNU Binutils 2.4x release" |
| |
| git tag -a <TAG> -u <Your Key> |
| eg: |
| git tag -a binutils-2_44 -u DD9E3C4F <=== Be careful to get the tag right |
| or: |
| git tag -a binutils-2_44 -u DD9E3C4F -m "Official GNU Binutils 2.43 release" |
| |
| NB/ If you do sign the binaries make sure to use a key |
| that has been published with the FSF. |
| |
| Then push the release: |
| |
| git push origin binutils-2_44 |
| |
| If you get an error message along the lines of: |
| "Invalid revision range ..." |
| you can ignore it. |
| |
| 27. Upload the tarballs to ftp.gnu.org. |
| |
| gnupload --to ftp.gnu.org:binutils binutils-2.44.tar.* |
| |
| Be prepared to provide the password for the key, if you |
| signed the binaries. |
| |
| The gnupload script is in the gnulib/build-aux directory. |
| It uses the ncftp package for transmitting the files. |
| |
| NB/ This step can be done in PARALLEL with step 28. |
| |
| Check for an email response from the upload. If necessary |
| fix any problems. (The response might take a while, so |
| proceed with the next steps if you are confident that |
| everything is OK). |
| |
| 28. Upload the tarballs (and signatures) to sourceware.org: |
| |
| sftp sourceware.org |
| cd /sourceware/ftp/pub/binutils/releases |
| put binutils-2.4*.tar.* |
| chmod 644 binutils-2.4*.tar.* |
| quit |
| |
| 29. Update web pages. For sourceware.org: |
| |
| Clone the documentation (if you have not already done so): |
| |
| git clone ssh://sourceware.org/git/binutils-htdocs |
| |
| Create a new docs sub-directory and move into it: |
| |
| cd binutils-htdocs |
| mkdir docs-2.44 |
| cd docs-2.44 |
| |
| Copy the index.html from the previous release |
| |
| cp ../docs/index.html . |
| |
| Update the index.html file to reference this new release and to |
| point back to the current (now old) release. |
| |
| If necessary make the html documentation locally with the "make |
| html" command. (This should have been done by step 25 above). |
| |
| Copy in the documentation files: |
| |
| cp -r <build-dir>/gas/doc/as . |
| cp <build-dir>/gas/doc/as.html . |
| cp <build-dir>/gas/doc/as.pdf . |
| |
| cp -r <build-dir>/bfd/doc/bfd . |
| cp <build-dir>/bfd/doc/bfd.html . |
| cp <build-dir>/bfd/doc/bfd.pdf . |
| |
| cp -r <build-dir>/binutils/binutils_html binutils [NB/ Path not like others] |
| cp <build-dir>/binutils/doc/binutils.html . |
| cp <build-dir>/binutils/doc/binutils.pdf . |
| |
| cp -r <build-dir>/gprof/doc/gprof . |
| cp <build-dir>/gprof/gprof.html . [NB/ Path not like others] |
| cp <build-dir>/gprof/gprof.pdf . [NB/ Path not like others] |
| |
| cp -r <build-dir>/ld/doc/ld . |
| cp <build-dir>/ld/ld.html . [NB/ Path not like others] |
| cp <build-dir>/ld/ld.pdf . [NB/ Path not like others] |
| |
| [NB/ The gprofng documentation does not have a node-per-page selection] |
| cp <build-dir>/gprofng/doc/gprof.html . |
| cp <build-dir>/gprofng/doc/gprof.pdf . |
| |
| cp <build-dir>/libctf/doc/ctf-spec.html . |
| cp <build-dir>/libctf/doc/ctf-spec.pdf . |
| |
| cp <build-dir>/libsframe/doc/sframe-spec.html . |
| cp <build-dir>/libsframe/doc/sframe-spec.pdf . |
| |
| Update the symbolic link. |
| |
| cd .. [Should now be in be in binutils-htdocs/ ] |
| rm docs |
| ln -s docs-2.44 docs |
| |
| Edit index.html file to change the links to point to the new |
| release, mention any new features, update dates and so on. |
| |
| Check that the new web page is correct: |
| |
| file:///<path-to-binutils-htdocs>/index.html |
| |
| Add the new directories and files, commit and push the changes: |
| |
| git add . |
| git commit -m"Update documenation for the 2.4x release"a |
| git push |
| |
| |
| 29.1 For the www.gnu.org site you have to email webmasters@gnu.org |
| and ask them to copy the change(s): |
| --------------------------------------- |
| Hi FSF Webmasters, |
| |
| Please could the GNU Binutils webpage at: |
| |
| https://www.gnu.org/software/binutils/binutils.html |
| |
| be updated to indicate that there is now a newer version available |
| (2.4x). I have already updated the related page on the Sourceware |
| website so this might be useful as a template: |
| |
| https://sourceware.org/binutils/ |
| |
| Thanks very much. |
| |
| Cheers |
| -------------------------------------- |
| |
| 30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and |
| David Edelsohn <dje.gcc@gmail.com> announcing the new release. |
| Sign the email and include the checksum: |
| |
| sha256sum binutils-2.4*.tar.* |
| |
| (The email to Davis is so that he can update the GNU Toolchain |
| social media). Something like this: |
| ----------------------------------------------------------------------- |
| Hi Everyone, |
| |
| We are pleased to announce that version 2.4x of the GNU Binutils project |
| sources have been released and are now available for download at: |
| |
| https://ftp.gnu.org/gnu/binutils |
| https://sourceware.org/pub/binutils/releases/ |
| |
| checksums: xxxx |
| |
| As an experiment these tarballs were made with the new "-r <date>" |
| option supported by the src-release.sh script. This attempts to make |
| reproducible tarballs by sorting the files and passing the |
| "--mtime=<date>" option to tar. The date used for these tarballs was |
| obtained by running: |
| |
| git log -1 --format=%cd --date=format:%F bfd/version.m4 |
| |
| This release contains numerous bug fixes, and also the |
| following new features: |
| |
| <extract info from the NEWS files> |
| |
| For more information see: |
| |
| https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=gas/NEWS;;hb=refs/tags/binutils-2_4x |
| https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=ld/NEWS;hb=refs/tags/binutils-2_4x |
| https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=binutils/NEWS;hb=refs/tags/binutils-2_4x |
| |
| Our thanks go out to all of the binutils contributors, past and |
| present, for helping to make this release possible. |
| |
| ----------------------------------------------------------------------- |
| |
| 31. Clean up the source tree: |
| |
| git clean -fdx . |
| |
| 32. Edit bfd/development.sh on the branch and set the development flag |
| to "true". (Leave the experimental flag set to "false"). Also bump |
| the version in bfd/version.m4 by adding a trailing .0, so that the |
| date suffix keeps the version lower than the trunk version. |
| Regenerate files. Commit these changes. |
| |
| 33. Email the binutils list telling everyone that the 2.4x branch |
| is now open for business as usual and that patches no longer |
| need special approval. |
| |
| 34. Examine the bfd/config.bfd file in the mainline sources and move |
| any pending obsolete targets into the definitely obsolete |
| section. Create a changelog entry and commit. |
| |
| Sit back and relax, you are all done. |
| -------------------------------------------------------------------------- |
| How to perform a POINT release. |
| -------------------------------------------------------------------------- |
| |
| A point release is easier than a normal release since a lot of the |
| work has already been done. The branch has been created, the |
| translations updated and the documentation uploaded. So the procedure |
| looks like this: |
| |
| 0. Decide that a point release is necessary. |
| |
| Usually this only happens when a sufficient number of serious |
| bugs have been found and fixed since the previous release, and a |
| new official release is not imminent. |
| |
| 1. Tell the community that a point release is happening. Ask |
| maintainers to ensure that their ports are up to date on the |
| release branch. Ask the community if there are any bug fixes |
| which are missing from the branch. Allow some time for the |
| responses to this step. |
| |
| 2. Make sure that the branch sources build, test and install |
| correctly. |
| |
| 2.5 Prepare a list of the bugs which have been fixed. This |
| will be needed for step 9. |
| |
| 3. In the branch sources: |
| |
| a. Update the minor release number in bfd/version.m4. |
| b. Edit bfd/development.sh, set "development=false". |
| c. Regenerate the configure files. |
| d. Remove spurious autom4te.cache files: |
| |
| git clean -fdx |
| |
| e. Update the changelog: |
| |
| gitlog-to-changelog --since=2021-07-03 > ChangeLog.git |
| |
| f. Commit the updates along with a "this-is-the-2.4x.y-release" |
| comment. |
| |
| git add . |
| git commit -m"..." |
| git push |
| |
| f. Tag the branch with the new release number. Optional: add |
| "-u XXXXX" to sign with a gpg key, and -m "..." for a |
| comment. eg: |
| |
| git tag -a binutils-2_43_1 |
| or: |
| git tag -a binutils-2_43_1 -u DD9E3C4F -m "Official GNU Binutils 2.43.1 release" |
| |
| Then push it: |
| |
| git push origin binutils-2_43_1 |
| |
| g. Check that your file creation mask will create the |
| correct file permissions. Ie: |
| |
| umask 022 |
| |
| h. Create the release tarballs: |
| |
| ./src-release.sh -b -g -l -x -z binutils |
| or: |
| ./src-release.sh -b -g -l -x -z -r `git log -1 --format=%cd --date=format:%F bfd/version.m4` binutils |
| |
| i. Check that the files in the tarballs have the correct |
| permissions. |
| |
| tar tvf binutils-*.tar.xz | grep -e "---" |
| |
| 4. [If paranoid - upload the tarballs to one of the FTP servers and |
| ask people to test it before going on to step 5]. |
| |
| 5. Upload the tarballs to ftp.gnu.org. |
| |
| gnupload --to ftp.gnu.org:binutils binutils-*.tar.* |
| |
| The gnupload script is in the gnulib/build-aux directory. |
| |
| 6. Upload the tarballs to sourceware.org: |
| |
| sftp sourceware.org |
| cd /sourceware/ftp/pub/binutils/releases |
| put binutils-*.tar.* |
| chmod 644 binutils-*.tar.* |
| quit |
| |
| It is OK to upload the signatures as well. |
| |
| 7. Clean the source tree again |
| |
| git clean -fdx |
| |
| Edit bfd/development.sh and set "development=true". |
| |
| Commit this change. |
| |
| 8. Update web pages. For sourceware.org: |
| |
| * Clone the binutils documentation: git clone ssh://sourceware.org/git/binutils-htdocs |
| * Edit index.html and update the latest release number (if this |
| is a latest release). |
| * Add new documentation (if necessary). |
| * Commit and push the changes. |
| |
| For the www.gnu.org site you have to email webmasters@gnu.org |
| and ask them to make the change(s). |
| |
| 9. Send an emails to the binutils list, info-gnu@gnu.org and |
| David Edelsohn <dje.gcc@gmail.com> announcing the new release. |
| (The email to Davis is so that he can update the GNU Toolchain |
| social media). Something like this: |
| |
| ------------------------------------------------------------------------ |
| Hi Everyone, |
| |
| We are pleased to announce that version 2.4x.y of the GNU Binutils |
| project sources have been released and are now available for download at: |
| |
| https://ftp.gnu.org/gnu/binutils |
| https://sourceware.org/pub/binutils/releases/ |
| |
| This is a point release over the previous 2.4x version, containing bug |
| fixes but no new features. |
| |
| Our thanks go out to all of the binutils contributors, past and |
| present, for helping to make this release possible. |
| |
| Here is a list of the bugs that have been fixed: |
| xx |
| xx |
| xx |
| xx |
| -------------------------------------------------------------------------- |
| |
| 10. Create a new Bugzilla entry for the point release. |
| |
| https://sourceware.org/bugzilla/editversions.cgi?product=binutils |
| |
| And a new milestone too: |
| |
| https://sourceware.org/bugzilla/editmilestones.cgi?product=binutils |
| |
| Copyright (C) 2017-2024 Free Software Foundation, Inc. |
| |
| Copying and distribution of this file, with or without modification, |
| are permitted in any medium without royalty provided the copyright |
| notice and this notice are preserved. |
