HACKING

   1 -*- outline -*-
   2
   3 This file attempts to describe the rules to use when hacking Bison.
   4 Don't put this file into the distribution.
   5
   6 Everything related to the development of Bison is on Savannah:
   7
   8         http://savannah.gnu.org/projects/bison/
   9
  10
  11 * Administrivia
  12
  13 ** If you incorporate a change from somebody on the net:
  14 First, if it is a large change, you must make sure they have signed
  15 the appropriate paperwork.  Second, be sure to add their name and
  16 email address to THANKS.
  17
  18 ** If a change fixes a test, mention the test in the ChangeLog entry.
  19
  20 ** Bug reports
  21 If somebody reports a new bug, mention his name in the ChangeLog entry
  22 and in the test case you write.  Put him into THANKS.
  23
  24 The correct response to most actual bugs is to write a new test case
  25 which demonstrates the bug.  Then fix the bug, re-run the test suite,
  26 and check everything in.
  27
  28 ** You may find it useful to install the git-merge-changelog merge driver:
  29
  30   http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
  31
  32 When following the generic installation instructions there, keep in mind that
  33 your clone of Bison's git repository already contains appropriate
  34 .gitattributes files, and running Bison's bootstrap script will make the
  35 necessary changes to .git/config.
  36
  37
  38 * Hacking
  39
  40 ** Visible changes
  41 Which include serious bug fixes, must be mentioned in NEWS.
  42
  43 ** Translations
  44 Only user visible strings are to be translated: error messages, bits
  45 of the .output file etc.  This excludes impossible error messages
  46 (comparable to assert/abort), and all the --trace output which is
  47 meant for the maintainers only.
  48
  49
  50 * Working from the repository
  51
  52 These notes intend to help people working on the checked-out sources.
  53 These requirements do not apply when building from a distribution tarball.
  54
  55 ** Requirements
  56
  57 We've opted to keep only the highest-level sources in the repository.
  58 This eases our maintenance burden, (fewer merges etc.), but imposes more
  59 requirements on anyone wishing to build from the just-checked-out sources.
  60 For example, you have to use the latest stable versions of the maintainer
  61 tools we depend upon, including:
  62
  63 - Automake <http://www.gnu.org/software/automake/>
  64 - Autoconf <http://www.gnu.org/software/autoconf/>
  65 - Flex <http://www.gnu.org/software/flex/>
  66 - Gettext <http://www.gnu.org/software/gettext/>
  67 - Gzip <http://www.gnu.org/software/gzip/>
  68 - Perl <http://www.cpan.org/>
  69 - Rsync <http://samba.anu.edu.au/rsync/>
  70 - Tar <http://www.gnu.org/software/tar/>
  71
  72 Valgrind <http://valgrind.org/> is also highly recommended, if
  73 Valgrind supports your architecture.
  74
  75 Bison is written using Bison grammars, so there are bootstrapping
  76 issues.  The bootstrap script attempts to discover when the C code
  77 generated from the grammars is out of date, and to bootstrap with an
  78 out-of-date version of the C code, but the process is not foolproof.
  79 Also, you may run into similar problems yourself if you modify Bison.
  80
  81 Only building the initial full source tree will be a bit painful.
  82 Later, after synchronizing from the repository a plain `make' should
  83 be sufficient.
  84
  85 ** First checkout
  86
  87 Obviously, if you are reading these notes, you did manage to check out
  88 this package from the repository.  For the record, you will find all the
  89 relevant information on:
  90
  91         http://savannah.gnu.org/git/?group=bison
  92
  93 Bison uses Git submodules: subscriptions to other Git repositories.
  94 In particular it uses gnulib, the GNU portability library.  To ask Git
  95 to perform the first checkout of the submodules, run
  96
  97        $ git submodule update --init
  98
  99 Git submodule support is weak before versions 1.6 and later, you
 100 should probably upgrade Git if your version is older.
 101
 102 The next step is to get other files needed to build, which are
 103 extracted from other source packages:
 104
 105         $ ./bootstrap
 106
 107 And there you are!  Just
 108
 109         $ ./configure
 110         $ make
 111         $ make check
 112
 113 At this point, there should be no difference between your local copy,
 114 and the master copy:
 115
 116         $ git diff
 117
 118 should output no difference.
 119
 120 Enjoy!
 121
 122 ** Updating
 123
 124 The use of submodules make things somewhat different because git does
 125 not support recursive operations: submodules must be taken care of
 126 explicitly by the user.
 127
 128 *** Updating Bison
 129
 130 If you pull a newer version of a branch, say via `git pull', you might
 131 import requests for updated submodules.  A simple `git diff' will
 132 reveal if the current version of the submodule (i.e., the actual
 133 contents of the gnulib directory) and the current request from the
 134 subscriber (i.e., the reference of the version of gnulib that the
 135 Bison reporitory requests) differ.  To upgrade the submodules (i.e.,
 136 to check out the version that is actually requested by the subscriber,
 137 run `git submodule update'.
 138
 139         $ git pull
 140         $ git submodule update
 141
 142 *** Updating a submodule
 143 To update a submodule, say gnulib, do as follows:
 144
 145 Get the most recent version of the master branch from git.
 146
 147         $ cd gnulib
 148         $ git fetch
 149         $ git checkout -b master --track origin/master
 150
 151 Make sure Bison can live with that version of gnulib.
 152
 153         $ cd ..
 154         $ ./bootstrap
 155         $ make distcheck
 156
 157 Register your changes.
 158
 159         $ git checkin ...
 160
 161
 162 * Test suite
 163
 164 ** make check
 165 Use liberally.
 166
 167 ** Release checks
 168 Try to run the test suite with more severe conditions before a
 169 release:
 170
 171 - Configure the package with --enable-gcc-warnings, so that one checks
 172   that 1. Bison compiles cleanly, 2. the parsers it produces compile
 173   cleanly too.
 174
 175 - run `make maintainer-check' which:
 176   - runs `valgrind -q bison' to run Bison under Valgrind.
 177   - runs the parsers under Valgrind.
 178   - runs the test suite with G++ as C compiler...
 179
 180 - run `make maintainer-push-check', which runs `make maintainer-check'
 181   while activating the push implementation and its pull interface wrappers
 182   in many test cases that were originally written to exercise only the
 183   pull implementation.  This makes certain the push implementation can
 184   perform every task the pull implementation can.
 185
 186 - run `make maintainer-xml-check', which runs `make maintainer-check'
 187   while checking Bison's XML automaton report for every working grammar
 188   passed to Bison in the test suite.  The check just diffs the output of
 189   Bison's included XSLT style sheets with the output of --report=all and
 190   --graph.
 191
 192 - Change tests/atlocal/CFLAGS to add your preferred options.  For
 193   instance, `-traditional' to check that the parsers are K&R.  Note
 194   that it does not make sense for glr.c, which should be ANSI,
 195   but currently is actually GNU C, nor for lalr1.cc.
 196
 197
 198 * Release Procedure
 199
 200 ** Try to get the *.pot files to the Translation Project at least one week
 201 before a stable release, to give them time to translate them.
 202
 203 ** Tests
 204 See above.
 205
 206 ** Update the foreign files
 207 Running `./bootstrap' in the top level should update them all for you.
 208 This covers PO files too.  Sometimes a PO file contains problems that
 209 causes it to be rejected by recent Gettext releases; please report
 210 these to the Translation Project.
 211
 212 ** Update README
 213 Make sure the information in this file is current.  Most notably, make sure it
 214 recommends a version of GNU M4 that is compatible with the latest Bison
 215 sources.
 216
 217 ** Update NEWS
 218 The version number, *and* the date of the release (including for
 219 betas).
 220
 221 ** Update ChangeLog
 222 Should have an entry similar to `Version 1.49b.'.
 223
 224 ** Update configure.ac
 225 Be sure PACKAGE_COPYRIGHT_YEAR is up-to-date.
 226
 227 ** Tag the release
 228 Before Bison will build with the right version number, you must tag the release
 229 in git.  Do this after all other changes.  The command is similar to:
 230
 231   git tag -a v2.3b
 232
 233 The log message can be simply:
 234
 235   Bison 2.3b
 236
 237 ** Push
 238 Once `make distcheck' passes, push your changes and the tag.
 239 `git push' without arguments will not push the tag.
 240
 241 ** make alpha
 242 FIXME: `make alpha' is not maintained and is broken.  These
 243 instructions need to be replaced or removed.
 244
 245 Running `make alpha' is absolutely perfect for beta releases: it makes
 246 the tarballs, the xdeltas, and prepares (in /tmp/) a proto
 247 announcement.  It is so neat, that that's what I use anyway for
 248 genuine releases, but adjusting things by hand (e.g., the urls in the
 249 announcement file, the ChangeLog which is not needed etc.).
 250
 251 If it fails, you're on your own...
 252
 253 It requires GNU Make.
 254
 255 ** Upload
 256 The generic GNU upload procedure is at:
 257
 258   http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
 259
 260 Follow the instructions there to register your information so you're permitted
 261 to upload.  Make sure your public key has been uploaded at least to
 262 keys.gnupg.net.  You can upload it with:
 263
 264   gpg --keyserver keys.gnupg.net --send-keys F125BDF3
 265
 266 where F125BDF3 should be replaced with your key ID.
 267
 268 Here's a brief reminder of how to roll the tarballs and upload them:
 269
 270 *** make distcheck
 271 *** gpg -b bison-2.3b.tar.gz
 272 *** In a file named `bison-2.3b.tar.gz.directive', type:
 273
 274       version: 1.1
 275       directory: bison
 276       filename: bison-2.3b.tar.gz
 277
 278 *** gpg --clearsign bison-2.3b.tar.gz.directive
 279 *** ftp ftp-upload.gnu.org # Log in as anonymous.
 280 *** cd /incoming/alpha # cd /incoming/ftp for full release.
 281 *** put bison-2.3b.tar.gz # This can take a while.
 282 *** put bison-2.3b.tar.gz.sig
 283 *** put bison-2.3b.tar.gz.directive.asc
 284 *** Repeat all these steps for bison-2.3b.tar.bz2.
 285
 286 ** Update Bison manual on www.gnu.org.
 287
 288 *** You need a non-anonymous checkout of the web pages directory.
 289
 290   $ cvs -d YOUR_USERID@cvs.savannah.gnu.org:/web/bison checkout bison
 291
 292 *** Get familiar with the instructions for web page maintainers.
 293 http://www.gnu.org/server/standards/readme_index.html
 294 http://www.gnu.org/server/standards/README.software.html
 295 especially the note about symlinks.
 296
 297 *** Build the web pages.
 298 Assuming BISON_CHECKOUT refers to a checkout of the Bison dir, and
 299 BISON_WWW_CHECKOUT refers to the web directory created above, do:
 300
 301   $ cd $BISON_CHECKOUT/doc
 302   $ make stamp-vti
 303   $ ../build-aux/gendocs.sh -o "$BISON_WWW_CHECKOUT/manual" \
 304     bison "Bison - GNU parser generator"
 305   $ cd $BISON_WWW_CHECKOUT
 306
 307 Verify that the result looks sane.
 308
 309 *** Commit the modified and the new files.
 310
 311 *** Remove old files.
 312 Find the files which have not been overwritten (because they belonged to
 313 sections that have been removed or renamed):
 314
 315    $ cd manual/html_node
 316    $ ls -lt
 317
 318 Remove these files and commit their removal to CVS.  For each of these
 319 files, add a line to the file .symlinks.  This will ensure that
 320 hyperlinks to the removed files will redirect to the entire manual; this
 321 is better than a 404 error.
 322
 323 There is a problem with 'index.html' being written twice (once for POSIX
 324 function 'index', once for the table of contents); you can ignore this
 325 issue.
 326
 327 ** Announce
 328 To generate a template announcement file:
 329
 330   make RELEASE_TYPE=alpha gpg_key_ID=F125BDF3 announcement
 331
 332 where alpha can be replaced by beta or major and F125BDF3 should be replaced
 333 with your key ID.  For an example of how to fill out the template, search the
 334 mailing list archives for the most recent release announcement.
 335
 336 Complete/fix the announcement file, and send it at least to
 337 info-gnu@gnu.org (if a real release, or a ``serious beta''),
 338 bug-bison@gnu.org, help-bison@gnu.org, bison-patches@gnu.org,
 339 and coordinator@translationproject.org.
 340
 341 Send the same announcement on the comp.compilers newsgroup by sending
 342 email to compilers@iecc.com.  Do not make any Cc as the moderator will
 343 throw away anything cross-posted or Cc'ed.  It really needs to be a
 344 separate message.
 345
 346 ** Bump the version number
 347 In configure.ac.  Run `make'.  So that developers don't accidentally add new
 348 items to the old NEWS entry, create a new empty NEWS entry something like:
 349
 350   Changes in version ?.? (????-??-??):
 351
 352 Push these changes.
 353
 354
 355 -----
 356
 357 Copyright (C) 2002-2005, 2007-2010 Free Software Foundation, Inc.
 358
 359 This file is part of GNU Bison.
 360
 361 This program is free software: you can redistribute it and/or modify
 362 it under the terms of the GNU General Public License as published by
 363 the Free Software Foundation, either version 3 of the License, or
 364 (at your option) any later version.
 365
 366 This program is distributed in the hope that it will be useful,
 367 but WITHOUT ANY WARRANTY; without even the implied warranty of
 368 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 369 GNU General Public License for more details.
 370
 371 You should have received a copy of the GNU General Public License
 372 along with this program.  If not, see <http://www.gnu.org/licenses/>.