From 3c47ed0fe6a96f5d975d3e2f7843dc989d021180 Mon Sep 17 00:00:00 2001 From: Kaz Kylheku Date: Tue, 13 Oct 2020 15:39:41 -0700 Subject: [PATCH] doc: document best deployment practices. * doc/bison.texi (Versioning): New node about practices regarding dealing with multiple versions of Bison. --- doc/bison.texi | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/doc/bison.texi b/doc/bison.texi index 0cb75060..ec2455c8 100644 --- a/doc/bison.texi +++ b/doc/bison.texi @@ -244,6 +244,7 @@ Reference sections: * Invocation:: How to run Bison (to produce the parser implementation). * Other Languages:: Creating C++ 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. @@ -540,6 +541,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 @@ -14675,6 +14680,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 +modifications. + +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 +output. + +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