(comparable to assert/abort), and all the --trace output which is
meant for the maintainers only.
+** Horizontal tabs
+Do not add horizontal tab characters to any file in Bison's repository
+except where required. For example, do not use tabs to format C code.
+However, make files, ChangeLog, and some regular expressions require
+tabs. Also, test cases might need to contain tabs to check that Bison
+properly processes tabs in its input.
+
* Working from the repository
** 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
+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/>
+- Automake <http://www.gnu.org/software/automake/>
- Flex <http://www.gnu.org/software/flex/>
- Gettext <http://www.gnu.org/software/gettext/>
+- Graphviz <http://www.graphviz.org>
- Gzip <http://www.gnu.org/software/gzip/>
+- Help2man <http://www.gnu.org/software/help2man/>
- Perl <http://www.cpan.org/>
- Rsync <http://samba.anu.edu.au/rsync/>
- Tar <http://www.gnu.org/software/tar/>
+- Texinfo <http://www.gnu.org/software/texinfo/>
Valgrind <http://valgrind.org/> is also highly recommended, if it 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.
+If you're using a GNU/Linux distribution, the easiest way to install the
+above packages depends on your system. The following shell command should
+work for Debian-based systems such as Ubuntu:
-Only building the initial full source tree will be a bit painful.
-Later, after synchronizing from the repository a plain 'make' should
-be sufficient. Note, however, that when gnulib is updated, running
-'./bootstrap' again might be needed.
+ sudo apt-get install \
+ autoconf automake autopoint flex graphviz help2man texinfo valgrind
+
+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.
+Note, however, that when gnulib is updated, running './bootstrap' again
+might be needed.
** First checkout
$ 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.
+Git submodule support is weak before versions 1.6 and later, 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
+If it fails with missing symbols (e.g., "error: possibly undefined macro:
+AC_PROG_GNU_M4"), you are likely to have forgotten the submodule
+initialization part. Otherwise, there you are! Just
$ ./configure
$ make
** make check
Use liberally.
+** TESTSUITEFLAGS
+
+The default is for make check to run all tests sequentially. This can be
+very time consumming when checking repeatedly or on slower setups. This can
+be sped up in two ways:
+
+Using -j, in a make-like fashion, for example:
+ $ make check TESTSUITEFLAGS='-j8'
+
+Running only the tests of a certain category, as specified in the AT files
+with AT_KEYWORDS([[category]]). Categories include:
+ - c++, for c++ parsers
+ - deprec, for tests concerning deprecated constructs.
+ - glr, for glr parsers
+ - java, for java parsers
+ - report, for automaton dumps
+
+To run a specific set of tests, use -k (for "keyword"). For example:
+ $ make check TESTSUITEFLAGS='-k c++'
+
+Both can be combined.
+
** Typical errors
If the test suite shows failures such as the following one
/usr/include/getopt.h:54:8: error: previous definition of 'struct option'
it probably means that some file was compiled without
-AT_DATA_SOURCE_PROLOGUE. This error is due to the fact that our -I pick up
-gnulib's replacement headers, such as getopt.h, which will go if config.h
-was not included first.
+AT_DATA_SOURCE_PROLOGUE. This error is due to the fact that our -I options
+pick up gnulib's replacement headers, such as getopt.h, and this will go
+wrong if config.h was not included first.
See tests/local.at for details.
that it does not make sense for glr.c, which should be ANSI, but
currently is actually GNU C, nor for lalr1.cc.
+- Test with a very recent version of GCC for both C and C++. Testing
+ with older versions that are still in use is nice too.
+
* Release Procedure
This section needs to be updated to take into account features from
-----
-Copyright (C) 2002-2005, 2007-2012 Free Software Foundation, Inc.
+Copyright (C) 2002-2005, 2007-2015 Free Software Foundation, Inc.
This file is part of GNU Bison.
projects / bison.git / blobdiff