xref: /bison/
Name Date Size

..29-Nov-20194 KiB

.gitattributesH A D13-Aug-20171

.gitignoreH A D22-Sep-2019401

.gitmodulesH A D13-Aug-2017184

.prev-versionH A D19-Jan-20206

.projectH A D13-Aug-201751

.travis.ymlH A D19-Jan-202013.4 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 D11-Jan-202032.8 KiB

bootstrap.confH A D05-Jan-20203.2 KiB

build-aux/H05-Jan-20204 KiB

cfg.mkH A D05-Jan-20206.7 KiB

ChangeLog-1998H A D13-Aug-201745.7 KiB

ChangeLog-2012H A D05-Jan-2020977.5 KiB

configure.acH A D19-Jan-202012 KiB

COPYINGH A D13-Aug-201734.3 KiB

data/H05-Jan-20204 KiB

doc/H05-Jan-20204 KiB

etc/H05-Jan-20204 KiB

examples/H05-Jan-20204 KiB

gnulib/H13-Aug-20174 KiB

gnulib-po/H22-Sep-20194 KiB

lib/H11-Jan-20204 KiB

m4/H19-Jan-20204 KiB

Makefile.amH A D05-Jan-20204.5 KiB

NEWSH A D19-Jan-2020133.7 KiB

PACKAGINGH A D05-Jan-20201.9 KiB

po/H23-Apr-20194 KiB

READMEH A D05-Jan-20203.9 KiB

README-alphaH A D05-Jan-20201.1 KiB

README-hacking.mdH A D05-Jan-202019.2 KiB

README.mdH A D05-Jan-20203.9 KiB

runtime-po/H25-Dec-20184 KiB

src/H20-Jan-20204 KiB

submodules/autoconf/H13-Aug-20174 KiB

tests/HToday4 KiB

THANKSH A D19-Jan-202010.7 KiB

TODOH A D11-Jan-202022.5 KiB

README

1This package contains the GNU Bison parser generator.
2
3# Installation
4## Build from git
5Here are basic installation instructions for a repository checkout:
6
7    $ git submodule update --init
8    $ ./bootstrap
9
10then proceed with the usual `configure && make` steps.
11
12The file README-hacking.md is about building, modifying and checking Bison.
13
14## Build from tarball
15See the file INSTALL for generic compilation and installation instructions.
16
17Bison requires GNU m4 1.4.6 or later.  See
18https://ftp.gnu.org/gnu/m4/m4-1.4.6.tar.gz.
19
20## Colored diagnostics
21As an experimental feature, diagnostics are now colored, controlled by the
22`--color` and `--style` options.
23
24To use them, install the libtextstyle library before configuring Bison.  It
25is available from https://alpha.gnu.org/gnu/gettext/, for instance
26https://alpha.gnu.org/gnu/gettext/libtextstyle-0.8.tar.gz.
27
28The option --color supports the following arguments:
29- always, yes: Enable colors.
30- never, no: Disable colors.
31- auto, tty (default): Enable colors if the output device is a tty.
32
33To customize the styles, create a CSS file, say `bison-bw.css`, similar to
34
35    /* bison-bw.css */
36    .warning   { }
37    .error     { font-weight: 800; text-decoration: underline; }
38    .note      { }
39
40then invoke bison with `--style=bison-bw.css`, or set the `BISON_STYLE`
41environment variable to `bison-bw.css`.
42
43## Relocatability
44If you pass `--enable-relocatable` to `configure`, Bison is relocatable.
45
46A relocatable program can be moved or copied to a different location on the
47file system.  It can also be used through mount points for network sharing.
48It is possible to make symlinks to the installed and moved programs, and
49invoke them through the symlink.
50
51See "Enabling Relocatability" in the documentation.
52
53## Internationalization
54Bison supports two catalogs: one for Bison itself (i.e., for the
55maintainer-side parser generation), and one for the generated parsers (i.e.,
56for the user-side parser execution).  The requirements between both differ:
57bison needs ngettext, the generated parsers do not.  To simplify the build
58system, neither are installed if ngettext is not supported, even if
59generated parsers could have been localized.  See
60http://lists.gnu.org/archive/html/bug-bison/2009-08/msg00006.html for more
61details.
62
63# Questions
64See the section FAQ in the documentation (doc/bison.info) for frequently
65asked questions.  The documentation is also available in PDF and HTML,
66provided you have a recent version of Texinfo installed: run `make pdf` or
67`make html`.
68
69If you have questions about using Bison and the documentation does not
70answer them, please send mail to <help-bison@gnu.org>.
71
72# Bug reports
73Please send bug reports to <bug-bison@gnu.org>.  Be sure to include the
74version number from `bison --version`, and a complete, self-contained test
75case in each bug report.
76
77# Copyright statements
78For any copyright year range specified as YYYY-ZZZZ in this package, note
79that the range specifies every single year in that closed interval.
80
81<!--
82
83Copyright (C) 1992, 1998-1999, 2003-2005, 2008-2015, 2018-2020 Free
84Software Foundation, Inc.
85
86This file is part of GNU bison, the GNU Compiler Compiler.
87
88This program is free software: you can redistribute it and/or modify
89it under the terms of the GNU General Public License as published by
90the Free Software Foundation, either version 3 of the License, or
91(at your option) any later version.
92
93This program is distributed in the hope that it will be useful,
94but WITHOUT ANY WARRANTY; without even the implied warranty of
95MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
96GNU General Public License for more details.
97
98You should have received a copy of the GNU General Public License
99along with this program.  If not, see <http://www.gnu.org/licenses/>.
100
101Local Variables:
102mode: markdown
103fill-column: 76
104ispell-dictionary: "american"
105End:
106
107LocalWords:  parsers ngettext Texinfo pdf html YYYY ZZZZ ispell american
108LocalWords:  MERCHANTABILITY
109
110-->
111

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
8# Administrivia
9
10## If you incorporate a change from somebody on the net:
11First, if it is a large change, you must make sure they have signed the
12appropriate paperwork.  Second, be sure to add their name and email address
13to THANKS.
14
15## If a change fixes a test, mention the test in the commit message.
16
17## Bug reports
18If somebody reports a new bug, mention his name in the commit message and in
19the test case you write.  Put him into THANKS.
20
21The correct response to most actual bugs is to write a new test case which
22demonstrates the bug.  Then fix the bug, re-run the test suite, and check
23everything in.
24
25
26# Hacking
27
28## Visible changes
29Which include serious bug fixes, must be mentioned in NEWS.
30
31## Translations
32Only user visible strings are to be translated: error messages, bits of the
33.output file etc.  This excludes impossible error messages (comparable to
34assert/abort), and all the --trace output which is meant for the maintainers
35only.
36
37## Horizontal tabs
38Do not add horizontal tab characters to any file in Bison's repository
39except where required.  For example, do not use tabs to format C code.
40However, make files, ChangeLog, and some regular expressions require tabs.
41Also, test cases might need to contain tabs to check that Bison properly
42processes tabs in its input.
43
44
45# Working from the repository
46
47These notes intend to help people working on the checked-out sources.  These
48requirements do not apply when building from a distribution tarball.
49
50## Requirements
51
52We've opted to keep only the highest-level sources in the repository.  This
53eases our maintenance burden, (fewer merges etc.), but imposes more
54requirements on anyone wishing to build from the just-checked-out sources.
55For example, you have to use the latest stable versions of the maintainer
56tools we depend upon, including:
57
58- Autoconf <http://www.gnu.org/software/autoconf/>
59- Automake <http://www.gnu.org/software/automake/>
60- Flex <http://www.gnu.org/software/flex/>
61- Gettext <http://www.gnu.org/software/gettext/>
62- Graphviz <http://www.graphviz.org>
63- Gzip <http://www.gnu.org/software/gzip/>
64- Help2man <http://www.gnu.org/software/help2man/>
65- Perl <http://www.cpan.org/>
66- Rsync <http://samba.anu.edu.au/rsync/>
67- Tar <http://www.gnu.org/software/tar/>
68- Texinfo <http://www.gnu.org/software/texinfo/>
69
70Valgrind <http://valgrind.org/> is also highly recommended, if it supports
71your architecture.
72
73If you're using a GNU/Linux distribution, the easiest way to install the
74above packages depends on your system.  The following shell command should
75work for Debian-based systems such as Ubuntu:
76
77    sudo apt-get install \
78      autoconf automake autopoint flex graphviz help2man texinfo valgrind
79
80Bison is written using Bison grammars, so there are bootstrapping issues.
81The bootstrap script attempts to discover when the C code generated from the
82grammars is out of date, and to bootstrap with an out-of-date version of the
83C code, but the process is not foolproof.  Also, you may run into similar
84problems yourself if you modify Bison.
85
86Only building the initial full source tree will be a bit painful.  Later,
87after synchronizing from the repository a plain 'make' should be sufficient.
88Note, however, that when gnulib is updated, running './bootstrap' again
89might be needed.
90
91## First checkout
92
93Obviously, if you are reading these notes, you did manage to check out this
94package from the repository.  For the record, you will find all the relevant
95information on http://savannah.gnu.org/git/?group=bison.
96
97Bison uses Git submodules: subscriptions to other Git repositories.  In
98particular it uses gnulib, the GNU portability library.  To ask Git to
99perform the first checkout of the submodules, run
100
101    $ git submodule update --init
102
103The next step is to get other files needed to build, which are extracted
104from other source packages:
105
106    $ ./bootstrap
107
108Bootstrapping updates the submodules to the versions registered in the
109top-level directory.  To change gnulib, first check out the version you want
110in `gnulib`, then commit this change in Bison's repository, and finally run
111bootstrap.
112
113If it fails with missing symbols (e.g., `error: possibly undefined macro:
114AC_PROG_GNU_M4`), you are likely to have forgotten the submodule
115initialization part.  To recover from it, run `git reset --hard HEAD`, and
116restart with the submodule initialization.  Otherwise, there you are!  Just
117
118    $ ./configure
119    $ make
120    $ make check
121
122At this point, there should be no difference between your local copy, and
123the master copy:
124
125    $ git diff
126
127should output no difference.
128
129Enjoy!
130
131## Updating
132
133If you have git at version 1.8.2 or later, the command
134
135    $ git submodule update --recursive --remote
136
137will be useful for updating to the latest version of all submodules.
138
139Under earlier versions, use of submodules make things somewhat different
140because git does not yet support recursive operations: submodules must be
141taken care of explicitly.
142
143### Updating Bison
144
145If you pull a newer version of a branch, say via `git pull`, you might
146import requests for updated submodules.  A simple `git diff` will reveal if
147the current version of the submodule (i.e., the actual contents of the
148gnulib directory) and the current request from the subscriber (i.e., the
149reference of the version of gnulib that the Bison repository requests)
150differ.  To upgrade the submodules (i.e., to check out the version that is
151actually requested by the subscriber, run `git submodule update`.
152
153    $ git pull
154    $ git submodule update
155
156### Updating a submodule
157To update a submodule, say gnulib, do as follows:
158
159Get the most recent version of the master branch from git.
160
161    $ cd gnulib
162    $ git fetch
163    $ git checkout -b master --track origin/master
164
165Make sure Bison can live with that version of gnulib.
166
167    $ cd ..
168    $ ./bootstrap
169    $ make distcheck
170
171Register your changes.
172
173    $ git commit ...
174
175For a suggestion of what gnulib commit might be stable enough for a formal
176release, see the ChangeLog in the latest gnulib snapshot at
177http://erislabs.net/ianb/projects/gnulib/.
178
179The Autoconf files we use are currently:
180- m4/m4.m4
181- lib/m4sugar/m4sugar.m4
182- lib/m4sugar/foreach.m4
183
184These files don't change very often in Autoconf, so it should be relatively
185straight-forward to examine the differences in order to decide whether to
186update.
187
188# Test Suite
189
190## make check
191Consume without moderation.  It is composed of two kinds of tests: the
192examples, and the main test suite.
193
194### The Examples
195In examples/, there is a number of ready-to-use examples (see
196examples/README.md).  These examples have small test suites run by `make
197check`.  The test results are in local `*.log` files (e.g.,
198`$build/examples/c/calc/calc.log`).
199
200### The Main Test Suite
201The main test suite, in tests/, is written on top of GNU Autotest, which is
202part of Autoconf.  Run `info autoconf 'Using Autotest'` to read the
203documentation, not only about how to write tests, but also where are the
204logs, how to read them etc.
205
206The main test suite generates a log for each test (e.g.,
207`$build/tests/testsuite.dir/004/testsuite.log` for test #4), and a main log
208file in `$build/tests/testsuite.log`.  The latter is meant for end users: it
209contains lots of details that should help diagnosing issues, including build
210issues.  The per-test logs are more convenient when working locally.
211
212#### TESTSUITEFLAGS
213To run just the main test suite, run `make check-local`.
214
215The default is for make check-local to run all tests sequentially.  This can
216be very time consuming when checking repeatedly or on slower setups.  This
217can be sped up in two ways:
218
219Using -j, in a make-like fashion, for example:
220
221    $ make check-local TESTSUITEFLAGS='-j8'
222
223Actually, when using GNU Make, TESTSUITEFLAGS defaults to the -jN passed to
224it, so you may simply run
225
226    $ make check-local -j8
227
228Running only the tests of a certain category, as specified in the AT files
229with AT_KEYWORDS([[category]]). Categories include:
230- c++, for c++ parsers
231- deprec, for tests concerning deprecated constructs.
232- glr, for glr parsers
233- java, for java parsers
234- report, for automaton dumps
235
236To get a list of all the tests (and their keywords for -k), run
237
238    $ ./tests/testsuite -l
239
240To run a specific set of tests, use -k (for "keyword"). For example:
241
242    $ make check-local TESTSUITEFLAGS='-k c++'
243
244Both can be combined.
245
246    $ make check-local TESTSUITEFLAGS='-j8 -k c++'
247
248To rerun the tests that failed:
249
250    $ make recheck -j5
251
252#### Updating the Expectations
253Sometimes some changes have a large impact on the test suite (e.g., when we
254added the `[-Wother]` part to all the warnings).  Part of the update can be
255done with a crude tool: `build-aux/update-test`.
256
257Once you ran the test suite, and therefore have many `testsuite.log` files,
258run, from the source tree:
259
260    $ ./build-aux/update-test $build/tests/testsuite.dir/*/testsuite.log
261
262where `$build` would be your build tree.  This will hopefully update most
263tests.  Re-run the test suite.  It might be interesting to run `update-test`
264again, since some early failures may stop latter tests from being run.  Yet
265at some point, you'll have to fix remaining issues by hand...
266
267
268## make maintainer-check-valgrind
269This target uses valgrind both to check bison, and the generated parsers.
270
271This is not mature on Mac OS X.  First, Valgrind does support the way bison
272calls m4, so Valgrind cannot be used to check bison on Mac OS X.
273
274Second, there are many errors that come from the platform itself, not from
275bison.  build-aux/darwin11.4.0.valgrind addresses some of them.
276
277Third, valgrind issues warnings such as:
278
279    --99312:0:syswrap- WARNING: Ignoring sigreturn( ..., UC_RESET_ALT_STACK );
280
281which cause the test to fail uselessly.  It is hard to ignore these errors
282with a major overhaul of the way instrumentation is performed in the test
283suite.  So currently, do not try to run valgrind on Mac OS X.
284
285## Release checks
286Try to run the test suite with more severe conditions before a
287release:
288
289- Configure the package with --enable-gcc-warnings, so that one checks that
290  1. Bison compiles cleanly, 2. the parsers it produces compile cleanly too.
291
292- Maybe build with -DGNULIB_POSIXCHECK, which suggests gnulib modules that
293  can fix portability issues.  See if you really want to pay attention to
294  its warnings; there's no need to obey blindly to it
295  (<http://lists.gnu.org/archive/html/bison-patches/2012-05/msg00057.html>).
296
297- Check with `make syntax-check` if there are issues diagnosed by gnulib.
298
299- run `make maintainer-check` which:
300  - runs `valgrind -q bison` to run Bison under Valgrind.
301  - runs the parsers under Valgrind.
302  - runs the test suite with G++ as C compiler...
303
304- run `make maintainer-check-push`, which runs `make maintainer-check` while
305  activating the push implementation and its pull interface wrappers in many
306  test cases that were originally written to exercise only the pull
307  implementation.  This makes certain the push implementation can perform
308  every task the pull implementation can.
309
310- run `make maintainer-check-xml`, which runs `make maintainer-check` while
311  checking Bison's XML automaton report for every working grammar passed to
312  Bison in the test suite.  The check just diffs the output of Bison's
313  included XSLT style sheets with the output of --report=all and --graph.
314
315- running `make maintainer-check-release` takes care of running
316  maintainer-check, maintainer-check-push and maintainer-check-xml.
317
318- Change tests/atlocal/CFLAGS to add your preferred options.
319
320- Test with a very recent version of GCC for both C and C++.  Testing with
321  older versions that are still in use is nice too.
322
323## gnulib
324To run tests on gnulib components (e.g., on bitset):
325
326    cd gnulib
327    ./gnulib-tool --test bitset-tests
328
329possibly within a specified environment:
330
331    CC='gcc-mp-8 -fsanitize=undefined' ./gnulib-tool --test bitset-tests
332
333To be able to run the tests several times, and to use symlinks instead of
334copies so that one can update the origin gnulib directory and immediately
335re-run the tests, run:
336
337    ./gnulib-tool --symlink --create-test --dir=/tmp/gnutest bitset-tests
338    cd /tmp/gnutest
339    ./configure -C CC='gcc-mp-8 -fsanitize=undefined' CFLAGS='-ggdb'
340    make check
341
342# Release Procedure
343This section needs to be updated to take into account features from gnulib.
344In particular, be sure to read README-release.
345
346## Update the submodules.  See above.
347
348## Update maintainer tools, such as Autoconf.  See above.
349
350## Try to get the *.pot files to the Translation Project at least one
351week before a stable release, to give them time to translate them.  Before
352generating the *.pot files, make sure that po/POTFILES.in and
353runtime-po/POTFILES.in list all files with translatable strings.  This
354helps: `grep -l '\<_(' *`.
355
356## Tests
357See above.
358
359## Update the foreign files
360Running `./bootstrap` in the top level should update them all for you.  This
361covers PO files too.  Sometimes a PO file contains problems that causes it
362to be rejected by recent Gettext releases; please report these to the
363Translation Project.
364
365## Update README
366Make sure the information in README is current.  Most notably, make sure it
367recommends a version of GNU M4 that is compatible with the latest Bison
368sources.
369
370## Check copyright years.
371We update years in copyright statements throughout Bison once at the start
372of every year by running `make update-copyright`.  However, before a
373release, it's good to verify that it's actually been run.  Besides the
374copyright statement for each Bison file, check the copyright statements that
375the skeletons insert into generated parsers, and check all occurrences of
376`PACKAGE_COPYRIGHT_YEAR` in configure.ac.
377
378## Update NEWS, commit and tag.
379See do-release-commit-and-tag in README-release.  For a while, we used beta
380names such as `2.6_rc1`.  Now that we use gnulib in the release procedure,
381we must use `2.5.90`, which has the additional benefit of being properly
382sorted in `git tag -l`.
383
384## make alpha, beta, or stable
385See README-release.
386
387## Upload
388There are two ways to upload the tarballs to the GNU servers: using gnupload
389(from gnulib), or by hand.  Obviously prefer the former.  But in either
390case, be sure to read the following paragraph.
391
392### Setup
393You need `gnupg`.
394
395Make sure your public key has been uploaded at least to keys.gnupg.net.  You
396can upload it with:
397
398  gpg --keyserver keys.gnupg.net --send-keys F125BDF3
399
400where F125BDF3 should be replaced with your key ID.
401
402### Using gnupload
403You need `ncftp`.
404
405At the end `make stable` (or alpha/beta) will display the procedure to run.
406Just copy and paste it in your shell.
407
408### By hand
409
410The generic GNU upload procedure is at
411http://www.gnu.org/prep/maintain/maintain.html#Automated-FTP-Uploads.
412
413Follow the instructions there to register your information so you're permitted
414to upload.
415
416Here's a brief reminder of how to roll the tarballs and upload them:
417
418### make distcheck
419### gpg -b bison-2.3b.tar.gz
420### In a file named `bison-2.3b.tar.gz.directive`, type:
421
422    version: 1.1
423    directory: bison
424    filename: bison-2.3b.tar.gz
425
426### gpg --clearsign bison-2.3b.tar.gz.directive
427### ftp ftp-upload.gnu.org # Log in as anonymous.
428### cd /incoming/alpha # cd /incoming/ftp for full release.
429### put bison-2.3b.tar.gz # This can take a while.
430### put bison-2.3b.tar.gz.sig
431### put bison-2.3b.tar.gz.directive.asc
432### Repeat all these steps for bison-2.3b.tar.xz.
433
434## Update Bison manual on www.gnu.org.
435
436The instructions below are obsolete, and left in case one would like to run
437the commands by hand.  Today, one just needs to run
438
439    $ make web-manual-update
440
441See README-release.
442
443### You need a non-anonymous checkout of the web pages directory.
444
445    $ cvs -d YOUR_USERID@cvs.savannah.gnu.org:/web/bison checkout bison
446
447### Get familiar with the instructions for web page maintainers.
448http://www.gnu.org/server/standards/readme_index.html
449http://www.gnu.org/server/standards/README.software.html
450especially the note about symlinks.
451
452### Build the web pages.
453Assuming BISON_CHECKOUT refers to a checkout of the Bison dir, and
454BISON_WWW_CHECKOUT refers to the web directory created above, do:
455
456    $ cd $BISON_CHECKOUT/doc
457    $ make stamp-vti
458    $ ../build-aux/gendocs.sh -o "$BISON_WWW_CHECKOUT/manual" \
459      bison "Bison - GNU parser generator"
460    $ cd $BISON_WWW_CHECKOUT
461
462Verify that the result looks sane.
463
464### Commit the modified and the new files.
465
466### Remove old files.
467Find the files which have not been overwritten (because they belonged to
468sections that have been removed or renamed):
469
470     $ cd manual/html_node
471     $ ls -lt
472
473Remove these files and commit their removal to CVS.  For each of these
474files, add a line to the file .symlinks.  This will ensure that hyperlinks
475to the removed files will redirect to the entire manual; this is better than
476a 404 error.
477
478## Announce
479The "make release" command just created a template,
480`$HOME/announce-bison-X.Y`.  Otherwise, to generate it, run:
481
482    make RELEASE_TYPE=alpha gpg_key_ID=F125BDF3 announcement
483
484where alpha can be replaced by `beta` or `table` and F125BDF3 should be
485replaced with your key ID.
486
487Complete/fix the announcement file.  The generated list of recipients
488(info-gnu@gnu.org, bison-announce@gnu.org, bug-bison@gnu.org,
489help-bison@gnu.org, bison-patches@gnu.org, and
490coordinator@translationproject.org) is appropriate for a stable release or a
491"serious beta".  For any other release, drop at least info-gnu@gnu.org.  For
492an example of how to fill out the rest of the template, search the mailing
493list archives for the most recent release announcement.
494
495For a stable release, send the same announcement on the comp.compilers
496newsgroup by sending email to compilers@iecc.com.  Do not make any Cc as the
497moderator will throw away anything cross-posted or Cc'ed.  It really needs
498to be a separate message.
499
500## Prepare NEWS
501So that developers don't accidentally add new items to the old NEWS entry,
502create a new empty entry in line 3 (without the two leading spaces):
503
504  * Noteworthy changes in release ?.? (????-??-??) [?]
505
506Push these changes.
507
508<!--
509
510Copyright (C) 2002-2005, 2007-2015, 2018-2020 Free Software Foundation,
511Inc.
512
513This file is part of GNU Bison.
514
515This program is free software: you can redistribute it and/or modify
516it under the terms of the GNU General Public License as published by
517the Free Software Foundation, either version 3 of the License, or
518(at your option) any later version.
519
520This program is distributed in the hope that it will be useful,
521but WITHOUT ANY WARRANTY; without even the implied warranty of
522MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
523GNU General Public License for more details.
524
525You should have received a copy of the GNU General Public License
526along with this program.  If not, see <http://www.gnu.org/licenses/>.
527
528Local Variables:
529mode: markdown
530fill-column: 76
531ispell-dictionary: "american"
532End:
533
534LocalWords:  Automake Autoconf Gettext Gzip Rsync Valgrind gnulib submodules
535LocalWords:  submodule init cd distcheck ChangeLog valgrind sigreturn sudo
536LocalWords:  UC gcc DGNULIB POSIXCHECK xml XSLT glr lalr README po runtime rc
537LocalWords:  gnupload gnupg gpg keyserver BDF ncftp filename clearsign cvs dir
538LocalWords:  symlinks vti html lt POSIX Cc'ed Graphviz Texinfo autoconf jN
539LocalWords:  automake autopoint graphviz texinfo PROG Wother parsers
540LocalWords:  TESTSUITEFLAGS deprec struct gnulib's getopt config ggdb
541LocalWords:  bitset fsanitize symlink CFLAGS MERCHANTABILITY ispell
542LocalWords:  american
543
544-->
545

README.md

1This package contains the GNU Bison parser generator.
2
3# Installation
4## Build from git
5Here are basic installation instructions for a repository checkout:
6
7    $ git submodule update --init
8    $ ./bootstrap
9
10then proceed with the usual `configure && make` steps.
11
12The file README-hacking.md is about building, modifying and checking Bison.
13
14## Build from tarball
15See the file INSTALL for generic compilation and installation instructions.
16
17Bison requires GNU m4 1.4.6 or later.  See
18https://ftp.gnu.org/gnu/m4/m4-1.4.6.tar.gz.
19
20## Colored diagnostics
21As an experimental feature, diagnostics are now colored, controlled by the
22`--color` and `--style` options.
23
24To use them, install the libtextstyle library before configuring Bison.  It
25is available from https://alpha.gnu.org/gnu/gettext/, for instance
26https://alpha.gnu.org/gnu/gettext/libtextstyle-0.8.tar.gz.
27
28The option --color supports the following arguments:
29- always, yes: Enable colors.
30- never, no: Disable colors.
31- auto, tty (default): Enable colors if the output device is a tty.
32
33To customize the styles, create a CSS file, say `bison-bw.css`, similar to
34
35    /* bison-bw.css */
36    .warning   { }
37    .error     { font-weight: 800; text-decoration: underline; }
38    .note      { }
39
40then invoke bison with `--style=bison-bw.css`, or set the `BISON_STYLE`
41environment variable to `bison-bw.css`.
42
43## Relocatability
44If you pass `--enable-relocatable` to `configure`, Bison is relocatable.
45
46A relocatable program can be moved or copied to a different location on the
47file system.  It can also be used through mount points for network sharing.
48It is possible to make symlinks to the installed and moved programs, and
49invoke them through the symlink.
50
51See "Enabling Relocatability" in the documentation.
52
53## Internationalization
54Bison supports two catalogs: one for Bison itself (i.e., for the
55maintainer-side parser generation), and one for the generated parsers (i.e.,
56for the user-side parser execution).  The requirements between both differ:
57bison needs ngettext, the generated parsers do not.  To simplify the build
58system, neither are installed if ngettext is not supported, even if
59generated parsers could have been localized.  See
60http://lists.gnu.org/archive/html/bug-bison/2009-08/msg00006.html for more
61details.
62
63# Questions
64See the section FAQ in the documentation (doc/bison.info) for frequently
65asked questions.  The documentation is also available in PDF and HTML,
66provided you have a recent version of Texinfo installed: run `make pdf` or
67`make html`.
68
69If you have questions about using Bison and the documentation does not
70answer them, please send mail to <help-bison@gnu.org>.
71
72# Bug reports
73Please send bug reports to <bug-bison@gnu.org>.  Be sure to include the
74version number from `bison --version`, and a complete, self-contained test
75case in each bug report.
76
77# Copyright statements
78For any copyright year range specified as YYYY-ZZZZ in this package, note
79that the range specifies every single year in that closed interval.
80
81<!--
82
83Copyright (C) 1992, 1998-1999, 2003-2005, 2008-2015, 2018-2020 Free
84Software Foundation, Inc.
85
86This file is part of GNU bison, the GNU Compiler Compiler.
87
88This program is free software: you can redistribute it and/or modify
89it under the terms of the GNU General Public License as published by
90the Free Software Foundation, either version 3 of the License, or
91(at your option) any later version.
92
93This program is distributed in the hope that it will be useful,
94but WITHOUT ANY WARRANTY; without even the implied warranty of
95MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
96GNU General Public License for more details.
97
98You should have received a copy of the GNU General Public License
99along with this program.  If not, see <http://www.gnu.org/licenses/>.
100
101Local Variables:
102mode: markdown
103fill-column: 76
104ispell-dictionary: "american"
105End:
106
107LocalWords:  parsers ngettext Texinfo pdf html YYYY ZZZZ ispell american
108LocalWords:  MERCHANTABILITY
109
110-->
111