README

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