FindFLEX: Update documentation

- Updated and synced module documentation with other similar find
  modules.
- Used lowercase style for commands across the docs.
- Commands documented with indentation.
- Command arguments described as a list separately.
- Used "commands" instead of "macros".
- Extended examples section.
- Added example showing how to use found Flex library by creating an
  imported target inside a project. Fixes: #18718

Help/policy/CMP0098.rst

@@ -6,8 +6,8 @@ CMP0098
 :module:`FindFLEX` runs ``flex`` in directory
 :variable:`CMAKE_CURRENT_BINARY_DIR` when executing.
 
-The module provides a ``FLEX_TARGET`` macro which generates FLEX output.
-In CMake 3.16 and below the macro would generate a custom command that runs
+The module provides a ``flex_target()`` command which generates FLEX output.
+In CMake 3.16 and below the command would generate a custom build rule that runs
 ``flex`` in the current source directory.  CMake 3.17 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.
@@ -18,7 +18,7 @@ provided as absolute path.
 This policy provides compatibility for projects that have not been updated
 to expect the new behavior.
 
-The ``OLD`` behavior for this policy is for ``FLEX_TARGET`` to use
+The ``OLD`` behavior for this policy is for ``flex_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`` relative to

Help/release/3.17.rst

@@ -170,7 +170,7 @@ Modules
   CURL's cmake buildsystem.  It also gained a new ``CURL_NO_CURL_CMAKE``
   option to disable this behavior.
 
-* The :module:`FindFLEX` module's ``FLEX_TARGET`` command now runs ``flex``
+* The :module:`FindFLEX` module's ``flex_target()`` command now runs ``flex``
   with :variable:`CMAKE_CURRENT_BINARY_DIR` as the working directory.
   See policy :policy:`CMP0098`.
 

Help/release/3.5.rst

@@ -73,7 +73,7 @@ Modules
 * The :module:`FindBoost` module now provides imported targets
   such as ``Boost::boost`` and ``Boost::filesystem``.
 
-* The :module:`FindFLEX` module ``FLEX_TARGET`` macro learned a
+* The :module:`FindFLEX` module ``flex_target()`` command learned a
   new ``DEFINES_FILE`` option to specify a custom output header
   to be generated.
 

Help/release/3.6.rst

@@ -288,7 +288,7 @@ Other Changes
   :command:`add_custom_command` calls.  This may break clients that
   added escaping manually to work around the bug.
 
-* The :module:`FindFLEX` module ``FLEX_TARGET`` macro now supports
+* The :module:`FindFLEX` module ``flex_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.

Modules/FindFLEX.cmake

@@ -5,126 +5,194 @@
 FindFLEX
 --------
 
-Find Fast Lexical Analyzer (Flex) executable and provide a macro
-to generate custom build rules.
+Finds the Fast Lexical Analyzer (Flex) command-line generator and its library,
+and provides CMake commands to create custom build rules for using Flex:
 
-The module defines the following variables:
+.. code-block:: cmake
 
-``FLEX_FOUND``
-  True if ``flex`` executable is found.
+  find_package(FLEX [<version>] ...)
 
-``FLEX_EXECUTABLE``
-  The path to the ``flex`` executable.
+Flex generates lexical analyzers, also known as *scanners* or *lexers*.  It also
+includes a runtime library (``fl``) that supplies support functions for the
+generated scanners, such as input handling, buffer management, and error
+reporting.
+
+Result Variables
+^^^^^^^^^^^^^^^^
+
+This module defines the following variables:
+
+``FLEX_FOUND``
+  Boolean indicating whether (the requested version of) Flex is found.
 
 ``FLEX_VERSION``
-  The version of ``flex``.
+  The version of Flex found.
+
+``FLEX_INCLUDE_DIRS``
+  The include directories containing headers for using Flex library.
 
 ``FLEX_LIBRARIES``
-  The ``flex`` libraries.
+  The libraries needed to link against to use Flex library.
 
-``FLEX_INCLUDE_DIRS``
-  The path to the ``flex`` headers.
+Cache Variables
+^^^^^^^^^^^^^^^
 
-The minimum required version of ``flex`` can be specified using the
-standard CMake syntax, e.g. :command:`find_package(FLEX 2.5.13)`.
+The following cache variables may also be set:
 
-If ``flex`` is found on the system, the module defines the macro:
+``FLEX_EXECUTABLE``
+  The path to the ``flex`` executable.
+
+Commands
+^^^^^^^^
+
+This module provides the following commands if ``flex`` is found:
+
+Generating Scanners
+"""""""""""""""""""
 
 .. command:: flex_target
 
+  Creates a custom build rule to generate a scanner file from a lex file using
+  Flex:
+
   .. code-block:: cmake
 
-    flex_target(<Name> <FlexInput> <FlexOutput>
-                [OPTIONS <options>...]
-                [COMPILE_FLAGS <string>]
-                [DEFINES_FILE <string>]
-                )
+    flex_target(
+      <name>
+      <input-lex-file>
+      <output-scanner-file>
+      [DEFINES_FILE <header>]
+      [OPTIONS <options>...]
+      [COMPILE_FLAGS <string>] # Deprecated
+    )
+
+  .. versionchanged:: 3.17
+    When policy :policy:`CMP0098` is set to ``NEW``, ``flex`` runs in the
+    :variable:`CMAKE_CURRENT_BINARY_DIR` directory.
+
+  ``<name>``
+    String used as an identifier for this command invocation.
 
-which creates a custom command to generate the ``<FlexOutput>`` file from
-the ``<FlexInput>`` file.  ``<Name>`` is an alias used to get details of this
-custom command.
+  ``<input-lex-file>``
+    The path to an input Flex source file (``.l``).  If given as a relative
+    path, it will be interpreted relative to the current source directory
+    (:variable:`CMAKE_CURRENT_SOURCE_DIR`).
 
-The options are:
+  ``<output-scanner-file>``
+    The path of the output file to be generated by Flex.  If given as a relative
+    path, it will be interpreted relative to the current Flex working directory.
 
-``OPTIONS <options>...``
-  .. versionadded:: 4.0
+  ``DEFINES_FILE <header>``
+    .. versionadded:: 3.5
 
-  A :ref:`semicolon-separated list <CMake Language Lists>` of flex options added
-  to the ``flex`` command line.
+    If Flex is configured to output a header file, this option may be used to
+    specify its name.  If given as a relative path, it will be interpreted
+    relative to the current Flex working directory.
 
-``COMPILE_FLAGS <string>``
-  .. deprecated:: 4.0
+  ``OPTIONS <options>...``
+    .. versionadded:: 4.0
 
-  Space-separated flex options added to the ``flex`` command line.
-  A :ref:`;-list <CMake Language Lists>` will not work.
-  This option is deprecated in favor of ``OPTIONS <options>...``.
+    A :ref:`semicolon-separated list <CMake Language Lists>` of extra options
+    added to the ``flex`` command line.
 
-``DEFINES_FILE <string>``
-  .. versionadded:: 3.5
+  ``COMPILE_FLAGS <string>``
+    .. deprecated:: 4.0
+      Superseded by ``OPTIONS <options>...``.
 
-  If flex is configured to output a header file, this option may be used to
-  specify its name.
+    A string of space-separated extra options added to the ``flex`` command
+    line. A :ref:`semicolon-separated list <CMake Language Lists>` will not
+    work.
 
-.. versionchanged:: 3.17
-  When :policy:`CMP0098` is set to ``NEW``, ``flex`` runs in the
-  :variable:`CMAKE_CURRENT_BINARY_DIR` directory.
+  ---------------------------------------------------------------------
 
-The macro defines the following variables:
+  This command also defines the following variables:
 
-``FLEX_<Name>_DEFINED``
-  True if the macro ran successfully.
+  ``FLEX_<name>_DEFINED``
+    Boolean indicating whether this command was successfully invoked.
 
-``FLEX_<Name>_OUTPUTS``
-  The source file generated by the custom rule, an alias for ``<FlexOutput>``.
+  ``FLEX_<name>_INPUT``
+    The Flex source file, an alias for ``<input-lex-file>``.
 
-``FLEX_<Name>_INPUT``
-  The flex source file, an alias for ``<FlexInput>``.
+  ``FLEX_<name>_OUTPUT_HEADER``
+    .. versionadded:: 3.5
 
-``FLEX_<Name>_OUTPUT_HEADER``
-  The header flex output, if any.
+    The header file generated by ``flex``, if any.
 
-``FLEX_<Name>_OPTIONS``
-  .. versionadded:: 4.0
+  ``FLEX_<name>_OUTPUTS``
+    A list of files generated by ``flex``, including the output scanner file,
+    and the header file.
 
-  Options used in the ``flex`` command line.
+  ``FLEX_<name>_OPTIONS``
+    .. versionadded:: 4.0
 
-Flex scanners often use tokens defined by Bison: the code generated
-by Flex depends of the header generated by Bison.  This module also
-defines a macro:
+    A list of command-line options used for the ``flex`` command.
+
+Adding Dependency Between Scanner and Parser
+""""""""""""""""""""""""""""""""""""""""""""
 
 .. command:: add_flex_bison_dependency
 
+  Adds the required dependency between a scanner and a parser:
+
   .. code-block:: cmake
 
-    add_flex_bison_dependency(<FlexTarget> <BisonTarget>)
+    add_flex_bison_dependency(<flex-name> <bison-name>)
 
-which adds the required dependency between a scanner and a parser
-where ``<FlexTarget>`` and ``<BisonTarget>`` are the first parameters of
-respectively ``flex_target`` and ``bison_target`` macros.
+  Flex scanners often rely on token definitions generated by Bison, meaning the
+  code produced by Flex depends on the header file created by Bison.
+
+  This command adds the required dependency between a scanner and a parser
+  where ``<flex-name>`` and ``<bison-name>`` are the first parameters of
+  respectively ``flex_target(<name> ...)`` and
+  :command:`bison_target(<name> ...)` commands.
 
 Examples
 ^^^^^^^^
 
+Examples: Finding Flex
+""""""""""""""""""""""
+
+Finding Flex:
+
 .. code-block:: cmake
 
-  find_package(BISON)
   find_package(FLEX)
 
-  bison_target(MyParser parser.y ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
-  flex_target(MyScanner lexer.l  ${CMAKE_CURRENT_BINARY_DIR}/lexer.cpp)
-  add_flex_bison_dependency(MyScanner MyParser)
+Finding Flex and specifying its minimum required version:
 
-  include_directories(${CMAKE_CURRENT_BINARY_DIR})
-  add_executable(Foo
-    Foo.cc
-    ${BISON_MyParser_OUTPUTS}
-    ${FLEX_MyScanner_OUTPUTS}
-  )
-  target_link_libraries(Foo ${FLEX_LIBRARIES})
+.. code-block:: cmake
+
+  find_package(FLEX 2.5.13)
+
+Finding Flex and making it required (if Flex is not found, processing stops
+with an error message):
+
+.. code-block:: cmake
+
+  find_package(FLEX 2.5.13 REQUIRED)
+
+Example: Generating Scanner
+"""""""""""""""""""""""""""
+
+Finding Flex and generating scanner source file in the current binary directory
+from the lex source file in the current source directory:
+
+.. code-block:: cmake
+
+  find_package(FLEX)
+
+  if(FLEX_FOUND)
+    flex_target(MyScanner lexer.l lexer.cpp)
+  endif()
+
+  add_executable(foo foo.cc ${FLEX_MyScanner_OUTPUTS})
+
+Example: Command-line Options
+"""""""""""""""""""""""""""""
 
 Adding additional command-line options to the ``flex`` executable can be passed
-as a list. For example, adding the ``--warn`` option to report warnings, and the
-``--noline`` (``-L``) to not generate ``#line`` directives.
+as a list.  For example, adding the ``--warn`` option to report warnings, and
+the ``--noline`` (``-L``) to not generate ``#line`` directives.
 
 .. code-block:: cmake
 
@@ -134,8 +202,9 @@ as a list. For example, adding the ``--warn`` option to report warnings, and the
     flex_target(MyScanner lexer.l lexer.cpp OPTIONS --warn --noline)
   endif()
 
-Generator expressions can be used in ``OPTIONS <options...``. For example, to
-add the ``--debug`` (``-d``) 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``
+(``-d``) option only for the ``Debug`` build type:
 
 .. code-block:: cmake
 
@@ -144,6 +213,60 @@ add the ``--debug`` (``-d``) option only for the ``Debug`` build type:
   if(FLEX_FOUND)
     flex_target(MyScanner lexer.l lexer.cpp OPTIONS $<$<CONFIG:Debug>:--debug>)
   endif()
+
+Example: Using Flex Library
+"""""""""""""""""""""""""""
+
+Finding Flex and creating an interface :ref:`imported target <Imported Targets>`
+that encapsulates its library usage requirements for linking to a project
+target:
+
+.. code-block:: cmake
+
+  find_package(FLEX)
+
+  if(FLEX_FOUND AND NOT TARGET FLEX::fl)
+    add_library(FLEX::fl INTERFACE IMPORTED)
+    set_target_properties(
+      FLEX::fl
+      PROPERTIES
+        INTERFACE_INCLUDE_DIRECTORIES "${FLEX_INCLUDE_DIRS}"
+        INTERFACE_LINK_LIBRARIES "${FLEX_LIBRARIES}"
+    )
+  endif()
+
+  if(FLEX_FOUND)
+    flex_target(MyScanner lexer.l lexer.cpp)
+  endif()
+
+  add_executable(Foo foo.cc ${FLEX_MyScanner_OUTPUTS})
+  target_link_libraries(Foo PRIVATE FLEX::fl)
+
+Example: Using Flex and Bison
+"""""""""""""""""""""""""""""
+
+The following example demonstrates, how to use Flex and :module:`Bison
+<FindBISON>` in CMake:
+
+.. code-block:: cmake
+
+  find_package(BISON)
+  find_package(FLEX)
+
+  if(BISON_FOUND AND FLEX_FOUND)
+    bison_target(MyParser parser.y parser.cpp)
+    flex_target(MyScanner lexer.l lexer.cpp)
+    add_flex_bison_dependency(MyScanner MyParser)
+  endif()
+
+  add_executable(Foo foo.cc ${BISON_MyParser_OUTPUTS} ${FLEX_MyScanner_OUTPUTS})
+
+  # ...
+
+See Also
+^^^^^^^^
+
+* The :module:`FindBISON` module to find Bison parser generator.
 #]=======================================================================]
 
 find_program(FLEX_EXECUTABLE NAMES flex win-flex win_flex DOC "path to the flex executable")
@@ -185,7 +308,7 @@ if(FLEX_EXECUTABLE)
   endif()
 
   #============================================================
-  # FLEX_TARGET (public macro)
+  # flex_target() public macro
   #============================================================
   #
   macro(FLEX_TARGET Name Input Output)
@@ -209,12 +332,12 @@ if(FLEX_EXECUTABLE)
       JOIN "\n" FLEX_TARGET_usage
       "Usage:"
       "  flex_target("
-      "    <Name>"
-      "    <Input>"
-      "    <Output>"
+      "    <name>"
+      "    <input-lex-file>"
+      "    <output-scanner-file>"
+      "    [DEFINES_FILE <header>]"
       "    [OPTIONS <options>...]"
       "    [COMPILE_FLAGS <string>]"
-      "    [DEFINES_FILE <string>]"
       "  )"
     )
 
@@ -319,7 +442,7 @@ if(FLEX_EXECUTABLE)
 
 
   #============================================================
-  # ADD_FLEX_BISON_DEPENDENCY (public macro)
+  # add_flex_bison_dependency() public macro
   #============================================================
   #
   macro(ADD_FLEX_BISON_DEPENDENCY FlexTarget BisonTarget)