[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH]: Suggested documentation about working with Bison versions.

From: Kaz Kylheku
Subject: Re: [PATCH]: Suggested documentation about working with Bison versions.
Date: Wed, 14 Oct 2020 17:27:19 -0700
User-agent: Roundcube Webmail/0.9.2

New version of the patch:

commit 6e1905b617dd8fac3161864b6787b0042ec7cd4a
Author: Kaz Kylheku <>
Date:   Tue Oct 13 15:39:41 2020 -0700

    doc: document best deployment practices.

    * doc/bison.texi (Versioning): New node about practices
    regarding dealing with multiple versions of Bison.

diff --git a/doc/bison.texi b/doc/bison.texi
index 67494d35..f280277e 100644
--- a/doc/bison.texi
+++ b/doc/bison.texi
@@ -244,6 +244,7 @@ Cover art by Etienne Suvasa.
* Invocation:: How to run Bison (to produce the parser implementation).
 * Other Languages::     Creating C++, D and Java parsers.
 * History::             How Bison came to be
+* Versioning::          Dealing with Bison versioning
 * FAQ::                 Frequently Asked Questions
* Table of Symbols:: All the keywords of the Bison language are explained.
 * Glossary::            Basic concepts are explained.
@@ -550,6 +551,10 @@ A Brief History of the Greater Ungulates
 * Bison::                       This program
 * Other Ungulates::             Similar programs

+Bison Version Compatibility
+* Versioning::                  Dealing with Bison versioning
 Frequently Asked Questions

 * Memory Exhausted::            Breaking the Stack Limits
@@ -14918,6 +14923,67 @@ still in use is David Beazley's ``PLY'' (Python Lex-Yacc) for
 Python. Another is goyacc, supporting the Go language. An ``ocamlyacc''
 is shipped as part of the Ocaml compiler suite.

+@c ================================================= Version Compatibility
+@node Versioning
+@chapter Bison Version Compatibility: Best Practices
+@cindex version
+@cindex compatibility
+Bison provides a Yacc compatibility mode in which it strives to conform with +the POSIX standard. Grammar files which are written to the POSIX standard, and +do not take advantage of any of the special capabilities of Bison, should
+work with many version of Bison without modification.
+All other features of Bison are particular to Bison, and are changing. Bison
+is actively maintained and continuously evolving.  It should come as no
+surprise that an older version of Bison will not accept Bison source code which
+uses newer features that do no not exist at all in the older Bison.
+Regrettably, in spite of reasonable effort to maintain compatibility, the +reverse situation may also occur: it may happen that code developed using an +older version of Bison does not build with a newer version of Bison without
+Because Bison is a code generation tool, it is possible to retain its output +and distribute that to the users of the program. The users are then not
+required to have Bison installed at all, only an implementation of the
+programming language, such as C, which is required for processing the generated
+It is the output of Bison that is intended to be of the utmost portability. +So, that is to say, whereas the Bison grammar source code may have a dependency +on specific versions of Bison, the generated parser from any version of Bison +should work with with a large number of implementations of C, or whatever
+language is applicable.
+The recommended best practice for using Bison (in the context of software that +is distributed in source code form) is to ship the generated parser to the +downstream users. Only those downstream users who engage in active development +of the program who need to make changes to the grammar file need to have Bison +installed at all, and those users can install the specific version of Bison
+which is required.
+Following this recommended practice also makes it possible to use a more recent +Bison than what is available to users through operating system distributions,
+thereby taking advantage of the latest techniques that Bison allows.
+Some features of Bison have been, or are being adopted into other Yacc-like +programs. Therefore it might seem that is a good idea to write grammar code +which targets multiple implementations, similarly to the way C programs are +often written to target multiple compilers and language versions. Other than +the Yacc subset described by POSIX, the Bison language is not rigorously +standardized. When a Bison feature is adopted by another parser generator, it +may be initially compatible with that version of Bison on which it was based, +but the compatibility may degrade going forward. Developers who strive to make +their Bison code simultaneously compatible with other parser generators are +encouraged to nevertheless use specific versions of all generators, and still +follow the recommended practice of shipping generated output. For example, +a project can internally maintain compatibility with multiple generators, +and choose the output of a particular one to ship to the users. Or else, +the project could ship all of the outputs, arranging for a way for the user
+to specify which one is used to build the program.
 @c ================================================= FAQ

 @node FAQ

reply via email to

[Prev in Thread] Current Thread [Next in Thread]