mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-12-31 02:39:48 -06:00
Code Issues Packages Projects Releases Wiki Activity

FindBISON: Update documentation

Browse Source 
- Updated and synced module documentation with other similar find
  modules.
- Documented bison_target() command indented relative to the title.
- Command arguments described as a list separately.
- Used "command" instead of "macro".
- Used lowercase style across the docs.
- Extended examples section.
This commit is contained in:
Peter Kokot
2025-04-29 06:18:15 +02:00
parent d85041c830
commit e0c4e8ecf4
6 changed files with 163 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
Help/policy/CMP0088.rst
View File

@@ -6,8 +6,8 @@ CMP0088
:module:`FindBISON` runs bison in :variable:`CMAKE_CURRENT_BINARY_DIR`
when executing.
The module provides a ``BISON_TARGET`` macro which generates BISON output.
In CMake 3.13 and below the macro would generate a custom command that runs
The module provides a ``bison_target()`` command which generates BISON output.
In CMake 3.13 and below the command would generate a custom build rule that runs
``bison`` in the source directory. CMake 3.14 and later prefer to run it
in the build directory and use :variable:`CMAKE_CURRENT_BINARY_DIR` as the
``WORKING_DIRECTORY`` of its :command:`add_custom_command` invocation.
@@ -17,7 +17,7 @@ tree rather than the source.
This policy provides compatibility for projects that have not been updated
to expect the new behavior.
The ``OLD`` behavior for this policy is for ``BISON_TARGET`` to use
The ``OLD`` behavior for this policy is for ``bison_target()`` to use
the current source directory for the ``WORKING_DIRECTORY`` and where
to generate implicit files. The ``NEW`` behavior of this policy is to
use the current binary directory for the ``WORKING_DIRECTORY`` and where

2
Help/release/3.14.rst
View File

@@ -193,7 +193,7 @@ Modules
each one to the main build using the canonical pattern. This
significantly reduces the amount of boilerplate needed in a project.
* The :module:`FindBISON` module's ``BISON_TARGET`` command now runs ``bison``
* The :module:`FindBISON` module's ``bison_target()`` command now runs ``bison``
with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
See policy :policy:`CMP0088`.

2
Help/release/3.4.rst
View File

@@ -117,7 +117,7 @@ Modules
useful with the :generator:`Ninja` generator to monitor CMake
superbuild progress and prevent CPU oversubscription.
* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a
* The :module:`FindBISON` module ``bison_target()`` command learned a
new ``DEFINES_FILE`` option to specify a custom output header
to be generated.

2
Help/release/3.6.rst
View File

@@ -283,7 +283,7 @@ Other Changes
files in different directories use ``#include <moc_foo.cpp>`` with the
same name (because the generated ``moc_foo.cpp`` files would collide).
* The :module:`FindBISON` module ``BISON_TARGET`` macro now supports
* The :module:`FindBISON` module ``bison_target()`` command now supports
special characters by passing the ``VERBATIM`` option to internal
:command:`add_custom_command` calls. This may break clients that
added escaping manually to work around the bug.

2
Help/release/3.7.rst
View File

@@ -168,7 +168,7 @@ Modules
* The :module:`ExternalProject` module gained a ``HTTP_HEADER``
option to add http download headers.
* The :module:`FindBISON` module ``BISON_TARGET`` macro learned a new
* The :module:`FindBISON` module ``bison_target()`` command learned a new
``REPORT_FILE`` option to specify the bison ``--report-file=`` option.
* The :module:`FindBZip2` module now provides imported targets.

228
Modules/FindBISON.cmake
View File

@@ -5,120 +5,198 @@
FindBISON
---------
Find ``bison`` executable and provide a macro to generate custom build rules.
Finds the Bison command-line parser generator and provides a CMake command to
generate custom build rules for using Bison:
The module defines the following variables:
.. code-block:: cmake
find_package(BISON [<version>] ...)
Bison is a parser generator that replaced earlier Yacc (Yet Another
Compiler-Compiler). On Unix-like systems, most common implementation is
GNU Bison. On Windows, this module looks for Windows-compatible Bison, if
installed.
Result Variables
^^^^^^^^^^^^^^^^
This module defines the following variables:
``BISON_FOUND``
True if the program was found.
``BISON_EXECUTABLE``
The path to the ``bison`` program.
Boolean indicating whether (the requested version of) Bison is found.
``BISON_VERSION``
The version of ``bison``.
The version of Bison found.
The minimum required version of ``bison`` can be specified using the
standard CMake syntax, e.g. :command:`find_package(BISON 2.1.3)`.
Cache Variables
^^^^^^^^^^^^^^^
If ``bison`` is found, the module defines the macro:
The following cache variables may also be set:
``BISON_EXECUTABLE``
The path to the ``bison`` command-line program.
Commands
^^^^^^^^
This module provides the following command if ``bison`` is found:
.. command:: bison_target
Creates a custom build rule to generate a parser file from a Yacc file using
Bison:
.. code-block:: cmake
bison_target(<Name> <YaccInput> <CodeOutput>
[OPTIONS <options>...]
[COMPILE_FLAGS <string>]
[DEFINES_FILE <file>]
[VERBOSE [<file>]]
[REPORT_FILE <file>]
)
bison_target(
<name>
<input-yacc-file>
<output-parser-file>
[DEFINES_FILE <header>]
[VERBOSE [<file>]] # The [<file>] argument is deprecated
[REPORT_FILE <file>]
[OPTIONS <options>...]
[COMPILE_FLAGS <string>] # Deprecated
)
which will create a custom rule to generate a parser. ``<YaccInput>`` is
the path to a yacc file. ``<CodeOutput>`` is the name of the source file
generated by bison. A header file can also be generated, and contains
the token list.
.. versionchanged:: 3.14
When policy :policy:`CMP0088` is set to ``NEW``, ``bison`` runs in the
:variable:`CMAKE_CURRENT_BINARY_DIR` directory.
.. versionchanged:: 3.14
When :policy:`CMP0088` is set to ``NEW``, ``bison`` runs in the
:variable:`CMAKE_CURRENT_BINARY_DIR` directory.
``<name>``
String used as an identifier for this command invocation.
The options are:
``<input-yacc-file>``
The path to an input Yacc source file (``.y``). If given as a relative
path, it will be interpreted relative to the current source directory
(:variable:`CMAKE_CURRENT_SOURCE_DIR`).
``OPTIONS <options>...``
.. versionadded:: 4.0
``<output-parser-file>``
The path of the output parser file to be generated by Bison. If given as a
relative path, it will be interpreted relative to the current Bison working
directory.
A :ref:`semicolon-separated list <CMake Language Lists>` of options added to
the ``bison`` command line.
``DEFINES_FILE <header>``
.. versionadded:: 3.4
``COMPILE_FLAGS <string>``
.. deprecated:: 4.0
By default, Bison can generate a header file containing the list of tokens.
This option allows specifying a custom ``<header>`` file to be generated by
Bison. If given as a relative path, it will be interpreted relative to the
current Bison working directory.
Space-separated bison options added to the ``bison`` command line.
A :ref:`;-list <CMake Language Lists>` will not work.
This option is deprecated in favor of ``OPTIONS <options>...``.
``VERBOSE [<file>]``
Enables generation of a verbose grammar and parser report. By default, the
report file is created in the current Bison working directory and named
``<output-parser-filename>.output``.
``DEFINES_FILE <file>``
.. versionadded:: 3.4
``<file>``
.. deprecated:: 3.7
Use ``VERBOSE REPORT_FILE <file>``.
Specify a non-default header ``<file>`` to be generated by ``bison``.
Specifies the path to which the report file should be copied. This
argument is retained for backward compatibility and only works when the
``<output-parser-file>`` is specified as an absolute path.
``VERBOSE [<file>]``
Tell ``bison`` to write a report file of the grammar and parser.
``REPORT_FILE <file>``
.. versionadded:: 3.7
.. deprecated:: 3.7
If ``<file>`` is given, it specifies path the report file is copied to.
``[<file>]`` is left for backward compatibility of this module.
Use ``VERBOSE REPORT_FILE <file>``.
Used in combination with ``VERBOSE`` to specify a custom path for the report
output ``<file>``, overriding the default location. If given as a relative
path, it will be interpreted relative to the current Bison working
directory.
``REPORT_FILE <file>``
.. versionadded:: 3.7
``OPTIONS <options>...``
.. versionadded:: 4.0
Specify a non-default report ``<file>``, if generated.
A :ref:`semicolon-separated list <CMake Language Lists>` of extra options
added to the ``bison`` command line.
The macro defines the following variables:
``COMPILE_FLAGS <string>``
.. deprecated:: 4.0
Superseded by ``OPTIONS <options>...``.
``BISON_<Name>_DEFINED``
True if the macro ran successfully.
A string of space-separated extra options added to the ``bison`` command
line. A :ref:`semicolon-separated list <CMake Language Lists>` will not
work.
``BISON_<Name>_INPUT``
The input source file, an alias for ``<YaccInput>``.
---------------------------------------------------------------------
``BISON_<Name>_OUTPUT_SOURCE``
The source file generated by ``bison``.
This command also defines the following variables:
``BISON_<Name>_OUTPUT_HEADER``
The header file generated by ``bison``.
``BISON_<name>_DEFINED``
Boolean indicating whether this command was successfully invoked.
``BISON_<Name>_OUTPUTS``
All files generated by ``bison`` including the source, the header and the
report.
``BISON_<name>_INPUT``
The input source file, an alias for ``<input-yacc-file>``.
``BISON_<Name>_OPTIONS``
.. versionadded:: 4.0
``BISON_<name>_OUTPUT_SOURCE``
The output parser file generated by ``bison``.
Options used in the ``bison`` command line.
``BISON_<name>_OUTPUT_HEADER``
The header file generated by ``bison``, if any.
``BISON_<Name>_COMPILE_FLAGS``
.. deprecated:: 4.0
``BISON_<name>_OUTPUTS``
A list of files generated by ``bison``, including the output parser file,
header file, and report file.
Options used in the ``bison`` command line. This variable is deprecated in
favor of ``BISON_<Name>_OPTIONS`` variable.
``BISON_<name>_OPTIONS``
.. versionadded:: 4.0
A list of command-line options used for the ``bison`` command.
``BISON_<name>_COMPILE_FLAGS``
.. deprecated:: 4.0
Superseded by ``BISON_<name>_OPTIONS`` variable with the same value.
A list of command-line options used for the ``bison`` command.
Examples
^^^^^^^^
Examples: Finding Bison
"""""""""""""""""""""""
Finding Bison:
.. code-block:: cmake
find_package(BISON)
bison_target(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp
DEFINES_FILE ${CMAKE_CURRENT_BINARY_DIR}/parser.h)
Finding Bison with a minimum required version:
.. code-block:: cmake
find_package(BISON 2.1.3)
Finding Bison and making it required (if Bison is not found, processing stops
with an error message):
.. code-block:: cmake
find_package(BISON 2.1.3 REQUIRED)
Example: Generating Parser
""""""""""""""""""""""""""
Finding Bison and adding input Yacc source file ``parser.y`` to be processed by
Bison into ``parser.cpp`` source file with header ``parser.h`` at build phase:
.. code-block:: cmake
find_package(BISON)
if(BISON_FOUND)
bison_target(MyParser parser.y parser.cpp DEFINES_FILE parser.h)
endif()
add_executable(Foo main.cpp ${BISON_MyParser_OUTPUTS})
Examples: Command-line Options
""""""""""""""""""""""""""""""
Adding additional command-line options to the ``bison`` executable can be passed
as a list. For example, adding the ``-Wall`` option to report all warnings, and
``--no-lines`` (``-l``) to not generate ``#line`` directives.
as a list. For example, adding the ``-Wall`` option to report all warnings, and
``--no-lines`` (``-l``) to not generate ``#line`` directives:
.. code-block:: cmake
@@ -128,8 +206,9 @@ as a list. For example, adding the ``-Wall`` option to report all warnings, and
bison_target(MyParser parser.y parser.cpp OPTIONS -Wall --no-lines)
endif()
Generator expressions can be used in ``OPTIONS <options...``. For example, to
add the ``--debug`` (``-t``) option only for the ``Debug`` build type:
:manual:`Generator expressions <cmake-generator-expressions(7)>` can be used in
the ``OPTIONS <options>...`` argument. For example, to add the ``--debug``
(``-t``) option only for the ``Debug`` build type:
.. code-block:: cmake
@@ -138,6 +217,11 @@ add the ``--debug`` (``-t``) option only for the ``Debug`` build type:
if(BISON_FOUND)
bison_target(MyParser parser.y parser.cpp OPTIONS $<$<CONFIG:Debug>:-t>)
endif()
See Also
^^^^^^^^
* The :module:`FindFLEX` module to find Flex scanner generator.
#]=======================================================================]
find_program(BISON_EXECUTABLE NAMES bison win-bison win_bison DOC "path to the bison executable")
@@ -261,7 +345,7 @@ if(BISON_EXECUTABLE)
endmacro()
#============================================================
# BISON_TARGET (public macro)
# bison_target() public macro
#============================================================
#
macro(BISON_TARGET Name BisonInput BisonOutput)