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 - Build with -DGNULIB_POSIXCHECK.  It suggests gnulib modules that can
 176   fix portability issues.
 177
 178 - run `make maintainer-check' which:
 179   - runs `valgrind -q bison' to run Bison under Valgrind.
 180   - runs the parsers under Valgrind.
 181   - runs the test suite with G++ as C compiler...
 182
 183 - run `make maintainer-push-check', which runs `make maintainer-check'
 184   while activating the push implementation and its pull interface wrappers
 185   in many test cases that were originally written to exercise only the
 186   pull implementation.  This makes certain the push implementation can
 187   perform every task the pull implementation can.
 188
 189 - run `make maintainer-xml-check', which runs `make maintainer-check'
 190   while checking Bison's XML automaton report for every working grammar
 191   passed to Bison in the test suite.  The check just diffs the output of
 192   Bison's included XSLT style sheets with the output of --report=all and
 193   --graph.
 194
 195 - Change tests/atlocal/CFLAGS to add your preferred options.  For
 196   instance, `-traditional' to check that the parsers are K&R.  Note
 197   that it does not make sense for glr.c, which should be ANSI,
 198   but currently is actually GNU C, nor for lalr1.cc.
 199
 200
 201 * Release Procedure
 202
 203 ** Try to get the *.pot files to the Translation Project at least one week
 204 before a stable release, to give them time to translate them.
 205
 206 ** Tests
 207 See above.
 208
 209 ** Update the foreign files
 210 Running `./bootstrap' in the top level should update them all for you.
 211 This covers PO files too.  Sometimes a PO file contains problems that
 212 causes it to be rejected by recent Gettext releases; please report
 213 these to the Translation Project.
 214
 215 ** Update README
 216 Make sure the information in this file is current.  Most notably, make sure it
 217 recommends a version of GNU M4 that is compatible with the latest Bison
 218 sources.
 219
 220 ** Update NEWS
 221 The version number, *and* the date of the release (including for
 222 betas).
 223
 224 ** Update ChangeLog
 225 Should have an entry similar to `Version 1.49b.'.
 226
 227 ** Update configure.ac
 228 Be sure PACKAGE_COPYRIGHT_YEAR is up-to-date.
 229
 230 ** Tag the release
 231 Before Bison will build with the right version number, you must tag the release
 232 in git.  Do this after all other changes.  The command is similar to:
 233
 234   git tag -a v2.3b
 235
 236 The log message can be simply:
 237
 238   Bison 2.3b
 239
 240 ** Push
 241 Once `make distcheck' passes, push your changes and the tag.
 242 `git push' without arguments will not push the tag.
 243
 244 ** make alpha
 245 FIXME: `make alpha' is not maintained and is broken.  These
 246 instructions need to be replaced or removed.
 247
 248 Running `make alpha' is absolutely perfect for beta releases: it makes
 249 the tarballs, the xdeltas, and prepares (in /tmp/) a proto
 250 announcement.  It is so neat, that that's what I use anyway for
 251 genuine releases, but adjusting things by hand (e.g., the urls in the
 252 announcement file, the ChangeLog which is not needed etc.).
 253
 254 If it fails, you're on your own...
 255
 256 It requires GNU Make.
 257
 258 ** Upload
 259 The generic GNU upload procedure is at:
 260
 261   http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
 262
 263 Follow the instructions there to register your information so you're permitted
 264 to upload.  Make sure your public key has been uploaded at least to
 265 keys.gnupg.net.  You can upload it with:
 266
 267   gpg --keyserver keys.gnupg.net --send-keys F125BDF3
 268
 269 where F125BDF3 should be replaced with your key ID.
 270
 271 Here's a brief reminder of how to roll the tarballs and upload them:
 272
 273 *** make distcheck
 274 *** gpg -b bison-2.3b.tar.gz
 275 *** In a file named `bison-2.3b.tar.gz.directive', type:
 276
 277       version: 1.1
 278       directory: bison
 279       filename: bison-2.3b.tar.gz
 280
 281 *** gpg --clearsign bison-2.3b.tar.gz.directive
 282 *** ftp ftp-upload.gnu.org # Log in as anonymous.
 283 *** cd /incoming/alpha # cd /incoming/ftp for full release.
 284 *** put bison-2.3b.tar.gz # This can take a while.
 285 *** put bison-2.3b.tar.gz.sig
 286 *** put bison-2.3b.tar.gz.directive.asc
 287 *** Repeat all these steps for bison-2.3b.tar.bz2.
 288
 289 ** Update Bison manual on www.gnu.org.
 290
 291 *** You need a non-anonymous checkout of the web pages directory.
 292
 293   $ cvs -d YOUR_USERID@cvs.savannah.gnu.org:/web/bison checkout bison
 294
 295 *** Get familiar with the instructions for web page maintainers.
 296 http://www.gnu.org/server/standards/readme_index.html
 297 http://www.gnu.org/server/standards/README.software.html
 298 especially the note about symlinks.
 299
 300 *** Build the web pages.
 301 Assuming BISON_CHECKOUT refers to a checkout of the Bison dir, and
 302 BISON_WWW_CHECKOUT refers to the web directory created above, do:
 303
 304   $ cd $BISON_CHECKOUT/doc
 305   $ make stamp-vti
 306   $ ../build-aux/gendocs.sh -o "$BISON_WWW_CHECKOUT/manual" \
 307     bison "Bison - GNU parser generator"
 308   $ cd $BISON_WWW_CHECKOUT
 309
 310 Verify that the result looks sane.
 311
 312 *** Commit the modified and the new files.
 313
 314 *** Remove old files.
 315 Find the files which have not been overwritten (because they belonged to
 316 sections that have been removed or renamed):
 317
 318    $ cd manual/html_node
 319    $ ls -lt
 320
 321 Remove these files and commit their removal to CVS.  For each of these
 322 files, add a line to the file .symlinks.  This will ensure that
 323 hyperlinks to the removed files will redirect to the entire manual; this
 324 is better than a 404 error.
 325
 326 There is a problem with 'index.html' being written twice (once for POSIX
 327 function 'index', once for the table of contents); you can ignore this
 328 issue.
 329
 330 ** Announce
 331 To generate a template announcement file:
 332
 333   make RELEASE_TYPE=alpha gpg_key_ID=F125BDF3 announcement
 334
 335 where alpha can be replaced by beta or major and F125BDF3 should be replaced
 336 with your key ID.  For an example of how to fill out the template, search the
 337 mailing list archives for the most recent release announcement.
 338
 339 Complete/fix the announcement file, and send it at least to
 340 info-gnu@gnu.org (if a real release, or a ``serious beta''),
 341 bug-bison@gnu.org, help-bison@gnu.org, bison-patches@gnu.org,
 342 and coordinator@translationproject.org.
 343
 344 Send the same announcement on the comp.compilers newsgroup by sending
 345 email to compilers@iecc.com.  Do not make any Cc as the moderator will
 346 throw away anything cross-posted or Cc'ed.  It really needs to be a
 347 separate message.
 348
 349 ** Bump the version number
 350 In configure.ac.  Run `make'.  So that developers don't accidentally add new
 351 items to the old NEWS entry, create a new empty NEWS entry something like:
 352
 353   Changes in version ?.? (????-??-??):
 354
 355 Push these changes.
 356
 357
 358 -----
 359
 360 Copyright (C) 2002-2005, 2007-2010 Free Software Foundation, Inc.
 361
 362 This file is part of GNU Bison.
 363
 364 This program is free software: you can redistribute it and/or modify
 365 it under the terms of the GNU General Public License as published by
 366 the Free Software Foundation, either version 3 of the License, or
 367 (at your option) any later version.
 368
 369 This program is distributed in the hope that it will be useful,
 370 but WITHOUT ANY WARRANTY; without even the implied warranty of
 371 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 372 GNU General Public License for more details.
 373
 374 You should have received a copy of the GNU General Public License
 375 along with this program.  If not, see <http://www.gnu.org/licenses/>.