# FindBISON

Finds the Bison command-line parser generator and provides a CMake command to generate custom build rules for using Bison:

    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`

  Boolean indicating whether (the requested version of) Bison was found.

`BISON_VERSION`

  The version of Bison found.

## Cache Variables

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:

bison_target

  Creates a custom build rule to generate a parser file from a Yacc file using Bison:

      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
      )

  Changed in version 3.14: When policy `CMP0088` is set to `NEW`, `bison` runs in the `CMAKE_CURRENT_BINARY_DIR` directory.

  `<name>`

    String used as an identifier for this command invocation.

  `<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 (`CMAKE_CURRENT_SOURCE_DIR`).

  `<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.

  `DEFINES_FILE <header>`

    Added in version 3.4.

    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.

  `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`.

    `<file>`

      Deprecated since version 3.7: Use `VERBOSE REPORT_FILE <file>`.

      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.

  `REPORT_FILE <file>`

    Added in version 3.7.

    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.

  `OPTIONS <options>...`

    Added in version 4.0.

    A semicolon-separated list of extra options added to the `bison` command line.

  `COMPILE_FLAGS <string>`

    Deprecated since version 4.0: Superseded by `OPTIONS <options>...`.

    A string of space-separated extra options added to the `bison` command line. A semicolon-separated list will not work.

  Command variables

  This command also defines the following variables:

  `BISON_<name>_DEFINED`

    Boolean indicating whether this command was successfully invoked.

  `BISON_<name>_INPUT`

    The input source file, an alias for `<input-yacc-file>`.

  `BISON_<name>_OUTPUT_SOURCE`

    The output parser file generated by `bison`.

  `BISON_<name>_OUTPUT_HEADER`

    The header file generated by `bison`, if any.

  `BISON_<name>_OUTPUTS`

    A list of files generated by `bison`, including the output parser file, header file, and report file.

  `BISON_<name>_OPTIONS`

    Added in version 4.0.

    A list of command-line options used for the `bison` command.

  `BISON_<name>_COMPILE_FLAGS`

    Deprecated since version 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:

    find_package(BISON)

Finding Bison with a minimum required version:

    find_package(BISON 2.1.3)

Finding Bison and making it required (if Bison is not found, processing stops with an error message):

    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:

    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:

    find_package(BISON)

    if(BISON_FOUND)
      bison_target(MyParser parser.y parser.cpp OPTIONS -Wall --no-lines)
    endif()

`Generator expressions` can be used in the `OPTIONS <options>...` argument. For example, to add the `--debug` (`-t`) option only for the `Debug` build type:

    find_package(BISON)

    if(BISON_FOUND)
      bison_target(MyParser parser.y parser.cpp OPTIONS $<$<CONFIG:Debug>:-t>)
    endif()

## See Also

- The `FindFLEX` module to find Flex scanner generator.