misc: document TESTSUITEFLAGS in README-hacking

[bison.git] / README-hacking

diff --git a/README-hacking b/README-hacking
index 2b92edcf0c7c1ae97f4b3799a594da35a9c9bd9e..ff5b4345fc0c17cd033bdcf03ab1e1a6a87b1c72 100644 (file)
--- a/README-hacking
+++ b/README-hacking
@@ -175,6 +175,41 @@ decide whether to update.
 ** 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
+
+  .../bison/lib/getopt.h:196:8: error: redefinition of 'struct option'
+  /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 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.
+
 ** make maintainer-check-valgrind
 This target uses valgrind both to check bison, and the generated parsers.