xref: /bison/
Name Date Size

..18-Aug.-20214 KiB

.gitattributesH A D06-Aug.-202141

.gitconfigH A D06-Aug.-2021320

.gitignoreH A D22-Sep.-2019401

.gitmodulesH A D13-Aug.-2017184

.prev-versionH A D11-Sep.-20216

.projectH A D13-Aug.-201751

.travis.ymlH A D29-Aug.-202115.8 KiB

.x-sc_require_config_hH A D13-Aug.-201737

.x-sc_unmarked_diagnosticsH A D13-Aug.-201718

.x-update-copyrightH A D13-Aug.-201795

AUTHORSH A D16-Feb.-20211.4 KiB

bootstrapH A D24-Jun.-202133.9 KiB

bootstrap.confH A D11-Sep.-20213.4 KiB

build-aux/H16-Feb.-20214 KiB

cfg.mkH A D13-Aug.-20216.9 KiB

ChangeLog-1998H A D13-Aug.-201745.7 KiB

ChangeLog-2012H A D16-Feb.-2021975.5 KiB

configure.acH A D29-Aug.-202112.2 KiB

COPYINGH A D16-Feb.-202134.3 KiB

data/H11-Aug.-20214 KiB

doc/H11-Sep.-20214 KiB

etc/H16-Feb.-20214 KiB

examples/H09-Aug.-20214 KiB

gnulib/H13-Aug.-20174 KiB

gnulib-po/H20-Nov.-20204 KiB

lib/H14-Sep.-20214 KiB

m4/H14-Sep.-20214 KiB

Makefile.amH A D16-Feb.-20215.1 KiB

NEWSH A D11-Sep.-2021160.4 KiB

PACKAGINGH A D16-Feb.-20211.9 KiB

po/H21-Dec.-20204 KiB

READMEH A D13-Aug.-20215.3 KiB

README-alphaH A D16-Feb.-20211.1 KiB

README-hacking.mdH A D16-Feb.-202123.6 KiB

README.mdH A D13-Aug.-20215.3 KiB

runtime-po/H20-Nov.-20204 KiB

src/H12-Sep.-20214 KiB

submodules/autoconf/H13-Aug.-20174 KiB

tests/H13-Sep.-20214 KiB

THANKSH A D16-Feb.-202111.5 KiB

TODOH A D05-Sep.-202127.3 KiB

README

1GNU Bison is a general-purpose parser generator that converts an annotated
2context-free grammar into a deterministic LR or generalized LR (GLR) parser
3employing LALR(1) parser tables.  Bison can also generate IELR(1) or
4canonical LR(1) parser tables.  Once you are proficient with Bison, you can
5use it to develop a wide range of language parsers, from those used in
6simple desk calculators to complex programming languages.
7
8Bison is upward compatible with Yacc: all properly-written Yacc grammars
9work with Bison with no change.  Anyone familiar with Yacc should be able to
10use Bison with little trouble.  You need to be fluent in C, C++, D or Java
11programming in order to use Bison.
12
13Bison and the parsers it generates are portable, they do not require any
14specific compilers.
15
16GNU Bison's home page is https://gnu.org/software/bison/.
17
18# Installation
19## Build from git
20The [README-hacking.md file](README-hacking.md) is about building, modifying
21and checking Bison.  See its "Working from the Repository" section to build
22Bison from the git repo.  Roughly, run:
23
24    $ git submodule update --init
25    $ ./bootstrap
26
27then proceed with the usual `configure && make` steps.
28
29## Build from tarball
30See the [INSTALL file](INSTALL) for generic compilation and installation
31instructions.
32
33Bison requires GNU m4 1.4.6 or later.  See
34https://ftp.gnu.org/gnu/m4/m4-1.4.6.tar.gz.
35
36## Running a non installed bison
37Once you ran `make`, you might want to toy with this fresh bison before
38installing it.  In that case, do not use `src/bison`: it would use the
39*installed* files (skeletons, etc.), not the local ones.  Use `tests/bison`.
40
41## Colored diagnostics
42As an experimental feature, diagnostics are now colored, controlled by the
43`--color` and `--style` options.
44
45To use them, install the libtextstyle library, 0.20.5 or newer, before
46configuring Bison.  It is available from https://alpha.gnu.org/gnu/gettext/,
47for instance https://alpha.gnu.org/gnu/gettext/libtextstyle-0.20.5.tar.gz,
48or as part of Gettext 0.21 or newer, for instance
49https://ftp.gnu.org/gnu/gettext/gettext-0.21.tar.gz.
50
51The option --color supports the following arguments:
52- always, yes: Enable colors.
53- never, no: Disable colors.
54- auto, tty (default): Enable colors if the output device is a tty.
55
56To customize the styles, create a CSS file, say `bison-bw.css`, similar to
57
58    /* bison-bw.css */
59    .warning   { }
60    .error     { font-weight: 800; text-decoration: underline; }
61    .note      { }
62
63then invoke bison with `--style=bison-bw.css`, or set the `BISON_STYLE`
64environment variable to `bison-bw.css`.
65
66In some diagnostics, bison uses libtextstyle to emit special escapes to
67generate clickable hyperlinks.  The environment variable
68`NO_TERM_HYPERLINKS` can be used to suppress them.  This may be useful for
69terminal emulators which produce garbage output when they receive the escape
70sequence for a hyperlink. Currently (as of 2020), this affects some versions
71of emacs, guake, konsole, lxterminal, rxvt, yakuake.
72
73## Relocatability
74If you pass `--enable-relocatable` to `configure`, Bison is relocatable.
75
76A relocatable program can be moved or copied to a different location on the
77file system.  It can also be used through mount points for network sharing.
78It is possible to make symlinks to the installed and moved programs, and
79invoke them through the symlink.
80
81See "Enabling Relocatability" in the documentation.
82
83## Internationalization
84Bison supports two catalogs: one for Bison itself (i.e., for the
85maintainer-side parser generation), and one for the generated parsers (i.e.,
86for the user-side parser execution).  The requirements between both differ:
87bison needs ngettext, the generated parsers do not.  To simplify the build
88system, neither are installed if ngettext is not supported, even if
89generated parsers could have been localized.  See
90https://lists.gnu.org/r/bug-bison/2009-08/msg00006.html for more
91details.
92
93# Questions
94See the section FAQ in the documentation (doc/bison.info) for frequently
95asked questions.  The documentation is also available in PDF and HTML,
96provided you have a recent version of Texinfo installed: run `make pdf` or
97`make html`.
98
99If you have questions about using Bison and the documentation does not
100answer them, please send mail to <help-bison@gnu.org>.
101
102# Bug reports
103Please send bug reports to <bug-bison@gnu.org>.  Be sure to include the
104version number from `bison --version`, and a complete, self-contained test
105case in each bug report.
106
107# Copyright statements
108For any copyright year range specified as YYYY-ZZZZ in this package, note
109that the range specifies every single year in that closed interval.
110
111<!--
112
113LocalWords:  parsers ngettext Texinfo pdf html YYYY ZZZZ ispell american md
114LocalWords:  MERCHANTABILITY GLR LALR IELR submodule init README src bw
115LocalWords:  Relocatability symlinks symlink
116
117Local Variables:
118mode: markdown
119fill-column: 76
120ispell-dictionary: "american"
121End:
122
123Copyright (C) 1992, 1998-1999, 2003-2005, 2008-2015, 2018-2021 Free
124Software Foundation, Inc.
125
126This file is part of GNU bison, the GNU Compiler Compiler.
127
128Permission is granted to copy, distribute and/or modify this document
129under the terms of the GNU Free Documentation License, Version 1.3 or
130any later version published by the Free Software Foundation; with no
131Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
132Texts.  A copy of the license is included in the "GNU Free
133Documentation License" file as part of this distribution.
134
135-->
136

README-alpha

1-*- text -*-
2
3This is a test release of this package.  Using it more or less
4implicitly signs you up to help us find whatever problems you report.
5
6The documentation still needs more work.  Suggestions welcome.
7Patches even more welcome.
8
9Please send comments and problem reports about this test release to
10<bug-bison@gnu.org>.  This program will get better only if you report
11the problems you encounter.
12
13-----
14
15Copyright (C) 2002, 2004, 2009-2015, 2018-2021 Free Software Foundation,
16Inc.
17
18This file is part of GNU Bison.
19
20This program is free software: you can redistribute it and/or modify
21it under the terms of the GNU General Public License as published by
22the Free Software Foundation, either version 3 of the License, or
23(at your option) any later version.
24
25This program is distributed in the hope that it will be useful,
26but WITHOUT ANY WARRANTY; without even the implied warranty of
27MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
28GNU General Public License for more details.
29
30You should have received a copy of the GNU General Public License
31along with this program.  If not, see <https://www.gnu.org/licenses/>.
32

README-hacking.md

1This file attempts to describe the rules to use when hacking Bison.
2Don't put this file into the distribution.
3
4Everything related to the development of Bison is on Savannah:
5https://savannah.gnu.org/projects/bison/.
6
7
8Working from the Repository
9===========================
10
11These notes intend to help people working on the checked-out sources.  These
12requirements do not apply when building from a distribution tarball.
13
14## Requirements
15
16We've opted to keep only the highest-level sources in the repository.  This
17eases our maintenance burden, (fewer merges etc.), but imposes more
18requirements on anyone wishing to build from the just-checked-out sources.
19For example, you have to use the latest stable versions of the maintainer
20tools we depend upon, including:
21
22- Autoconf <https://www.gnu.org/software/autoconf/>
23- Automake <https://www.gnu.org/software/automake/>
24- Flex <https://www.gnu.org/software/flex/>
25- Gettext <https://www.gnu.org/software/gettext/>
26- Gperf <https://www.gnu.org/software/gperf/>
27- Graphviz <https://www.graphviz.org>
28- Gzip <https://www.gnu.org/software/gzip/>
29- Help2man <https://www.gnu.org/software/help2man/>
30- Perl <https://www.cpan.org/>
31- Rsync <https://rsync.samba.org/>
32- Tar <https://www.gnu.org/software/tar/>
33- Texinfo <https://www.gnu.org/software/texinfo/>
34
35Valgrind <https://www.valgrind.org/> is also highly recommended, if it
36supports your architecture.
37
38If you're using a GNU/Linux distribution, the easiest way to install the
39above packages depends on your system.  The following shell command should
40work for Debian-based systems such as Ubuntu:
41
42    sudo apt-get install \
43      autoconf automake autopoint flex gperf graphviz help2man texinfo valgrind
44
45Bison is written using Bison grammars, so there are bootstrapping issues.
46The bootstrap script attempts to discover when the C code generated from the
47grammars is out of date, and to bootstrap with an out-of-date version of the
48C code, but the process is not foolproof.  Also, you may run into similar
49problems yourself if you modify Bison.
50
51Only building the initial full source tree will be a bit painful.  Later,
52after synchronizing from the repository a plain 'make' should be sufficient.
53Note, however, that when gnulib is updated, running './bootstrap' again
54might be needed.
55
56## First checkout
57
58Obviously, if you are reading these notes, you did manage to check out this
59package from the repository.  For the record, you will find all the relevant
60information on https://savannah.gnu.org/git/?group=bison.
61
62Bison uses Git submodules: subscriptions to other Git repositories.  In
63particular it uses gnulib, the GNU portability library.  To ask Git to
64perform the first checkout of the submodules, run
65
66    $ git submodule update --init
67
68The next step is to get other files needed to build, which are extracted
69from other source packages:
70
71    $ ./bootstrap
72
73Bootstrapping updates the submodules to the versions registered in the
74top-level directory.  To change gnulib, first check out the version you want
75in `gnulib`, then commit this change in Bison's repository, and finally run
76bootstrap.
77
78If it fails with missing symbols (e.g., `error: possibly undefined macro:
79AC_PROG_GNU_M4`), you are likely to have forgotten the submodule
80initialization part.  To recover from it, run `git reset --hard HEAD`, and
81restart with the submodule initialization.  Otherwise, there you are!  Just
82
83    $ ./configure
84    $ make
85    $ make check
86
87At this point, there should be no difference between your local copy, and
88the master copy:
89
90    $ git diff
91
92should output no difference.
93
94Enjoy!
95
96## Updating
97
98If you have git at version 1.8.2 or later, the command
99
100    $ git submodule update --recursive --remote
101
102will be useful for updating to the latest version of all submodules.
103
104Under earlier versions, use of submodules make things somewhat different
105because git does not yet support recursive operations: submodules must be
106taken care of explicitly.
107
108### Updating Bison
109
110If you pull a newer version of a branch, say via `git pull`, you might
111import requests for updated submodules.  A simple `git diff` will reveal if
112the current version of the submodule (i.e., the actual contents of the
113gnulib directory) and the current request from the subscriber (i.e., the
114reference of the version of gnulib that the Bison repository requests)
115differ.  To upgrade the submodules (i.e., to check out the version that is
116actually requested by the subscriber, run `git submodule update`.
117
118    $ git pull
119    $ git submodule update
120
121### Updating a submodule
122To update a submodule, say gnulib, do as follows:
123
124Get the most recent version of the master branch from git.
125
126    $ cd gnulib
127    $ git fetch
128    $ git checkout -b master --track origin/master
129
130Make sure Bison can live with that version of gnulib.
131
132    $ cd ..
133    $ ./bootstrap
134    $ make distcheck
135
136Register your changes.
137
138    $ git commit ...
139
140For a suggestion of what gnulib commit might be stable enough for a formal
141release, see the ChangeLog in the latest gnulib snapshot at
142https://erislabs.net/ianb/projects/gnulib/.
143
144The Autoconf files we use are currently:
145- m4/m4.m4
146- lib/m4sugar/m4sugar.m4
147- lib/m4sugar/foreach.m4
148
149These files don't change very often in Autoconf, so it should be relatively
150straight-forward to examine the differences in order to decide whether to
151update.
152
153## Troubleshooting
154
155Bison is self-hosted: its parser is generated by Bison.  We don't force
156ourselves to use the previous release of Bison, we use the current git
157master for several reasons:
158- dogfooding: let Bison be its first user
159- monitoring: seeing the diff on the generated parsers with git is very
160  helpful, as it allows to see easily the impact of the changes on a real
161  case parser.
162
163If you are unlucky the generated files, src/parse-gram.[ch], may be older
164than their source, src/parse-gram.y.  And your current version of Bison
165might not be able to grok it.  In that case, first refresh the generated
166files:
167
168    $ touch src/parse-gram.[ch]
169
170Then proceed.
171
172In case you wrecked your current copy of the parser, get back the previous
173version, compile bison, then force it to recreate the files:
174
175    $ git checkout HEAD^ src/parse-gram.[ch]
176    $ make -C _build
177    $ touch src/parse-gram.y
178    $ make -C _build
179
180
181Administrivia
182=============
183
184## If you incorporate a change from somebody on the net:
185First, if it is a large change, you must make sure they have signed the
186appropriate paperwork.  Second, be sure to add their name and email address
187to THANKS.
188
189## If a change fixes a test, mention the test in the commit message.
190
191## Bug reports
192If somebody reports a new bug, mention his name in the commit message and in
193the test case you write.  Put him into THANKS.
194
195The correct response to most actual bugs is to write a new test case which
196demonstrates the bug.  Then fix the bug, re-run the test suite, and check
197everything in.
198
199
200
201Hacking
202=======
203
204## Visible Changes
205Which include serious bug fixes, must be mentioned in NEWS.
206
207## Translations
208Only user visible strings are to be translated: error messages, bits of the
209.output file etc.  This excludes impossible error messages (comparable to
210assert/abort), and all the --trace output which is meant for the maintainers
211only.
212
213## Vocabulary
214- "lookahead", not "look-ahead".
215- "midrule", not "mid-rule".
216- "nonterminal", not "variable" or "non-terminal" or "non terminal".
217  Abbreviated as "nterm".
218- "shift/reduce" and "reduce/reduce", not "shift-reduce" or "shift reduce",
219  etc.
220
221## Syntax Highlighting
222It's quite nice to be in C++ mode when editing lalr1.cc for instance.
223However tools such as Emacs will be fooled by the fact that braces and
224parens do not nest, as in `[[}]]`.  As a consequence you might be misguided
225by its visual pairing to parens.  The m4-mode is safer.  Unfortunately the
226m4-mode is also fooled by `#` which is sees as a comment, stops pairing with
227parens/brackets that are inside...
228
229## Implementation Notes
230There are several places with interesting details about the implementation:
231- [Understanding C parsers generated by GNU
232Bison](https://www.cs.uic.edu/~spopuri/cparser.html) by Satya Kiran Popuri,
233is a wonderful piece of work that explains the implementation of Bison,
234- [src/gram.h](src/gram.h) documents the way the grammar is represented
235- [src/tables.h](src/tables.h) documents the generated tables
236- [data/README.md](data/README.md) contains details about the m4 implementation
237
238## Coding Style
239Do not add horizontal tab characters to any file in Bison's repository
240except where required.  For example, do not use tabs to format C code.
241However, make files, ChangeLog, and some regular expressions require tabs.
242Also, test cases might need to contain tabs to check that Bison properly
243processes tabs in its input.
244
245Prefer `res` as the name of the local variable that will be "return"ed by
246the function.
247
248In writing arithmetic comparisons, use "<" and "<=" rather than ">" and ">="
249<https://public-inbox.org/git/7vfyw7yebj.fsf_-_@assigned-by-dhcp.cox.net/>.
250
251### Bison
252Follow the GNU Coding Standards.
253
254Don't reinvent the wheel: we use gnulib, which features many components.
255Actually, Bison has legacy code that we should replace with gnulib modules
256(e.g., many ad hoc implementations of lists).
257
258#### Includes
259The `#include` directives follow an order:
260- first section for *.c files is `<config.h>`.  Don't include it in header
261  files
262- then, for *.c files, the corresponding *.h file
263- then possibly the `"system.h"` header
264- then the system headers.
265  Consider headers from `lib/` like system headers (i.e., `#include
266  <verify.h>`, not `#include "verify.h"`).
267- then headers from src/ with double quotes (`#include "getargs.h"`).
268
269Keep headers sorted alphabetically in each section.
270
271See also the [Header
272files](https://www.gnu.org/software/gnulib/manual/html_node/Header-files.html)
273and the [Implementation
274files](https://www.gnu.org/software/gnulib/manual/html_node/Implementation-files.html#Implementation-files)
275nodes of the gnulib documentation.
276
277Some source files are in the build tree (e.g., `src/scan-gram.c` made from
278`src/scan-gram.l`).  For them to find the headers from `src/`, we actually
279use `#include "src/getargs.h"` instead of `#include "getargs.h"`---that
280saves us from additional `-I` flags.
281
282### Skeletons
283We try to use the "typical" coding style for each language.
284
285#### CPP
286We indent the CPP directives this way:
287
288```
289#if FOO
290# if BAR
291#  define BAZ
292# endif
293#endif
294```
295
296Don't indent with leading spaces in the skeletons (it's OK in the grammar
297files though, e.g., in `%code {...}` blocks).
298
299On occasions, use `cppi -c` to see where we stand.  We don't aim at full
300correctness: depending `-d`, some bits can be in the *.c file, or the *.h
301file within the double-inclusion cpp-guards.  In that case, favor the case
302of the *.h file, but don't waste time on this.
303
304Don't hesitate to leave a comment on the `#endif` (e.g., `#endif /* FOO
305*/`), especially for long blocks.
306
307There is no consistency on `! defined` vs. `!defined`.  The day gnulib
308decides, we'll follow them.
309
310#### C/C++
311Follow the GNU Coding Standards.
312
313The `glr.c` skeleton was implemented with `camlCase`.  We are migrating it
314to `snake_case`.  Because we are gradually standardizing the code, it is
315currently inconsistent.
316
317Use `YYFOO` and `yyfoo` for entities that are exposed to the user.  They are
318part of our contract with the users wrt backward compatibility.
319
320Use `YY_FOO` and `yy_foo` for private matters.  Users should not use them,
321we are free to change them without fear of backward compatibility issues.
322
323Use `*_t` for types, especially for `yy*_t` in which case we shouldn't worry
324about the C standard introducing such a name.
325
326#### C++
327Follow the [C++ Core
328Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines).
329The [Google ones](https://google.github.io/styleguide/cppguide.html) may be
330interesting too.
331
332Our enumerators, such as the kinds (symbol and token kinds), should be lower
333case, but it was too late to follow that track for token kinds, and symbol
334kind enumerators are made to be consistent with them.
335
336Use `*_type` for type aliases.  Use `foo_get()` and `foo_set(v)` for
337accessors, or simply `foo()` and `foo(v)`.
338
339Use the `yy` prefix for private stuff, but there's no need for it in the
340public API.  The `yy` prefix is already taken care of via the namespace.
341
342#### Java
343We follow the [Java Code
344Conventions](https://www.oracle.com/technetwork/java/codeconventions-150003.pdf)
345and [Google Java Style
346Guide](https://google.github.io/styleguide/javaguide.html).  Unfortunately
347at some point some GNU Coding Style was installed in Java, but it's an
348error.  So we should for instance stop putting spaces in function calls.
349Because we are standardizing the code, it is currently inconsistent.  Treat
350acronyms as words: `YYLacStack`, not `YYLACStack`.
351
352Use a 2-space indentation (Google) rather than 4 (Oracle).
353
354Don't use the `yy` prefix for public members: `getExpectedTokens`, not
355`yyexpectedTokens` or `yygetExpectedTokens`.  Keep the `yy` prefix though
356for private details.
357
358## Commit Messages
359Imitate the style we use.  Use `git log` to get sources of inspiration.
360
361If the changes have a small impact on Bison's generated parser, embed these
362changes in the commit itself.  If the impact is large, first push all the
363changes except those about src/parse-gram.[ch], and then another commit
364named "regen" which is only about them.
365
366## Debugging
367Bison supports tracing of its various steps, via the `--trace` option.
368Since it is not meant for the end user, it is not displayed by `bison
369--help`, nor is it documented in the manual.  Instead, run `bison
370--trace=help`.
371
372## Documentation
373Use `@option` for options and options with their argument if they have no
374space (e.g., `@option{-Dfoo=bar}`).  However, use `@samp` elsewhere (e.g.,
375`@samp{-I foo}`).
376
377
378Test Suite
379==========
380
381## make check
382Consume without moderation.  It is composed of two kinds of tests: the
383examples, and the main test suite.
384
385### The Examples
386In examples/, there is a number of ready-to-use examples (see
387[examples/README.md](examples/README.md)).  These examples have small test
388suites run by `make check`.  The test results are in local `*.log` files
389(e.g., `$build/examples/c/calc/calc.log`).
390
391To check only the examples, run `make check-examples`.  To check just one
392example,
393
394    make check-examples TESTS='examples/c/bistromathic/bistromathic.test'
395
396### The Main Test Suite
397The main test suite, in tests/, is written on top of GNU Autotest, which is
398part of Autoconf.  Run `info autoconf 'Using Autotest'` to read the
399documentation, not only about how to write tests, but also where are the
400logs, how to read them etc.
401
402The main test suite generates a log for each test (e.g.,
403`$build/tests/testsuite.dir/004/testsuite.log` for test #4), and a main log
404file in `$build/tests/testsuite.log`.  The latter is meant for end users: it
405contains lots of details that should help diagnosing issues, including build
406issues.  The per-test logs are more convenient when working locally.
407
408#### TESTSUITEFLAGS
409To run just the main test suite, run `make check-tests`.
410
411The default is for `make check-tests` to run all tests sequentially.  This
412can be very time consuming when checking repeatedly or on slower setups.
413This can be sped up in two ways.
414
4151. Using -j, in a make-like fashion, for example:
416
417    $ make check-tests TESTSUITEFLAGS='-j8'
418
419When using GNU Make, TESTSUITEFLAGS defaults to the -jN passed to it, so you
420may simply run
421
422    $ make check-tests -j8
423
4242. Running only the tests of a certain category. See
425[tests/README.md](tests/README.md#keywords) for the list of categories.
426
427To get a list of all the tests (and their keywords for -k), run
428
429    $ ./tests/testsuite -l
430
431To run a specific set of tests, use -k (for "keyword"). For example:
432
433    $ make check-tests TESTSUITEFLAGS='-k c++'
434
435Both can be combined.
436
437    $ make check-tests TESTSUITEFLAGS='-j8 -k c++'
438
439To rerun the tests that failed:
440
441    $ make recheck -j5
442
443#### Updating the Expectations
444Sometimes some changes have a large impact on the test suite (e.g., when we
445added the `[-Wother]` part to all the warnings).  Part of the update can be
446done with a crude tool: `build-aux/update-test`.
447
448Once you ran the test suite, and therefore have many `testsuite.log` files,
449run `make update-tests`.  Or, by hand, from the *source* tree:
450
451    $ ./build-aux/update-test $build/tests/testsuite.dir/*/testsuite.log
452
453where `$build` would be your build tree.  This will hopefully update most
454tests.  Re-run the test suite.  It might be interesting to run `update-test`
455again, since some early failures may stop latter tests from being run.  Yet
456at some point, you'll have to fix remaining issues by hand...
457
458
459## Running Java parsers
460Use the `javaexec.sh` script.  For instance to run the parser of test case
461504:
462
463    $ sh ./_build/javaexec.sh -cp ./_build/tests/testsuite.dir/504 Calc
464
465## Using Sanitizers
466Address sanitizer (ASAN) and undefined-behavior sanitizer (UBSAN) are very
467useful.  Here's one way to set them up with GCC 10 on Mac Ports
468
4691. Configure with
470   ```
471   $ ./configure -C --enable-gcc-warnings \
472       CPPFLAGS='-isystem /opt/local/include' \
473       CC='gcc-mp-10 -fsanitize=address -fsanitize=undefined' \
474       CFLAGS='-ggdb' \
475       CXX='g++-mp-10.0 -fsanitize=address -fsanitize=undefined' \
476       CXXFLAGS='-ggdb' \
477       LDFLAGS='-L/opt/local/lib'
478   ```
479
4802. Compile
481
4823. Generate debug symbols:
483
484   ```
485   $ dsymutil src/bison
486   ```
487
4884. Run the tests with leak detection enabled
489   (`ASAN_OPTIONS=detect_leaks=1`).  E.g. for counterexamples:
490   ```
491   $ make check-tests TESTSUITEFLAGS='-j5 -k cex' ASAN_OPTIONS=detect_leaks=1
492   ```
493
4945. You might need a suppression file.  See
495   https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer#suppressions.
496   With G++ on a Mac, you might need a suppression file (say `leak.supp`)
497   that contains:
498
499   ```
500   leak:std::clog
501   ```
502
503   and pass the additional flags
504   `LSAN_OPTIONS=suppressions=$PWD/leak.supp,print_suppressions=0`
505
5066. To run the debugger, you might want something like this:
507   ```
508   $ YYDEBUG=1 \
509     UBSAN_OPTIONS=print_stacktrace=1 \
510     LSAN_OPTIONS=suppressions=$PWD/leak.supp,print_suppressions=0 \
511     ASAN_OPTIONS=detect_leaks=1 \
512     lldb -- ./_build/tests/testsuite.dir/712/glr-regr2a ./_build/tests/testsuite.dir/712/input1.txt
513   ```
514
515   In lldb to set a break on ubsan, try `rbreak ^__ubsan_handle_`.
516
517## make maintainer-check-valgrind
518This target uses valgrind both to check bison, and the generated parsers.
519
520This is not mature on Mac OS X.  First, Valgrind does support the way bison
521calls m4, so Valgrind cannot be used to check bison on Mac OS X.
522
523Second, there are many errors that come from the platform itself, not from
524bison.  build-aux/darwin11.4.0.valgrind addresses some of them.
525
526Third, valgrind issues warnings such as:
527
528    --99312:0:syswrap- WARNING: Ignoring sigreturn( ..., UC_RESET_ALT_STACK );
529
530which cause the test to fail uselessly.  It is hard to ignore these errors
531with a major overhaul of the way instrumentation is performed in the test
532suite.  So currently, do not try to run valgrind on Mac OS X.
533
534## Release checks
535Try to run the test suite with more severe conditions before a
536release:
537
538- Configure the package with --enable-gcc-warnings, so that one checks that
539  1. Bison compiles cleanly, 2. the parsers it produces compile cleanly too.
540
541- Maybe build with -DGNULIB_POSIXCHECK, which suggests gnulib modules that
542  can fix portability issues.  See if you really want to pay attention to
543  its warnings; there's no need to obey blindly to it
544  (<https://lists.gnu.org/r/bison-patches/2012-05/msg00057.html>).
545
546- Check with `make syntax-check` if there are issues diagnosed by gnulib.
547
548- run `make maintainer-check` which:
549  - runs `valgrind -q bison` to run Bison under Valgrind.
550  - runs the parsers under Valgrind.
551  - runs the test suite with G++ as C compiler...
552
553- run `make maintainer-check-push`, which runs `make maintainer-check` while
554  activating the push implementation and its pull interface wrappers in many
555  test cases that were originally written to exercise only the pull
556  implementation.  This makes certain the push implementation can perform
557  every task the pull implementation can.
558
559- run `make maintainer-check-xml`, which runs `make maintainer-check` while
560  checking Bison's XML automaton report for every working grammar passed to
561  Bison in the test suite.  The check just diffs the output of Bison's
562  included XSLT style sheets with the output of --report=all and --graph.
563
564- running `make maintainer-check-release` takes care of running
565  maintainer-check, maintainer-check-push and maintainer-check-xml.
566
567- Change tests/atlocal/CFLAGS to add your preferred options.
568
569- Test with a very recent version of GCC for both C and C++.  Testing with
570  older versions that are still in use is nice too.
571
572## gnulib
573To run tests on gnulib components (e.g., on bitset):
574
575    cd gnulib
576    ./gnulib-tool --test bitset-tests
577
578possibly within a specified environment:
579
580    CC='gcc-mp-8 -fsanitize=undefined' ./gnulib-tool --test bitset-tests
581
582To be able to run the tests several times, and to use symlinks instead of
583copies so that one can update the origin gnulib directory and immediately
584re-run the tests, run:
585
586    ./gnulib-tool --symlink --create-test --dir=/tmp/gnutest bitset-tests
587    cd /tmp/gnutest
588    ./configure -C CC='gcc-mp-8 -fsanitize=undefined' CFLAGS='-ggdb'
589    make check
590
591
592## Docker
593
594Running old compilers is not very easy.  Docker can be used for some of
595them.  Have a look at .travis.yml for setups.  Move the tarball in `/tmp`
596and run, for instance:
597
598```
599docker run -v /tmp:/tmp -it ubuntu:xenial
600```
601
602This way, the host and guest machines share `/tmp`.
603
604### GCC 4.6
605On Ubuntu Xenial.
606
607```
608apt-get update
609apt-get install software-properties-common
610apt-add-repository -y "ppa:ubuntu-toolchain-r/test"
611apt-get update
612apt-get install -y gcc-4.6 g++-4.6 m4 make
613```
614
615## Stow
616
617If you want to install several versions of Bison using GNU Stow, do
618something like this:
619
620```
621for v in 3.7 3.7.1
622do
623  cd /tmp
624  wget https://ftp.gnu.org/gnu/bison/bison-$v.tar.xz
625  tar xf bison-$v.tar.xz
626  cd bison-$v
627  ./configure --prefix /usr/local/stow/bison-$v
628  make -j4
629  sudo make install
630done
631```
632
633Release Procedure
634=================
635
636See the [README-release file](README-release), created when the package is
637bootstrapped.
638
639<!--
640
641Copyright (C) 2002-2005, 2007-2015, 2018-2021 Free Software Foundation,
642Inc.
643
644This file is part of GNU Bison.
645
646This program is free software: you can redistribute it and/or modify
647it under the terms of the GNU General Public License as published by
648the Free Software Foundation, either version 3 of the License, or
649(at your option) any later version.
650
651This program is distributed in the hope that it will be useful,
652but WITHOUT ANY WARRANTY; without even the implied warranty of
653MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
654GNU General Public License for more details.
655
656You should have received a copy of the GNU General Public License
657along with this program.  If not, see <https://www.gnu.org/licenses/>.
658
659Local Variables:
660mode: markdown
661fill-column: 76
662ispell-dictionary: "american"
663End:
664
665LocalWords:  Automake Autoconf Gettext Gzip Rsync Valgrind gnulib submodules
666LocalWords:  submodule init cd distcheck ChangeLog valgrind sigreturn sudo
667LocalWords:  UC gcc DGNULIB POSIXCHECK xml XSLT glr lalr README po runtime rc
668LocalWords:  gnupload gnupg gpg keyserver BDF ncftp filename clearsign cvs dir
669LocalWords:  symlinks vti html lt POSIX Cc'ed Graphviz Texinfo autoconf jN
670LocalWords:  automake autopoint graphviz texinfo PROG Wother parsers YYFOO
671LocalWords:  TESTSUITEFLAGS deprec struct gnulib's getopt config ggdb yyfoo
672LocalWords:  bitset fsanitize symlink CFLAGS MERCHANTABILITY ispell wrt YY
673LocalWords:  american Administrivia camlCase yy accessors namespace src hoc
674LocalWords:  getExpectedTokens yyexpectedTokens yygetExpectedTokens parens
675LocalWords:  regen dogfooding Autotest testsuite getargs CPP BAZ endif cppi
676LocalWords:  cpp javaexec cp Calc ASAN UBSAN CPPFLAGS isystem CXX cex Gperf
677LocalWords:  CXXFLAGS LDFLAGS dsymutil gperf
678
679-->
680

README.md

1GNU Bison is a general-purpose parser generator that converts an annotated
2context-free grammar into a deterministic LR or generalized LR (GLR) parser
3employing LALR(1) parser tables.  Bison can also generate IELR(1) or
4canonical LR(1) parser tables.  Once you are proficient with Bison, you can
5use it to develop a wide range of language parsers, from those used in
6simple desk calculators to complex programming languages.
7
8Bison is upward compatible with Yacc: all properly-written Yacc grammars
9work with Bison with no change.  Anyone familiar with Yacc should be able to
10use Bison with little trouble.  You need to be fluent in C, C++, D or Java
11programming in order to use Bison.
12
13Bison and the parsers it generates are portable, they do not require any
14specific compilers.
15
16GNU Bison's home page is https://gnu.org/software/bison/.
17
18# Installation
19## Build from git
20The [README-hacking.md file](README-hacking.md) is about building, modifying
21and checking Bison.  See its "Working from the Repository" section to build
22Bison from the git repo.  Roughly, run:
23
24    $ git submodule update --init
25    $ ./bootstrap
26
27then proceed with the usual `configure && make` steps.
28
29## Build from tarball
30See the [INSTALL file](INSTALL) for generic compilation and installation
31instructions.
32
33Bison requires GNU m4 1.4.6 or later.  See
34https://ftp.gnu.org/gnu/m4/m4-1.4.6.tar.gz.
35
36## Running a non installed bison
37Once you ran `make`, you might want to toy with this fresh bison before
38installing it.  In that case, do not use `src/bison`: it would use the
39*installed* files (skeletons, etc.), not the local ones.  Use `tests/bison`.
40
41## Colored diagnostics
42As an experimental feature, diagnostics are now colored, controlled by the
43`--color` and `--style` options.
44
45To use them, install the libtextstyle library, 0.20.5 or newer, before
46configuring Bison.  It is available from https://alpha.gnu.org/gnu/gettext/,
47for instance https://alpha.gnu.org/gnu/gettext/libtextstyle-0.20.5.tar.gz,
48or as part of Gettext 0.21 or newer, for instance
49https://ftp.gnu.org/gnu/gettext/gettext-0.21.tar.gz.
50
51The option --color supports the following arguments:
52- always, yes: Enable colors.
53- never, no: Disable colors.
54- auto, tty (default): Enable colors if the output device is a tty.
55
56To customize the styles, create a CSS file, say `bison-bw.css`, similar to
57
58    /* bison-bw.css */
59    .warning   { }
60    .error     { font-weight: 800; text-decoration: underline; }
61    .note      { }
62
63then invoke bison with `--style=bison-bw.css`, or set the `BISON_STYLE`
64environment variable to `bison-bw.css`.
65
66In some diagnostics, bison uses libtextstyle to emit special escapes to
67generate clickable hyperlinks.  The environment variable
68`NO_TERM_HYPERLINKS` can be used to suppress them.  This may be useful for
69terminal emulators which produce garbage output when they receive the escape
70sequence for a hyperlink. Currently (as of 2020), this affects some versions
71of emacs, guake, konsole, lxterminal, rxvt, yakuake.
72
73## Relocatability
74If you pass `--enable-relocatable` to `configure`, Bison is relocatable.
75
76A relocatable program can be moved or copied to a different location on the
77file system.  It can also be used through mount points for network sharing.
78It is possible to make symlinks to the installed and moved programs, and
79invoke them through the symlink.
80
81See "Enabling Relocatability" in the documentation.
82
83## Internationalization
84Bison supports two catalogs: one for Bison itself (i.e., for the
85maintainer-side parser generation), and one for the generated parsers (i.e.,
86for the user-side parser execution).  The requirements between both differ:
87bison needs ngettext, the generated parsers do not.  To simplify the build
88system, neither are installed if ngettext is not supported, even if
89generated parsers could have been localized.  See
90https://lists.gnu.org/r/bug-bison/2009-08/msg00006.html for more
91details.
92
93# Questions
94See the section FAQ in the documentation (doc/bison.info) for frequently
95asked questions.  The documentation is also available in PDF and HTML,
96provided you have a recent version of Texinfo installed: run `make pdf` or
97`make html`.
98
99If you have questions about using Bison and the documentation does not
100answer them, please send mail to <help-bison@gnu.org>.
101
102# Bug reports
103Please send bug reports to <bug-bison@gnu.org>.  Be sure to include the
104version number from `bison --version`, and a complete, self-contained test
105case in each bug report.
106
107# Copyright statements
108For any copyright year range specified as YYYY-ZZZZ in this package, note
109that the range specifies every single year in that closed interval.
110
111<!--
112
113LocalWords:  parsers ngettext Texinfo pdf html YYYY ZZZZ ispell american md
114LocalWords:  MERCHANTABILITY GLR LALR IELR submodule init README src bw
115LocalWords:  Relocatability symlinks symlink
116
117Local Variables:
118mode: markdown
119fill-column: 76
120ispell-dictionary: "american"
121End:
122
123Copyright (C) 1992, 1998-1999, 2003-2005, 2008-2015, 2018-2021 Free
124Software Foundation, Inc.
125
126This file is part of GNU bison, the GNU Compiler Compiler.
127
128Permission is granted to copy, distribute and/or modify this document
129under the terms of the GNU Free Documentation License, Version 1.3 or
130any later version published by the Free Software Foundation; with no
131Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
132Texts.  A copy of the license is included in the "GNU Free
133Documentation License" file as part of this distribution.
134
135-->
136