gnulib: update

[bison.git] / README-hacking

diff --git a/README-hacking b/README-hacking
index 988bd3044cb778ddf1e23f56b13eb984d2d07c53..25e4ef3400beaf754da93f802a82e1aaf03c07cf 100644 (file)
--- a/README-hacking
+++ b/README-hacking
@@ -50,34 +50,44 @@ These requirements do not apply when building from a distribution tarball.
 
 ** Requirements
 
 
 ** 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:
 
 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/>
 - 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/>
 - 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/>
 - 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/>
 - 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.
 
 
 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:
+
+  sudo apt-get install \
+    autoconf automake autopoint flex graphviz help2man texinfo valgrind

 
 

-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.
+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
 
 
 ** First checkout
 


@@ -93,15 +103,17 @@ to perform the first checkout of the submodules, run
 
        $ git submodule update --init
 
 
        $ 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
 
 
 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
 
         $ ./configure
         $ make


@@ -175,6 +187,28 @@ decide whether to update.
 ** make check
 Use liberally.
 
 ** 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
 
 ** Typical errors
 If the test suite shows failures such as the following one
 


@@ -417,7 +451,7 @@ Push these changes.
 
 -----
 
 
 -----
 

-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.
 
 
 This file is part of GNU Bison.