diff --git a/Help/policy/CMP0088.rst b/Help/policy/CMP0088.rst index 845849dfed..886796f758 100644 --- a/Help/policy/CMP0088.rst +++ b/Help/policy/CMP0088.rst @@ -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 diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst index f46a417d59..6b3a187480 100644 --- a/Help/release/3.14.rst +++ b/Help/release/3.14.rst @@ -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`. diff --git a/Help/release/3.4.rst b/Help/release/3.4.rst index abfede6ca3..e17e6ad515 100644 --- a/Help/release/3.4.rst +++ b/Help/release/3.4.rst @@ -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. diff --git a/Help/release/3.6.rst b/Help/release/3.6.rst index 92b101253c..e12c392ade 100644 --- a/Help/release/3.6.rst +++ b/Help/release/3.6.rst @@ -283,7 +283,7 @@ Other Changes files in different directories use ``#include `` 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. diff --git a/Help/release/3.7.rst b/Help/release/3.7.rst index 9656a546b4..ceac100b2b 100644 --- a/Help/release/3.7.rst +++ b/Help/release/3.7.rst @@ -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. diff --git a/Modules/FindBISON.cmake b/Modules/FindBISON.cmake index cbda5cd87a..644f5904a0 100644 --- a/Modules/FindBISON.cmake +++ b/Modules/FindBISON.cmake @@ -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 [] ...) + +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( - [OPTIONS ...] - [COMPILE_FLAGS ] - [DEFINES_FILE ] - [VERBOSE []] - [REPORT_FILE ] - ) + bison_target( + + + + [DEFINES_FILE
] + [VERBOSE []] # The [] argument is deprecated + [REPORT_FILE ] + [OPTIONS ...] + [COMPILE_FLAGS ] # Deprecated + ) -which will create a custom rule to generate a parser. ```` is -the path to a yacc file. ```` 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. + ```` + String used as an identifier for this command invocation. -The options are: + ```` + 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 ...`` - .. versionadded:: 4.0 + ```` + 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 ` of options added to - the ``bison`` command line. + ``DEFINES_FILE
`` + .. versionadded:: 3.4 -``COMPILE_FLAGS `` - .. deprecated:: 4.0 + By default, Bison can generate a header file containing the list of tokens. + This option allows specifying a custom ``
`` 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 ` will not work. - This option is deprecated in favor of ``OPTIONS ...``. + ``VERBOSE []`` + 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``. -``DEFINES_FILE `` - .. versionadded:: 3.4 + ```` + .. deprecated:: 3.7 + Use ``VERBOSE REPORT_FILE ``. - Specify a non-default header ```` 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 + ```` is specified as an absolute path. -``VERBOSE []`` - Tell ``bison`` to write a report file of the grammar and parser. + ``REPORT_FILE `` + .. versionadded:: 3.7 - .. deprecated:: 3.7 - If ```` is given, it specifies path the report file is copied to. - ``[]`` is left for backward compatibility of this module. - Use ``VERBOSE REPORT_FILE ``. + Used in combination with ``VERBOSE`` to specify a custom path for the report + output ````, overriding the default location. If given as a relative + path, it will be interpreted relative to the current Bison working + directory. -``REPORT_FILE `` - .. versionadded:: 3.7 + ``OPTIONS ...`` + .. versionadded:: 4.0 - Specify a non-default report ````, if generated. + A :ref:`semicolon-separated list ` of extra options + added to the ``bison`` command line. -The macro defines the following variables: + ``COMPILE_FLAGS `` + .. deprecated:: 4.0 + Superseded by ``OPTIONS ...``. -``BISON__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 ` will not + work. -``BISON__INPUT`` - The input source file, an alias for ````. + --------------------------------------------------------------------- -``BISON__OUTPUT_SOURCE`` - The source file generated by ``bison``. + This command also defines the following variables: -``BISON__OUTPUT_HEADER`` - The header file generated by ``bison``. + ``BISON__DEFINED`` + Boolean indicating whether this command was successfully invoked. -``BISON__OUTPUTS`` - All files generated by ``bison`` including the source, the header and the - report. + ``BISON__INPUT`` + The input source file, an alias for ````. -``BISON__OPTIONS`` - .. versionadded:: 4.0 + ``BISON__OUTPUT_SOURCE`` + The output parser file generated by ``bison``. - Options used in the ``bison`` command line. + ``BISON__OUTPUT_HEADER`` + The header file generated by ``bison``, if any. -``BISON__COMPILE_FLAGS`` - .. deprecated:: 4.0 + ``BISON__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__OPTIONS`` variable. + ``BISON__OPTIONS`` + .. versionadded:: 4.0 + + A list of command-line options used for the ``bison`` command. + + ``BISON__COMPILE_FLAGS`` + .. deprecated:: 4.0 + Superseded by ``BISON__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 ` can be used in +the ``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 $<$:-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)