-*- outline -*-
This file attempts to describe the rules to use when hacking Bison.
-Don't put this file into the distribution. Don't mention it in the
-ChangeLog.
+Don't put this file into the distribution.
Everything related to the development of Bison is on Savannah:
- http://savannah.gnu.org/projects/bison/
+ http://savannah.gnu.org/projects/bison/
* Administrivia
which demonstrates the bug. Then fix the bug, re-run the test suite,
and check everything in.
+** You may find it useful to install the git-merge-changelog merge driver:
+
+ http://git.sv.gnu.org/gitweb/?p=gnulib.git;a=blob;f=lib/git-merge-changelog.c
+
+When following the generic installation instructions there, keep in mind that
+your clone of Bison's git repository already contains appropriate
+.gitattributes files, and running Bison's bootstrap script will make the
+necessary changes to .git/config.
+
* Hacking
meant for the maintainers only.
+* Working from the repository
+
+These notes intend to help people working on the checked-out sources.
+These requirements do not apply when building from a distribution tarball.
+
+** Requirements
+
+We've opted to keep only the highest-level sources in the repository.
+This eases our maintenance burden, (fewer merges etc.), but imposes more
+requirements on anyone wishing to build from the just-checked-out sources.
+For example, you have to use the latest stable versions of the maintainer
+tools we depend upon, including:
+
+- Automake <http://www.gnu.org/software/automake/>
+- Autoconf <http://www.gnu.org/software/autoconf/>
+- Flex <http://www.gnu.org/software/flex/>
+- Gettext <http://www.gnu.org/software/gettext/>
+- Gzip <http://www.gnu.org/software/gzip/>
+- Perl <http://www.cpan.org/>
+- Rsync <http://samba.anu.edu.au/rsync/>
+- Tar <http://www.gnu.org/software/tar/>
+
+Valgrind <http://valgrind.org/> is also highly recommended, if
+Valgrind supports your architecture.
+
+Bison is written using Bison grammars, so there are bootstrapping
+issues. The bootstrap script attempts to discover when the C code
+generated from the grammars is out of date, and to bootstrap with an
+out-of-date version of the C code, but the process is not foolproof.
+Also, you may run into similar problems yourself if you modify Bison.
+
+Only building the initial full source tree will be a bit painful.
+Later, after synchronizing from the repository a plain `make' should
+be sufficient.
+
+** First checkout
+
+Obviously, if you are reading these notes, you did manage to check out
+this package from the repository. For the record, you will find all the
+relevant information on:
+
+ http://savannah.gnu.org/git/?group=bison
+
+Bison uses Git submodules: subscriptions to other Git repositories.
+In particular it uses gnulib, the GNU portability library. To ask Git
+to perform the first checkout of the submodules, run
+
+ $ git submodule update --init
+
+Git submodule support is weak before versions 1.6 and later, you
+should probably upgrade Git if your version is older.
+
+The next step is to get other files needed to build, which are
+extracted from other source packages:
+
+ $ ./bootstrap
+
+And there you are! Just
+
+ $ ./configure
+ $ make
+ $ make check
+
+At this point, there should be no difference between your local copy,
+and the master copy:
+
+ $ git diff
+
+should output no difference.
+
+Enjoy!
+
+** Updating
+
+The use of submodules make things somewhat different because git does
+not support recursive operations: submodules must be taken care of
+explicitly by the user.
+
+*** Updating Bison
+
+If you pull a newer version of a branch, say via `git pull', you might
+import requests for updated submodules. A simple `git diff' will
+reveal if the current version of the submodule (i.e., the actual
+contents of the gnulib directory) and the current request from the
+subscriber (i.e., the reference of the version of gnulib that the
+Bison reporitory requests) differ. To upgrade the submodules (i.e.,
+to check out the version that is actually requested by the subscriber,
+run `git submodule update'.
+
+ $ git pull
+ $ git submodule update
+
+*** Updating a submodule
+To update a submodule, say gnulib, do as follows:
+
+Get the most recent version of the master branch from git.
+
+ $ cd gnulib
+ $ git fetch
+ $ git checkout -b master --track origin/master
+
+Make sure Bison can live with that version of gnulib.
+
+ $ cd ..
+ $ ./bootstrap
+ $ make distcheck
+
+Register your changes.
+
+ $ git checkin ...
+
+
* Test suite
** make check
- runs the parsers under Valgrind.
- runs the test suite with G++ as C compiler...
+- run `make maintainer-push-check', which runs `make maintainer-check'
+ while activating the push implementation and its pull interface wrappers
+ in many test cases that were originally written to exercise only the
+ pull implementation. This makes certain the push implementation can
+ perform every task the pull implementation can.
+
+- run `make maintainer-xml-check', which runs `make maintainer-check'
+ while checking Bison's XML automaton report for every working grammar
+ passed to Bison in the test suite. The check just diffs the output of
+ Bison's included XSLT style sheets with the output of --report=all and
+ --graph.
+
- Change tests/atlocal/CFLAGS to add your preferred options. For
instance, `-traditional' to check that the parsers are K&R. Note
that it does not make sense for glr.c, which should be ANSI,
- but currently is actually GNU C, nor for lalr1.cc, which anyway is
- not exercised yet in the test suite.
+ but currently is actually GNU C, nor for lalr1.cc.
* Release Procedure
+** Try to get the *.pot files to the Translation Project at least one week
+before a stable release, to give them time to translate them.
+
** Tests
See above.
** Update the foreign files
-Running `make update' in the top level should make it all for you.
-This covers PO files too. Beware that it happens that some PO files
-contain serious problems and are rejected by recent Gettext releases:
-fix them all, and complain to the Translation Project!
+Running `./bootstrap' in the top level should update them all for you.
+This covers PO files too. Sometimes a PO file contains problems that
+causes it to be rejected by recent Gettext releases; please report
+these to the Translation Project.
-Note that there might be *new* PO files. Don't forget to update the
-whole machinery, which not only includes LINGUAS, but `cvs add'ing the
-PO files too.
+** Update README
+Make sure the information in this file is current. Most notably, make sure it
+recommends a version of GNU M4 that is compatible with the latest Bison
+sources.
** Update NEWS
The version number, *and* the date of the release (including for
** Update ChangeLog
Should have an entry similar to `Version 1.49b.'.
-Check all this in once `make distcheck' passes.
+
+** Update configure.ac
+Be sure PACKAGE_COPYRIGHT_YEAR is up-to-date.
+
+** Tag the release
+Before Bison will build with the right version number, you must tag the release
+in git. Do this after all other changes. The command is similar to:
+
+ git tag -a v2.3b
+
+The log message can be simply:
+
+ Bison 2.3b
+
+** Push
+Once `make distcheck' passes, push your changes and the tag.
+`git push' without arguments will not push the tag.
** make alpha
+FIXME: `make alpha' is not maintained and is broken. These
+instructions need to be replaced or removed.
+
Running `make alpha' is absolutely perfect for beta releases: it makes
the tarballs, the xdeltas, and prepares (in /tmp/) a proto
announcement. It is so neat, that that's what I use anyway for
It requires GNU Make.
** Upload
-Put the tarballs/xdeltas where they should be. Or put it somewhere,
-and send the URL to ftp-upload@gnu.org.
+The generic GNU upload procedure is at:
-** Bump the version number
-In configure.ac. Run `make', check this in.
+ http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads
+
+After following the instructions there to register your information so you're
+permitted to upload, here's a brief reminder of how to roll the tarballs and
+upload them:
+
+*** make distcheck
+*** gpg -b bison-2.3b.tar.gz
+*** In a file named `bison-2.3b.tar.gz.directive', type:
+
+ version: 1.1
+ directory: bison
+ filename: bison-2.3b.tar.gz
+
+*** gpg --clearsign bison-2.3b.tar.gz.directive
+*** ftp ftp-upload.gnu.org # Log in as anonymous.
+*** cd /incoming/alpha # cd /incoming/ftp for full release.
+*** put bison-2.3b.tar.gz # This can take a while.
+*** put bison-2.3b.tar.gz.sig
+*** put bison-2.3b.tar.gz.directive.asc
+*** Repeat all these steps for bison-2.3b.tar.bz2.
** Announce
+To generate a template announcement file:
+
+ make RELEASE_TYPE=alpha gpg_key_ID=F125BDF3 announcement
+
+where alpha can be replaced by beta or major and F125BDF3 should be replaced
+with your key ID. For an example of how to fill out the template, search the
+mailing list archives for the most recent release announcement.
+
Complete/fix the announcement file, and send it at least to
info-gnu@gnu.org (if a real release, or a ``serious beta''),
-bison@gnu.org, and translation@iro.umontreal.ca.
+bug-bison@gnu.org, help-bison@gnu.org, bison-patches@gnu.org,
+and coordinator@translationproject.org.
+
+Send the same announcement on the comp.compilers newsgroup by sending
+email to compilers@iecc.com. Do not make any Cc as the moderator will
+throw away anything cross-posted or Cc'ed. It really needs to be a
+separate message.
+
+** Bump the version number
+In configure.ac. Run `make'. So that developers don't accidentally add new
+items to the old NEWS entry, create a new empty NEWS entry something like:
+
+ Changes in version ?.? (????-??-??):
-Send the same announcement on the comp.compilers newsgroup. Do not
-make any Cc as the moderator will throw away anything cross-posted or
-Cc'ed. It really needs to be a separate message.
+Push these changes.
-----
-Copyright (C) 2002, 2003 Free Software Foundation, Inc.
+Copyright (C) 2002, 2003, 2004, 2005, 2007, 2008, 2009
+Free Software Foundation, Inc.
This file is part of GNU Bison.
-GNU Bison is free software; you can redistribute it and/or modify
+This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2, or (at your option)
-any later version.
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
-GNU Bison is distributed in the hope that it will be useful,
+This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
-along with GNU Bison; see the file COPYING. If not, write to the Free
-Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
-02111-1307, USA.
+along with this program. If not, see <http://www.gnu.org/licenses/>.
projects / bison.git / blobdiff