xref: /bison/
Name Date Size

..05-Sep-20204 KiB

.gitattributesH A D13-Aug-20171

.gitignoreH A D22-Sep-2019401

.gitmodulesH A D13-Aug-2017184

.prev-versionH A D06-Sep-20206

.projectH A D13-Aug-201751

.travis.ymlH A D19-Sep-202014.6 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 D05-Jan-20201.4 KiB

bootstrapH A D13-Apr-202032.8 KiB

bootstrap.confH A D19-Sep-20203.3 KiB

build-aux/H13-May-20204 KiB

cfg.mkH A D06-Sep-20206.8 KiB

ChangeLog-1998H A D13-Aug-201745.7 KiB

ChangeLog-2012H A D05-Jan-2020977.5 KiB

configure.acH A D02-Aug-202012.4 KiB

COPYINGH A D13-Aug-201734.3 KiB

data/H30-Aug-20204 KiB

doc/H19-Sep-20204 KiB

etc/H19-Sep-20204 KiB

examples/H06-Sep-20204 KiB

gnulib/H13-Aug-20174 KiB

gnulib-po/H30-Apr-20204 KiB

lib/H19-Sep-20204 KiB

m4/H19-Sep-20204 KiB

Makefile.amH A D23-May-20204.9 KiB

NEWSH A D19-Sep-2020154.7 KiB

PACKAGINGH A D05-Jan-20201.9 KiB

po/H04-Jul-20204 KiB

READMEH A D02-Aug-20205.4 KiB

README-alphaH A D05-Jan-20201.1 KiB

README-hacking.mdH A D19-Sep-202022.4 KiB

README.mdH A D02-Aug-20205.4 KiB

runtime-po/H25-Dec-20184 KiB

src/HToday4 KiB

submodules/autoconf/H13-Aug-20174 KiB

tests/H19-Sep-20204 KiB

THANKSH A D02-Aug-202011.5 KiB

TODOH A D13-Sep-202031.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++ 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
90http://lists.gnu.org/archive/html/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-2020 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-2020 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 <http://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:
5http://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 <http://www.gnu.org/software/autoconf/>
23- Automake <http://www.gnu.org/software/automake/>
24- Flex <http://www.gnu.org/software/flex/>
25- Gettext <http://www.gnu.org/software/gettext/>
26- Gperf <http://www.gnu.org/software/gperf/>
27- Graphviz <http://www.graphviz.org>
28- Gzip <http://www.gnu.org/software/gzip/>
29- Help2man <http://www.gnu.org/software/help2man/>
30- Perl <http://www.cpan.org/>
31- Rsync <http://samba.anu.edu.au/rsync/>
32- Tar <http://www.gnu.org/software/tar/>
33- Texinfo <http://www.gnu.org/software/texinfo/>
34
35Valgrind <http://valgrind.org/> is also highly recommended, if it supports
36your 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 http://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
142http://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(http://www.gelato.unsw.edu.au/archives/git/0505/4507.html).
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](http://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.
350
351Use a 2-space indentation (Google) rather than 4 (Oracle).
352
353Don't use the "yy" prefix for public members: "getExpectedTokens", not
354"yyexpectedTokens" or "yygetExpectedTokens".
355
356## Commit Messages
357Imitate the style we use.  Use `git log` to get sources of inspiration.
358
359If the changes have a small impact on Bison's generated parser, embed these
360changes in the commit itself.  If the impact is large, first push all the
361changes except those about src/parse-gram.[ch], and then another commit
362named "regen" which is only about them.
363
364## Debugging
365Bison supports tracing of its various steps, via the `--trace` option.
366Since it is not meant for the end user, it is not displayed by `bison
367--help`, nor is it documented in the manual.  Instead, run `bison
368--trace=help`.
369
370## Documentation
371Use `@option` for options and options with their argument if they have no
372space (e.g., `@option{-Dfoo=bar}`).  However, use `@samp` elsewhere (e.g.,
373`@samp{-I foo}`).
374
375
376Test Suite
377==========
378
379## make check
380Consume without moderation.  It is composed of two kinds of tests: the
381examples, and the main test suite.
382
383### The Examples
384In examples/, there is a number of ready-to-use examples (see
385[examples/README.md](examples/README.md)).  These examples have small test
386suites run by `make check`.  The test results are in local `*.log` files
387(e.g., `$build/examples/c/calc/calc.log`).
388
389### The Main Test Suite
390The main test suite, in tests/, is written on top of GNU Autotest, which is
391part of Autoconf.  Run `info autoconf 'Using Autotest'` to read the
392documentation, not only about how to write tests, but also where are the
393logs, how to read them etc.
394
395The main test suite generates a log for each test (e.g.,
396`$build/tests/testsuite.dir/004/testsuite.log` for test #4), and a main log
397file in `$build/tests/testsuite.log`.  The latter is meant for end users: it
398contains lots of details that should help diagnosing issues, including build
399issues.  The per-test logs are more convenient when working locally.
400
401#### TESTSUITEFLAGS
402To run just the main test suite, run `make check-local`.
403
404The default is for make check-local to run all tests sequentially.  This can
405be very time consuming when checking repeatedly or on slower setups.  This
406can be sped up in two ways:
407
408Using -j, in a make-like fashion, for example:
409
410    $ make check-local TESTSUITEFLAGS='-j8'
411
412Actually, when using GNU Make, TESTSUITEFLAGS defaults to the -jN passed to
413it, so you may simply run
414
415    $ make check-local -j8
416
417Running only the tests of a certain category, as specified in the AT files
418with AT_KEYWORDS([[category]]). Categories include:
419- c++, for c++ parsers
420- deprec, for tests concerning deprecated constructs.
421- glr, for glr parsers
422- java, for java parsers
423- report, for automaton dumps
424
425To get a list of all the tests (and their keywords for -k), run
426
427    $ ./tests/testsuite -l
428
429To run a specific set of tests, use -k (for "keyword"). For example:
430
431    $ make check-local TESTSUITEFLAGS='-k c++'
432
433Both can be combined.
434
435    $ make check-local TESTSUITEFLAGS='-j8 -k c++'
436
437To rerun the tests that failed:
438
439    $ make recheck -j5
440
441#### Updating the Expectations
442Sometimes some changes have a large impact on the test suite (e.g., when we
443added the `[-Wother]` part to all the warnings).  Part of the update can be
444done with a crude tool: `build-aux/update-test`.
445
446Once you ran the test suite, and therefore have many `testsuite.log` files,
447run `make update-tests`.  Or, by hand, from the *source* tree:
448
449    $ ./build-aux/update-test $build/tests/testsuite.dir/*/testsuite.log
450
451where `$build` would be your build tree.  This will hopefully update most
452tests.  Re-run the test suite.  It might be interesting to run `update-test`
453again, since some early failures may stop latter tests from being run.  Yet
454at some point, you'll have to fix remaining issues by hand...
455
456
457## Running Java parsers
458Use the `javaexec.sh` script.  For instance to run the parser of test case
459504:
460
461    $ sh ./_build/javaexec.sh -cp ./_build/tests/testsuite.dir/504 Calc
462
463## Using Sanitizers
464Address sanitizer (ASAN) and undefined-behavior sanitizer (UBSAN) are very
465useful.  Here's one way to set ASAN up with GCC 10 on Mac Ports
466
4671. Configure with
468
469    $ ./configure -C --enable-gcc-warnings \
470        CPPFLAGS='-isystem /opt/local/include' \
471        CC='gcc-mp-10 -fsanitize=address' \
472        CFLAGS='-ggdb' \
473        CXX='g++-mp-10.0 -fsanitize=address' \
474        CXXFLAGS='-ggdb' \
475        LDFLAGS='-L/opt/local/lib'
476
4772. Compile
478
4793. Generate debug symbols:
480
481    $ dsymutil src/bison
482
4834. Run the tests with leak detection enabled
484   (`ASAN_OPTIONS=detect_leaks=1`).  E.g. for counterexamples:
485
486    $ make check-local TESTSUITEFLAGS='-j5 -k cex' ASAN_OPTIONS=detect_leaks=1
487
488## make maintainer-check-valgrind
489This target uses valgrind both to check bison, and the generated parsers.
490
491This is not mature on Mac OS X.  First, Valgrind does support the way bison
492calls m4, so Valgrind cannot be used to check bison on Mac OS X.
493
494Second, there are many errors that come from the platform itself, not from
495bison.  build-aux/darwin11.4.0.valgrind addresses some of them.
496
497Third, valgrind issues warnings such as:
498
499    --99312:0:syswrap- WARNING: Ignoring sigreturn( ..., UC_RESET_ALT_STACK );
500
501which cause the test to fail uselessly.  It is hard to ignore these errors
502with a major overhaul of the way instrumentation is performed in the test
503suite.  So currently, do not try to run valgrind on Mac OS X.
504
505## Release checks
506Try to run the test suite with more severe conditions before a
507release:
508
509- Configure the package with --enable-gcc-warnings, so that one checks that
510  1. Bison compiles cleanly, 2. the parsers it produces compile cleanly too.
511
512- Maybe build with -DGNULIB_POSIXCHECK, which suggests gnulib modules that
513  can fix portability issues.  See if you really want to pay attention to
514  its warnings; there's no need to obey blindly to it
515  (<http://lists.gnu.org/archive/html/bison-patches/2012-05/msg00057.html>).
516
517- Check with `make syntax-check` if there are issues diagnosed by gnulib.
518
519- run `make maintainer-check` which:
520  - runs `valgrind -q bison` to run Bison under Valgrind.
521  - runs the parsers under Valgrind.
522  - runs the test suite with G++ as C compiler...
523
524- run `make maintainer-check-push`, which runs `make maintainer-check` while
525  activating the push implementation and its pull interface wrappers in many
526  test cases that were originally written to exercise only the pull
527  implementation.  This makes certain the push implementation can perform
528  every task the pull implementation can.
529
530- run `make maintainer-check-xml`, which runs `make maintainer-check` while
531  checking Bison's XML automaton report for every working grammar passed to
532  Bison in the test suite.  The check just diffs the output of Bison's
533  included XSLT style sheets with the output of --report=all and --graph.
534
535- running `make maintainer-check-release` takes care of running
536  maintainer-check, maintainer-check-push and maintainer-check-xml.
537
538- Change tests/atlocal/CFLAGS to add your preferred options.
539
540- Test with a very recent version of GCC for both C and C++.  Testing with
541  older versions that are still in use is nice too.
542
543## gnulib
544To run tests on gnulib components (e.g., on bitset):
545
546    cd gnulib
547    ./gnulib-tool --test bitset-tests
548
549possibly within a specified environment:
550
551    CC='gcc-mp-8 -fsanitize=undefined' ./gnulib-tool --test bitset-tests
552
553To be able to run the tests several times, and to use symlinks instead of
554copies so that one can update the origin gnulib directory and immediately
555re-run the tests, run:
556
557    ./gnulib-tool --symlink --create-test --dir=/tmp/gnutest bitset-tests
558    cd /tmp/gnutest
559    ./configure -C CC='gcc-mp-8 -fsanitize=undefined' CFLAGS='-ggdb'
560    make check
561
562
563## Docker
564
565Running old compilers is not very easy.  Docker can be used for some of
566them.  Have a look at .travis.yml for setups.  Move the tarball in `/tmp`
567and run, for instance:
568
569```
570docker run -v /tmp:/tmp -it ubuntu:xenial
571```
572
573This way, the host and guest machines share `/tmp`.
574
575### GCC 4.6
576On Ubuntu Xenial.
577
578```
579apt-get update
580apt-get install software-properties-common
581apt-add-repository -y "ppa:ubuntu-toolchain-r/test"
582apt-get update
583apt-get install -y gcc-4.6 g++-4.6 m4 make
584```
585
586Release Procedure
587=================
588
589See the [README-release file](README-release), created when the package is
590bootstrapped.
591
592<!--
593
594Copyright (C) 2002-2005, 2007-2015, 2018-2020 Free Software Foundation,
595Inc.
596
597This file is part of GNU Bison.
598
599This program is free software: you can redistribute it and/or modify
600it under the terms of the GNU General Public License as published by
601the Free Software Foundation, either version 3 of the License, or
602(at your option) any later version.
603
604This program is distributed in the hope that it will be useful,
605but WITHOUT ANY WARRANTY; without even the implied warranty of
606MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
607GNU General Public License for more details.
608
609You should have received a copy of the GNU General Public License
610along with this program.  If not, see <http://www.gnu.org/licenses/>.
611
612Local Variables:
613mode: markdown
614fill-column: 76
615ispell-dictionary: "american"
616End:
617
618LocalWords:  Automake Autoconf Gettext Gzip Rsync Valgrind gnulib submodules
619LocalWords:  submodule init cd distcheck ChangeLog valgrind sigreturn sudo
620LocalWords:  UC gcc DGNULIB POSIXCHECK xml XSLT glr lalr README po runtime rc
621LocalWords:  gnupload gnupg gpg keyserver BDF ncftp filename clearsign cvs dir
622LocalWords:  symlinks vti html lt POSIX Cc'ed Graphviz Texinfo autoconf jN
623LocalWords:  automake autopoint graphviz texinfo PROG Wother parsers YYFOO
624LocalWords:  TESTSUITEFLAGS deprec struct gnulib's getopt config ggdb yyfoo
625LocalWords:  bitset fsanitize symlink CFLAGS MERCHANTABILITY ispell wrt YY
626LocalWords:  american Administrivia camlCase yy accessors namespace src hoc
627LocalWords:  getExpectedTokens yyexpectedTokens yygetExpectedTokens parens
628LocalWords:  regen dogfooding Autotest testsuite getargs CPP BAZ endif cppi
629LocalWords:  cpp javaexec cp Calc ASAN UBSAN CPPFLAGS isystem CXX cex Gperf
630LocalWords:  CXXFLAGS LDFLAGS dsymutil gperf
631
632-->
633

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++ 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
90http://lists.gnu.org/archive/html/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-2020 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