X-Git-Url: https://git.saurik.com/bison.git/blobdiff_plain/bcbbf654863dd285b176a0f54a75a28c4bdac1d3..HEAD:/README-hacking diff --git a/README-hacking b/README-hacking index bb91ac06..25e4ef34 100644 --- a/README-hacking +++ b/README-hacking @@ -35,6 +35,13 @@ of the .output file etc. This excludes impossible error messages (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 @@ -43,34 +50,44 @@ 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 +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 - Autoconf +- Automake - Flex - Gettext +- Graphviz - Gzip +- Help2man - Perl - Rsync - Tar +- Texinfo Valgrind 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 @@ -86,15 +103,17 @@ 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. +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 @@ -168,6 +187,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. @@ -226,6 +280,9 @@ release: 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 @@ -394,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.