mingw/info/gdbint/Releasing-GDB.html

   1 <html lang="en">
   2 <head>
   3 <title>GDB Internals</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="GDB Internals">
   6 <meta name="generator" content="makeinfo 4.3">
   7 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home">
   8 </head>
   9 <body>
  10 <div class="node">
  11 <p>
  12 Node:<a name="Releasing%20GDB">Releasing GDB</a>,
  13 Next:<a rel="next" accesskey="n" href="Testsuite.html#Testsuite">Testsuite</a>,
  14 Previous:<a rel="previous" accesskey="p" href="Porting-GDB.html#Porting%20GDB">Porting GDB</a>,
  15 Up:<a rel="up" accesskey="u" href="index.html#Top">Top</a>
  16 <hr><br>
  17 </div>
  18
  19 <h2 class="chapter">Releasing GDB</h2>
  20
  21 <h3 class="section">Obsolete any code</h3>
  22
  23    <p>Before anything else, poke the other developers (and around the source
  24 code) to see if there is anything that can be removed from GDB
  25 (an old target, an unused file).
  26
  27    <p>Obsolete code is identified by adding an <code>OBSOLETE</code> prefix to every
  28 line.  Doing this means that it is easy to identify obsolete code when
  29 grepping through the sources.
  30
  31    <p>The process has a number of steps and is intentionally slow -- this is
  32 to mainly ensure that people have had a reasonable chance to respond.
  33 Remember, everything on the internet takes a week.
  34
  35      <ul>
  36 <li>announce the change on <a href="mailto:gdb@sources.redhat.com">GDB mailing list</a>
  37 <li>wait a week or so
  38 <li>announce the change on <a href="mailto:gdb-announce@sources.redhat.com">GDB Announcement mailing list</a>
  39 <li>wait a week or so
  40 <li>go through and edit all relevant files and lines (e.g., in
  41 <code>configure.tgt</code>) so that they are prefixed with the word
  42 <code>OBSOLETE</code>.
  43 </ul>
  44
  45    <p><em>Maintainer note: Removing old code, while regrettable, is a good
  46 thing.  Firstly it helps the developers by removing code that is either
  47 no longer relevant or simply wrong.  Secondly since it removes any
  48 history associated with the file (effectively clearing the slate) the
  49 developer has a much freer hand when it comes to fixing broken files.</em>
  50
  51 <h3 class="section">Before the branch</h3>
  52
  53    <p>The most important objective at this stage is to find and fix simple
  54 changes that become a pain to track once the branch is created.  For
  55 instance, configuration problems that stop GDB from even
  56 building.  If you can't get the problem fixed, document it in the
  57 <code>gdb/PROBLEMS</code> file.
  58
  59 <h4 class="subheading">Organize and announce the schedule.</h4>
  60
  61    <p>The following is a possible schedule.  It is based on the rule-of-thumb
  62 that everything on the Internet takes a week.  You may want to even
  63 increase those times further since an analysis of the actual data
  64 strongly suggests that the below is far to aggressive.
  65
  66      <ul>
  67 <li>announce it
  68 <li>wait a week
  69 <li>announce branch date
  70 <li>wait a week
  71 <li>Cut the branch
  72 <li>wait a week
  73 <li>start enjoying all the fun
  74 </ul>
  75
  76    <p>As an aside, the branch tag name is probably regrettable vis:
  77 <pre class="example">     gdb_N_M-YYYY-MM-DD-{branch,branchpoint}
  78      </pre>
  79
  80 <h4 class="subheading">Refresh any imported files.</h4>
  81
  82    <p>A number of files are taken from external repositories.  They include:
  83
  84      <ul>
  85 <li><code>texinfo/texinfo.tex</code>
  86 <li><code>config.guess</code> et. al.
  87 </ul>
  88
  89    <p>and should be refreshed.
  90
  91 <h4 class="subheading">Prompt for <code>gdb/NEWS</code></h4>
  92
  93    <p>People always forget.  Send a post reminding them but also if you know
  94 something interesting happened add it your self.
  95
  96 <h4 class="subheading">Review <code>gdb/README</code></h4>
  97
  98    <p>Grab one of the nightly snapshots and then walk through the
  99 <code>gdb/README</code> looking for anything that can be improved.
 100
 101 <h4 class="subheading">Check the ARI</h4>
 102
 103    <p>ARI is an <code>awk</code> script (Awk Regression Indicator?) that checks for a
 104 number of errors and coding conventions.  The checks include things like
 105 using <code>malloc</code> instead of <code>xmalloc</code> and file naming problems.
 106 There shouldn't be any regressions.
 107
 108 <h3 class="section">Cut the branch</h3>
 109
 110 <h4 class="subheading">The dirty work</h4>
 111
 112    <p>I think something like the below was used:
 113
 114 <pre class="example">     $  d=`date -u +%Y-%m-%d`
 115      $  echo $d
 116      2002-01-24
 117      $  cvs -f -d /cvs/src rtag -D $d-gmt \
 118      gdb_5_1-$d-branchpoint insight+dejagnu
 119      $  cvs -f -d /cvs/src rtag -b -r gdb_V_V-$d-branchpoint \
 120      gdb_5_1-$d-branch insight+dejagnu
 121      $
 122      </pre>
 123
 124      <ul>
 125 <li>the <kbd>-D YYYY-MM-DD-gmt</kbd> forces the branch to an exact date/time.
 126 <li>the trunk is first taged so that the branch point can easily be found
 127 <li>Insight (which includes GDB) and dejagnu are tagged at the same time
 128 </ul>
 129
 130 <h4 class="subheading">Post the branch info</h4>
 131
 132 <h4 class="subheading">Update the web and news pages</h4>
 133
 134 <h4 class="subheading">Tweak cron to track the new branch</h4>
 135
 136 <h3 class="section">Stabilize the branch</h3>
 137
 138    <p>Something goes here.
 139
 140 <h3 class="section">Create a Release</h3>
 141
 142    <p>This procedure can be followed when creating beta and final final
 143 releases.  With a beta many of the steps can be skipped.
 144
 145 <h4 class="subheading">Establish a few defaults.</h4>
 146
 147 <pre class="example">     $  b=gdb_5_1-2001-07-29-branch
 148      $  v=5.1.1
 149      $  t=/sourceware/snapshot-tmp/gdbadmin-tmp
 150      $  echo $t/$b/$v
 151      $  mkdir -p $t/$b/$v
 152      $  cd $t/$b/$v
 153      $  pwd
 154      /sourceware/snapshot-tmp/gdbadmin-tmp/gdb_5_1-2001-07-29-branch/5.1.1
 155      $  which autoconf
 156      /home/gdbadmin/bin/autoconf
 157      $
 158      </pre>
 159
 160    <p>NB: Check the autoconf version carefully.  You want to be using the
 161 version taken from the binutils snapshot directory.  It is most likely
 162 that your system's installed version (<code>/usr/bin</code>?) is probably
 163 correct.
 164
 165 <h4 class="subheading">Check out the relevant modules:</h4>
 166
 167 <pre class="example">     $  for m in gdb insight dejagnu
 168      do
 169      ( mkdir -p $m &amp;&amp; cd $m &amp;&amp; cvs -q -f -d /cvs/src co -P -r $b $m )
 170      done
 171      $
 172      </pre>
 173
 174    <p>NB: The reading of <code>.cvsrc</code> is disabled (<code>-f</code>) so that there
 175 isn't any confusion between what is written here and what your local CVS
 176 really does.
 177
 178 <h4 class="subheading">Update relevant files.</h4>
 179
 180 <h5 class="subsubheading"><code>gdb/NEWS</code></h5>
 181
 182    <p>Major releases get their comments added as part of the mainline.  Minor
 183 releases should probably mention any significant bugs that were fixed.
 184
 185    <p>Don't forget to update the ChangeLog.
 186
 187 <pre class="example">     $  emacs gdb/src/gdb/NEWS
 188      ...
 189      c-x 4 a
 190      ...
 191      c-x c-s c-x c-c
 192      $  cp gdb/src/gdb/NEWS insight/src/gdb/NEWS
 193      $  cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
 194      </pre>
 195
 196 <h5 class="subsubheading"><code>gdb/README</code></h5>
 197
 198    <p>You'll need to update: the version, the update date, and who did it.
 199
 200 <pre class="example">     $  emacs gdb/src/gdb/README
 201      ...
 202      c-x 4 a
 203      ...
 204      c-x c-s c-x c-c
 205      $  cp gdb/src/gdb/README insight/src/gdb/README
 206      $  cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
 207      </pre>
 208
 209    <p><em>Maintainer note: Hopefully the README file was reviewed before the
 210 initial branch was cut so just a simple substitute is needed to get it
 211 updated.</em>
 212
 213    <p><em>Maintainer note: Other projects generate </em><code>README</code><em> and
 214 </em><code>INSTALL</code><em> from the core documentation.  This might be worth
 215 pursuing.</em>
 216
 217 <h5 class="subsubheading"><code>gdb/version.in</code></h5>
 218
 219 <pre class="example">     $  echo $v &gt; gdb/src/gdb/version.in
 220      $  emacs gdb/src/gdb/version.in
 221      ...
 222      c-x 4 a
 223      ...
 224      c-x c-s c-x c-c
 225      $  cp gdb/src/gdb/version.in insight/src/gdb/version.in
 226      $  cp gdb/src/gdb/ChangeLog insight/src/gdb/ChangeLog
 227      </pre>
 228
 229 <h5 class="subsubheading"><code>dejagnu/src/dejagnu/configure.in</code></h5>
 230
 231    <p>Dejagnu is more complicated.  The version number is a parameter to
 232 <var>AM_INIT_AUTOMAKE</var>.  Tweak it to read something like
 233 <var>gdb-5.1.1</var>.
 234
 235    <p>Re-generate configure.
 236
 237    <p>Add a ChangeLog.
 238
 239 <h4 class="subheading">Do the dirty work</h4>
 240
 241    <p>This is identical to the process used when creating the daily snapshot.
 242
 243 <pre class="example">     $  for m in gdb insight dejagnu
 244      do
 245      ( cd $m/src &amp;&amp; gmake -f Makefile.in $m.tar.bz2 )
 246      done
 247      </pre>
 248
 249 <h4 class="subheading">Check the source files</h4>
 250
 251    <p>You're looking for files that have mysteriously disappeared as the
 252 <kbd>distclean</kbd> has the habit of deleting files it shouldn't.  Watch out
 253 for the <code>version.in</code> update <kbd>cronjob</kbd>.
 254
 255 <pre class="example">     $  ( cd gdb/src &amp;&amp; cvs -f -q -n update )
 256      M djunpack.bat
 257      ? proto-toplev
 258      ? gdb-5.1.1.tar.bz2
 259      M gdb/ChangeLog
 260      M gdb/NEWS
 261      M gdb/README
 262      M gdb/version.in
 263      ? gdb/p-exp.tab.c
 264      ? gdb/doc/gdb.info-11
 265      ? gdb/doc/gdb.info-12
 266      ? gdb/doc/gdb.info-13
 267      ? gdb/doc/gdb.info-14
 268      ? gdb/doc/gdb.info-15
 269      ? gdb/doc/gdbint.info-4
 270      ? gdb/doc/gdbint.info-5
 271      $
 272      </pre>
 273
 274    <p><em>Don't worry about the </em><code>gdb.info-??</code><em> or
 275 </em><code>gdb/p-exp.tab.c</code><em>.  They were generated (and yes </em><code>gdb.info-1</code><em>
 276 was also generated only something strange with CVS means that they
 277 didn't get supressed).  Fixing it would be nice though.</em>
 278
 279 <h4 class="subheading">Re-pack the release with <code>gzip</code></h4>
 280
 281 <pre class="example">     $  cp */*/*.bz2 .
 282      $  bunzip2 -k -v *.bz2
 283      $  gzip -9 -v *.tar
 284      </pre>
 285
 286    <p>NB: A pipe such as <kbd>bunzip2 &lt; xxx.bz2 | gzip -9 &gt; xxx.gz</kbd> shouldn't
 287 be used since, in that mode, gzip doesn't know the file name information
 288 and consequently can't include it.  This is also why the release process
 289 runs <code>tar</code> and <code>bzip2</code> as separate passes.
 290
 291    <p><em>Maintainer note: The release process could be changed to create
 292 </em><code>.tar</code><em> rather than </em><code>.tar.bz2</code><em> files.</em>
 293
 294 <h3 class="section">Check the release</h3>
 295
 296    <p>Grab the <code>gdb.tar.bz2</code>, copy it to your local machine and then try
 297 a simple build using it.
 298
 299    <p>If this is a pre-release just copy the <code>.bz2</code> files to the snapshot
 300 directory and skip the remaining steps.
 301
 302    <p>If it is a final release, also make it available under a bogus name so
 303 that others can download and check it.
 304
 305    <p><em>Maintainer note: This adds an extra day to the release process but
 306 is very much worth it.  Other developers are given the oportunity to
 307 check that things like your </em><code>NEWS</code><em> entries are correct or that
 308 other changes actually work.</em>
 309
 310 <h3 class="section">Release the tar ball</h3>
 311
 312    <p>This is where, unfortunatly, the notes just get vague.
 313
 314 <h4 class="subheading">Install on sware</h4>
 315
 316 <pre class="example">     $  cp *.bz2 *.gz ~ftp/pub/gdb/releases
 317      </pre>
 318
 319 <h4 class="subheading">Create and update the web pages.</h4>
 320
 321    <p>Try the following:
 322
 323      <ul>
 324 <li>create the directory <code>htdocs/</code><var>version</var><code></code> (e.g., <code>htdocs/5.1.1</code>
 325 <li>copy <code>index.html</code> and <code>ANNOUNCE</code> from the previous release
 326 into the <code>htdocs/</code><var>version</var><code></code> directory and edit for content.
 327 Things like the MD5 sums, <kbd>ls -l</kbd> output, the version number and so
 328 on will need updating.  Add NEWS entries to the <code>ANNOUNCE</code>.  This
 329 ensures that the previous announcement is kept somewhere handy.
 330 <li>copy the <code>NEWS</code> from the distro into the
 331 <code>htdocs/</code><var>version</var><code></code> directory, trim down to just the most recent
 332 news items
 333 <li>Add a short (identical) announcement to both <code>htdocs/index.html</code>
 334 and <code>htdocs/news/index.html</code>
 335 <li>edit the script <code>htdocs/index.sh</code> to link in the new release
 336 number.  Run it across all <code>index.html</code> files vis <kbd>./index.sh
 337 index.html */index.html</kbd>.
 338 <li>grep the <code>htdocs</code> tree for references to the previous release
 339 version (<code>htdocs/download/index.html</code>)
 340 </ul>
 341
 342    <p><em>Maintainer note: This step is too fragile -- it is too easy to
 343 mis one of the entries and forget to update it.</em>
 344
 345 <h4 class="subheading">Generate online docs</h4>
 346
 347    <p>You need to find the magic command that is used to generate the online
 348 docs from the <code>.tar.bz2</code>.  The best way is to look in the output
 349 from one of the nightly cronjobs and then just edit accordingly.
 350 Something like:
 351
 352 <pre class="example">     $  ~/ss/update-web-docs \
 353       ~ftp/pub/gdb/releases/gdb-5.1.1.tar.bz2 \
 354       $PWD/www \
 355       /www/sourceware/htdocs/gdb/5.1.1/onlinedocs \
 356       gdb
 357      </pre>
 358
 359 <h4 class="subheading">Something about <code>ANNOUNCEMENT</code></h4>
 360
 361    <p>Send the <code>ANNOUNCEMENT</code> file you created above to:
 362
 363      <ul>
 364 <li><a href="mailto:gdb-announce@sources.redhat.com">GDB Announcement mailing list</a>
 365 <li>The gnu announce list (but delay it a day or so to let things get out).
 366 </ul>
 367
 368 <h4 class="subheading">Install it on GNU</h4>
 369
 370    <p>At the time of writing, the GNU machine was <kbd>gnudist.gnu.org</kbd> in
 371 <code>~ftp/gnu/gdb</code> (I think, I'm still waiting for it to copy into my
 372 home directory).
 373
 374 <h3 class="section">Cleanup</h3>
 375
 376 <h4 class="subheading">Commit outstanding changes</h4>
 377
 378    <p>In particular you'll need to commit the changes to:
 379
 380      <ul>
 381 <li><code>gdb/ChangeLog</code>
 382 <li><code>gdb/version.in</code>
 383 <li><code>gdb/NEWS</code>
 384 <li><code>gdb/README</code>
 385 </ul>
 386
 387 <h4 class="subheading">Tag the release</h4>
 388
 389    <p>Something like:
 390
 391 <pre class="example">     $  d=`date -u +%Y-%m-%d`
 392      $  echo $d
 393      2002-01-24
 394      $  ( cd insight/src/gdb &amp;&amp; cvs -f -q update )
 395      $  ( cd insight/src &amp;&amp; cvs -f -q tag gdb_5_1_1-$d-release )
 396      </pre>
 397
 398    <p>Insight is used since that contains more of the release than GDB (yes
 399 dejagnu doesn't get tagged but I think we can live with that.).
 400
 401 <h4 class="subheading">Restart <code>gdb/version.in</code></h4>
 402
 403    <p>If <code>gdb/version.in</code> does not contain an ISO date such as
 404 <kbd>2002-01-24</kbd> then the daily <code>cronjob</code> won't update it.  Having
 405 committed all the release changes it can be set to
 406 <code>5.1.0_0000-00-00-cvs</code> which will restart things (yes the <kbd>_</kbd>
 407 is important - it affects the snapshot process).
 408
 409    <p>Don't forget the <code>ChangeLog</code>.
 410
 411 <h4 class="subheading">Merge into trunk</h4>
 412
 413    <p>The files committed to the branch may also need changes merged into the
 414 trunk.
 415
 416 <h3 class="section">Post release</h3>
 417
 418    <p>Remove any <code>OBSOLETE</code> code.
 419
 420    </body></html>
 421