arm, objdump: print obsolote warning when 26-bit set in instructions
[binutils-gdb.git] / binutils / README-how-to-make-a-release
blobcce2ed768eeed60cd7a4bdf998ab893b09c0b46c
1                 README for MAKING BINUTILS RELEASES
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:
7   https://www.gnu.org/software/gnulib/
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.
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.
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.
21 -------------------------------------------------
22 How to perform a release.
23 -------------------------------------------------
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.
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.
36 -------------------------------------------------
37 How to create the release branch.
38 -------------------------------------------------
40 Approx time to complete from here: 2 hours ...
42   2.5 If you have not built from the sources recently then now is the
43       time to check that they still work...
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.
49      Likewise for the ChangeLog files in: bfd, binutils, cpu,
50      elfcpp, gas, gold, gprof, include, ld, libctf, opcodes and toplevel.
52      Add a note of the name of the new branch to binutils/BRANCHES.
54      Commit these changes.
56   4. Create the release branch using:
58         git branch binutils-2_44-branch
59         git push origin binutils-2_44-branch
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...
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_44-branch 2.44
71      If you get a message about being in a "detached head" state, something
72      has gone wrong...
74      Keep the checked out sources - they are going to be needed in future
75      steps.
77   6. Update "BINUTILS_BRANCH" in gdbadmin's crontab:
79      Log in as gdbadmin on sourceware.org, and then:
81         $ cd crontab
82         $ vi crontab
83         [change BINUTILS_BRANCH]
84         $ cvs ci crontab
85         $ crontab crontab
87      If you do not have access to this account, please feel free to
88      ask Joel Brobecker <brobecker AT adacore DOT com>.
90   7. Rename the current HEAD version entry in Bugzilla, and create a
91      new one.  E.g. rename "2.44 (HEAD)" to 2.44, and create
92      "2.45 (HEAD)":
93      
94         https://sourceware.org/bugzilla/editversions.cgi?product=binutils
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.
100      So if the release is going to be 2.44 then the version number on
101      the BRANCH should be set to 2.43.90 - ie almost, but not quite 2.44,
102      and the version number on the MAINLINE should be set to 2.44.50 -
103      ie half way to 2.45 release.
105      So the BRANCH bfd/version.m4 has:
106      
107        m4_define([BFD_VERSION], [2.43.90])
108        
109      and the MAINLINE has:
111        m4_define([BFD_VERSION], [2.44.50])
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"
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.
121   9. Create an initial pre-release:
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:
131           ./src-release.sh -x binutils
133         FIXME: Not sure if the following steps are needed...
134         
135         Add a .dirstamp file to the gas/doc subdirectory:
137           touch -d `date +%Y-%m-%d` binutils-2.43.90/gas/doc/.dirstamp
138           tar rvf binutils-2.43.90.tar binutils-2.43.90/gas/doc/.dirstamp
139           rm binutils-2.43.90.tar.xz
140           xz -9 -k binutils-2.43.90.tar
142          ...END OF FIXME   
144      c. Build a test target using this tarball.
146            cp binutils-*.tar.xz /dev/shm
147            pushd /dev/shm
148            tar xvf binutils-*.tar.xz
149            mkdir build
150            cd build
151            ../binutils-*/configure --quiet --enable-gold
152            make
153            popd
155         If there are problems, fix them.
157      d. Upload the pre-release snapshot to the sourceware FTP site:
159           scp binutils-2.43.90.tar.xz sourceware.org:/var/ftp/pub/binutils/snapshots
160           ssh sourceware.org sha256sum ~ftp/pub/binutils/snapshots/binutils-2.43.90.tar.xz
162         Paranoia: Compare the checksum with the local version.
164      e. Clean up the source directory again.
166          git clean -fdx
168   10. Tell the Translation Project where to find the new tarball.
169       <coordinator@translationproject.org>
170       qv: https://translationproject.org/html/maintainers.html
172 ------------------------------------------------------------------------
173 Dear Translation Project
175   The 2.43 release branch has been created for the GNU Binutils project.
177   A snapshot of the branch sources can be found here:
179     https://sourceware.org/pub/binutils/snapshots/binutils-2.42.90.tar.xz
181   We hope to make the official release of the sources on the <DATE>
182   although that could change if there are important bugs that need to
183   be fixed before the release.
184 ------------------------------------------------------------------------
186   11. Announce the availability of the snapshot and the branch on the
187       binutils mailing list.  Set a date for when the release will
188       actually happen.  Something like:
189       
190 ------------------------------------------------------------------------
191 Hi Everyone, 
193   The <NEW_VERSION> branch has now been created:
195      git clone git://sourceware.org/git/binutils-gdb.git -b binutils-<NEW_VERSION>-branch
197   A snapshot of the sources is also available here:
199     https://sourceware.org/pub/binutils/snapshots/binutils-<OLD_VERSION>.90.tar.xz
201   Please could all patches for the branch be run by me.
202   The rules for the branch are:
204     * No new features.
205     * Target specific bug fixes are OK.
206     * Generic bug fixes are OK if they are important and widely tested.
207     * Documentation updates/fixes are OK.
208     * Translation updates are OK.
209     * Fixes for testsuite failures are OK.
211   Ideally I would like to make the release happen in two weeks time,
212   i.e. <DATE>.  Which I hope will be enough time for everyone
213   to get their final fixes in.
214 ------------------------------------------------------------------------
216   12. Build various different toolchains, test them and nag
217       maintainers to fix any testsuite failures for their
218       architectures...
220 ==============================================================================
221 ==============================================================================
223 For the next few weeks, monitor the mailing list for new translations
224 and respond to any requests to have patches applied to the branch.
226 ==============================================================================
227 ==============================================================================
229 Then, a couple of weeks later ...
231 -------------------------------------------------
232 How to create the release.
233 -------------------------------------------------
235   20. Make sure that the branch sources still build, test and install 
236       correctly.  Make sure that the sources are clean, without any
237       patch files (.reg .orig *~) left over.
239          cd <branch>
240          git pull        
241          git clean -fdx
242          cd <builds>
243          make
245   21. a. Update the release number in bfd/version.m4 on the release
246          branch to a whole new minor version number, without a point
247          value.  Eg "2.43.90" becomes "2.44".  NB/ Not: "2.44.00"
249       b. Change bfd/development.sh to set all values to "false".
251       c. Regenerate the configure and makefiles.  And *info* files.
253             cd <build-configured-with-enable-maintainer-mode>
254             make -j1 all-gas all-ld all-binutils all-gprof all-gold all-gprofng all-libctf
255             make info
257       d. Create a ChangeLog from the git refs for all of the commits
258          from when changelog entries were no longer required:
260            gitlog-to-changelog --since=2021-07-03 > ChangeLog.git
261            git add ChangeLog.git
263          The gitlog-to-changelog script is part of the sources
264          of the "config" project.
266          Add an entry for ChangeLog.git to the src-release.sh script's
267          DEVO_SUPPORT list, so that it is included in the release.
269          FIXME: it would be better if the ChangeLog.git file was permanently
270          added to the src-release.sh script, but this mean that it would have
271          to exist in the master repository, and that the GDB project would
272          need to agree to have it there.
273         
274       e. Add ChangeLog entries for all of the updates and add a
275          "this-is-the-2.43-release" comment and commit.
277            git add .
278            git commit -m "this-is-the-2.44-release"
279            git push
280            
281   22. Check that your file creation mask will create the
282       correct file permissions.  Eg:
284             % umask
285             22
287       Remove any spurious autom4te.cache files left over from the
288       reconfiguring:
290             git clean -fdx
292   23. Note - check to see if any new files have been added to the top
293       level of the source directory, but which are not in the
294       DEVO_SUPPORT variable in the src-release.sh script.  If they are
295       needed then add them.
297       PARANOIA: Check that there are no pending commits:
299              git status
301       Then create the release tarballs:
302   
303             ./src-release.sh -b -g -l -x -z binutils
305       OR ... for a more reproducible tarball:
307             ./src-release.sh -b -g -l -x -z -r `git log -1 --format=%cd --date=format:%F bfd/version.m4` binutils
309   24. Check that the files in the tarballs have the correct
310       permissions.
312            tar tvf binutils-*.tar.xz | grep -e "---"
314       Also check that the man files are not empty.  (cf PR 28144).
316            tar tvf binutils-*.tar.xz | grep -e "\.1"
318   25. Sanity check the release on x86_64-pc-linux-gnu by building and
319        running the testsuites (gas, gold, binutils and ld).
320       Make the source directory read-only before building.
321       Also test 'make install'.
322       Also build the html and pdf documentation files.
323       If necessary fix any problems.
325         pushd /dev/shm
326         mkdir delme
327         cd delme
328         tar xvf <path-to-sources>/binutils-2.*.tar.lz
329         chmod -R -w binutils-2.*
330         mkdir build
331         cd build
332         ../binutils-2.*/configure --quiet --enable-gold --prefix=`pwd`/install --enable-plugins --enable-shared
333         make -j1 all-gas all-gold all-ld all-binutils all-gprof all-gprofng
334         make check-gas check-binutils check-ld check-gold
335         make install-gas install-gold install-ld install-binutils install-gprofng
337         # Needed for step 29...
338         make html pdf html-libctf pdf-libctf html-libsframe pdf-libsframe
340         popd
342   26. Tag the branch with the new release number:
343         [optional: add "-u XXXXX" to sign with a gpg key]
344         enter a tag message such as: "Official GNU Binutils 2.4x release"
346             git tag -a <TAG>         -u <Your Key>
347           eg:
348             git tag -a binutils-2_44 -u DD9E3C4F      <=== Be careful to get the tag right
349           or:
350             git tag -a binutils-2_44 -u DD9E3C4F -m "Official GNU Binutils 2.43 release"
352         NB/ If you do sign the binaries make sure to use a key
353         that has been published with the FSF.
355         Then push the release:
356         
357             git push origin binutils-2_44
359         If you get an error message along the lines of:
360           "Invalid revision range ..."
361         you can ignore it.
363   27.  Upload the tarballs to ftp.gnu.org.
365           gnupload --to ftp.gnu.org:binutils binutils-2.44.tar.*
367         Be prepared to provide the password for the key, if you
368         signed the binaries.
369       
370         The gnupload script is in the gnulib/build-aux directory.
371         It uses the ncftp package for transmitting the files.
373         NB/ This step can be done in PARALLEL with step 28.
375         Check for an email response from the upload.  If necessary
376         fix any problems.  (The response might take a while, so
377         proceed with the next steps if you are confident that
378         everything is OK).
380   28. Upload the tarballs (and signatures) to sourceware.org:
382        sftp sourceware.org
383          cd /sourceware/ftp/pub/binutils/releases
384          put binutils-2.4*.tar.*
385          chmod 644 binutils-2.4*.tar.*
386          quit
388   29. Update web pages.  For sourceware.org:
390       Clone the documentation (if you have not already done so):
391       
392         git clone ssh://sourceware.org/git/binutils-htdocs
393       
394       Create a new docs sub-directory and move into it:
396         cd binutils-htdocs
397         mkdir docs-2.44
398         cd docs-2.44
399         
400       Copy the index.html from the previous release
402         cp ../docs/index.html .
404       Update the index.html file to reference this new release and to
405       point back to the current (now old) release.
407       If necessary make the html documentation locally with the "make
408       html" command.  (This should have been done by step 25 above).
410       Copy in the documentation files:
411       
412          cp -r <build-dir>/gas/doc/as    .
413          cp <build-dir>/gas/doc/as.html  .
414          cp <build-dir>/gas/doc/as.pdf   .
415          
416          cp -r <build-dir>/bfd/doc/bfd   .
417          cp <build-dir>/bfd/doc/bfd.html .
418          cp <build-dir>/bfd/doc/bfd.pdf  .
420          cp -r <build-dir>/binutils/binutils_html  binutils    [NB/ Path not like others]
421          cp <build-dir>/binutils/doc/binutils.html .
422          cp <build-dir>/binutils/doc/binutils.pdf  .
424          cp -r <build-dir>/gprof/doc/gprof     .
425          cp <build-dir>/gprof/gprof.html   .                [NB/ Path not like others]
426          cp <build-dir>/gprof/gprof.pdf    .                [NB/ Path not like others]
427          
428          cp -r <build-dir>/ld/doc/ld     .
429          cp <build-dir>/ld/ld.html   .              [NB/ Path not like others]
430          cp <build-dir>/ld/ld.pdf    .              [NB/ Path not like others]
432             [NB/ The gprofng documentation does not have a node-per-page selection]
433          cp <build-dir>/gprofng/doc/gprof.html   .
434          cp <build-dir>/gprofng/doc/gprof.pdf    .
435          
436          cp <build-dir>/libctf/doc/ctf-spec.html   .
437          cp <build-dir>/libctf/doc/ctf-spec.pdf    .
439          cp <build-dir>/libsframe/doc/sframe-spec.html   .
440          cp <build-dir>/libsframe/doc/sframe-spec.pdf    .
442       Update the symbolic link.
444          cd ..     [Should now be in be in binutils-htdocs/ ]
445          rm docs
446          ln -s docs-2.44 docs
447          
448       Edit index.html file to change the links to point to the new
449       release, mention any new features, update dates and so on.
451       Check that the new web page is correct:
453          file:///<path-to-binutils-htdocs>/index.html
455       Add the new directories and files, commit and push the changes:
457         git add .
458         git commit -m"Update documenation for the 2.4x release"a
459         git push
462   29.1 For the www.gnu.org site you have to email webmasters@gnu.org
463       and ask them to copy the change(s):
464 ---------------------------------------
465 Hi FSF Webmasters,
467   Please could the GNU Binutils webpage at:
469 https://www.gnu.org/software/binutils/binutils.html
471   be updated to indicate that there is now a newer version available
472   (2.4x).  I have already updated the related page on the Sourceware
473   website so this might be useful as a template:
475 https://sourceware.org/binutils/
477   Thanks very much.
479 Cheers
480 --------------------------------------  
482   30. Send emails to binutils@sourceware.org, info-gnu@gnu.org and
483       David Edelsohn <dje.gcc@gmail.com> announcing the new release.
484       Sign the email and include the checksum:
486           sha256sum binutils-2.4*.tar.*
488       (The email to Davis is so that he can update the GNU Toolchain
489       social media).  Something like this:
490       -----------------------------------------------------------------------
491         Hi Everyone,
493         We are pleased to announce that version 2.4x of the GNU Binutils project
494         sources have been released and are now available for download at:
496           https://ftp.gnu.org/gnu/binutils
497           https://sourceware.org/pub/binutils/releases/
499           checksums: xxxx
501         As an experiment these tarballs were made with the new "-r <date>"
502         option supported by the src-release.sh script.  This attempts to make
503         reproducible tarballs by sorting the files and passing the
504         "--mtime=<date>" option to tar.  The date used for these tarballs was
505         obtained by running:
506   
507           git log -1 --format=%cd --date=format:%F bfd/version.m4
509         This release contains numerous bug fixes, and also the
510         following new features:
512           <extract info from the NEWS files>
514         For more information see:
515         
516           https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=gas/NEWS;;hb=refs/tags/binutils-2_4x
517           https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=ld/NEWS;hb=refs/tags/binutils-2_4x
518           https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;a=blob_plain;f=binutils/NEWS;hb=refs/tags/binutils-2_4x
520         Our thanks go out to all of the binutils contributors, past and
521         present, for helping to make this release possible.
523       -----------------------------------------------------------------------
525   31. Clean up the source tree:
527         git clean -fdx .
529   32. Edit bfd/development.sh on the branch and set the development flag
530       to "true".  (Leave the experimental flag set to "false").  Also bump
531       the version in bfd/version.m4 by adding a trailing .0, so that the
532       date suffix keeps the version lower than the trunk version.
533       Regenerate files.  Commit these changes.
535   33. Email the binutils list telling everyone that the 2.4x branch
536       is now open for business as usual and that patches no longer
537       need special approval.
539   34. Examine the bfd/config.bfd file in the mainline sources and move
540       any pending obsolete targets into the definitely obsolete
541       section.  Create a changelog entry and commit.
543   Sit back and relax, you are all done.
544 --------------------------------------------------------------------------
545 How to perform a POINT release.
546 --------------------------------------------------------------------------
548 A point release is easier than a normal release since a lot of the
549 work has already been done.  The branch has been created, the
550 translations updated and the documentation uploaded.  So the procedure
551 looks like this:
553   0. Decide that a point release is necessary.
555      Usually this only happens when a sufficient number of serious
556      bugs have been found and fixed since the previous release, and a
557      new official release is not imminent.
559   1. Tell the community that a point release is happening.  Ask
560      maintainers to ensure that their ports are up to date on the
561      release branch.  Ask the community if there are any bug fixes
562      which are missing from the branch.  Allow some time for the
563      responses to this step.
565   2. Make sure that the branch sources build, test and install
566      correctly.
568   2.5 Prepare a list of the bugs which have been fixed.  This
569       will be needed for step 9.
571   3. In the branch sources:
573        a. Update the minor release number in bfd/version.m4.
574        b. Edit bfd/development.sh, set "development=false".
575        c. Regenerate the configure files.
576        d. Remove spurious autom4te.cache files:
578           git clean -fdx
580         e. Update the changelog:
581         
582            gitlog-to-changelog --since=2021-07-03 > ChangeLog.git
583           
584        f. Commit the updates along with a "this-is-the-2.4x.y-release"
585           comment.
587              git add .
588              git commit -m"..."
589              git push
590              
591        f. Tag the branch with the new release number.  Optional: add
592           "-u XXXXX" to sign with a gpg key, and -m "..." for a
593           comment.  eg:
594           
595                git tag -a binutils-2_43_1
596           or:       
597                git tag -a binutils-2_43_1 -u DD9E3C4F -m "Official GNU Binutils 2.43.1 release"
599           Then push it:
600           
601             git push origin binutils-2_43_1
603        g. Check that your file creation mask will create the
604           correct file permissions.  Ie:
606             umask 022
608        h. Create the release tarballs:
609        
610               ./src-release.sh -b -g -l -x -z binutils
611           or: 
612               ./src-release.sh -b -g -l -x -z -r `git log -1 --format=%cd --date=format:%F bfd/version.m4` binutils
614        i. Check that the files in the tarballs have the correct
615           permissions.
617            tar tvf binutils-*.tar.xz | grep -e "---"
619   4. [If paranoid - upload the tarballs to one of the FTP servers and
620       ask people to test it before going on to step 5].
622   5. Upload the tarballs to ftp.gnu.org.
624        gnupload --to ftp.gnu.org:binutils binutils-*.tar.*
626      The gnupload script is in the gnulib/build-aux directory.
628   6. Upload the tarballs to sourceware.org:
630        sftp sourceware.org
631          cd /sourceware/ftp/pub/binutils/releases
632          put binutils-*.tar.*
633          chmod 644 binutils-*.tar.*
634          quit
636    It is OK to upload the signatures as well.
638    7. Clean the source tree again
639        
640          git clean -fdx
641             
642        Edit bfd/development.sh and set "development=true".
643        
644        Commit this change.
646   8. Update web pages.  For sourceware.org:
648       * Clone the binutils documentation: git clone ssh://sourceware.org/git/binutils-htdocs
649       * Edit index.html and update the latest release number (if this
650         is a latest release).
651       * Add new documentation (if necessary).
652       * Commit and push the changes.
654       For the www.gnu.org site you have to email webmasters@gnu.org
655       and ask them to make the change(s).
657   9. Send an emails to the binutils list, info-gnu@gnu.org and
658      David Edelsohn <dje.gcc@gmail.com> announcing the new release.
659      (The email to Davis is so that he can update the GNU Toolchain
660      social media).  Something like this:
662 ------------------------------------------------------------------------
663 Hi Everyone,
665   We are pleased to announce that version 2.4x.y of the GNU Binutils
666   project sources have been released and are now available for download at:
668     https://ftp.gnu.org/gnu/binutils
669     https://sourceware.org/pub/binutils/releases/
671   This is a point release over the previous 2.4x version, containing bug
672   fixes but no new features.
674   Our thanks go out to all of the binutils contributors, past and
675   present, for helping to make this release possible.
677   Here is a list of the bugs that have been fixed:
678     xx
679     xx
680     xx
681     xx
682 --------------------------------------------------------------------------
684   10. Create a new Bugzilla entry for the point release.
685      
686        https://sourceware.org/bugzilla/editversions.cgi?product=binutils
688      And a new milestone too:
690        https://sourceware.org/bugzilla/editmilestones.cgi?product=binutils
692 Copyright (C) 2017-2024 Free Software Foundation, Inc.
694 Copying and distribution of this file, with or without modification,
695 are permitted in any medium without royalty provided the copyright
696 notice and this notice are preserved.