code:
file
----

File manipulation command.

This command is dedicated to file and path manipulation requiring access to the
filesystem.

For other path manipulation, handling only syntactic aspects, have a look at
:command:`cmake_path` command.

.. note::

  The sub-commands `RELATIVE_PATH`_, `TO_CMAKE_PATH`_ and `TO_NATIVE_PATH`_ has
  been superseded, respectively, by sub-commands
  :ref:`RELATIVE_PATH <cmake_path-RELATIVE_PATH>`,
  :ref:`CONVERT ... TO_CMAKE_PATH_LIST <cmake_path-TO_CMAKE_PATH_LIST>` and
  :ref:`CONVERT ... TO_NATIVE_PATH_LIST <cmake_path-TO_NATIVE_PATH_LIST>` of
  :command:`cmake_path` command.

Synopsis
^^^^^^^^

.. parsed-literal::

  `Reading`_
    file(`READ`_ <filename> <out-var> [...])
    file(`STRINGS`_ <filename> <out-var> [...])
    file(`\<HASH\>`_ <filename> <out-var>)
    file(`TIMESTAMP`_ <filename> <out-var> [...])
    file(`GET_RUNTIME_DEPENDENCIES`_ [...])

  `Writing`_
    file({`WRITE`_ | `APPEND`_} <filename> <content>...)
    file({`TOUCH`_ | `TOUCH_NOCREATE`_} <file>...)
    file(`GENERATE`_ OUTPUT <output-file> [...])
    file(`CONFIGURE`_ OUTPUT <output-file> CONTENT <content> [...])

  `Filesystem`_
    file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] <globbing-expr>...)
    file(`MAKE_DIRECTORY`_ <directories>...)
    file({`REMOVE`_ | `REMOVE_RECURSE`_ } <files>...)
    file(`RENAME`_ <oldname> <newname> [...])
    file(`COPY_FILE`_ <oldname> <newname> [...])
    file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
    file(`SIZE`_ <filename> <out-var>)
    file(`READ_SYMLINK`_ <linkname> <out-var>)
    file(`CREATE_LINK`_ <original> <linkname> [...])
    file(`CHMOD`_ <files>... <directories>... PERMISSIONS <permissions>... [...])
    file(`CHMOD_RECURSE`_ <files>... <directories>... PERMISSIONS <permissions>... [...])

  `Path Conversion`_
    file(`REAL_PATH`_ <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
    file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
    file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)

  `Transfer`_
    file(`DOWNLOAD`_ <url> [<file>] [...])
    file(`UPLOAD`_ <file> <url> [...])

  `Locking`_
    file(`LOCK`_ <path> [...])

  `Archiving`_
    file(`ARCHIVE_CREATE`_ OUTPUT <archive> PATHS <paths>... [...])
    file(`ARCHIVE_EXTRACT`_ INPUT <archive> [...])

Reading
^^^^^^^

.. signature::
  file(READ <filename> <variable>
       [OFFSET <offset>] [LIMIT <max-in>] [HEX])

  Read content from a file called ``<filename>`` and store it in a
  ``<variable>``.  Optionally start from the given ``<offset>`` and
  read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
  be converted to a hexadecimal representation (useful for binary data).
  If the ``HEX`` option is specified, letters in the output
  (``a`` through ``f``) are in lowercase.

.. signature::
  file(STRINGS <filename> <variable> <options>...)

  Parse a list of ASCII strings from ``<filename>`` and store it in
  ``<variable>``.  Binary data in the file are ignored.  Carriage return
  (``\r``, CR) characters are ignored.  The options are:

    ``LENGTH_MAXIMUM <max-len>``
      Consider only strings of at most a given length.

    ``LENGTH_MINIMUM <min-len>``
      Consider only strings of at least a given length.

    ``LIMIT_COUNT <max-num>``
      Limit the number of distinct strings to be extracted.

    ``LIMIT_INPUT <max-in>``
      Limit the number of input bytes to read from the file.

    ``LIMIT_OUTPUT <max-out>``
      Limit the number of total bytes to store in the ``<variable>``.

    ``NEWLINE_CONSUME``
      Treat newline characters (``\n``, LF) as part of string content
      instead of terminating at them.

    ``NO_HEX_CONVERSION``
      Intel Hex and Motorola S-record files are automatically converted to
      binary while reading unless this option is given.

    ``REGEX <regex>``
      Consider only strings that match the given regular expression,
      as described under :ref:`string(REGEX) <Regex Specification>`.

      .. versionchanged:: 3.29
        Capture groups from the last match in the file are stored in
        :variable:`CMAKE_MATCH_<n>`, similar to
        :command:`string(REGEX MATCHALL)`.  See policy :policy:`CMP0159`.

    ``ENCODING <encoding-type>``
      .. versionadded:: 3.1

      Consider strings of a given encoding.  Currently supported encodings are:
      ``UTF-8``, ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE``.
      If the ``ENCODING`` option is not provided and the file
      has a Byte Order Mark, the ``ENCODING`` option will be defaulted
      to respect the Byte Order Mark.

  .. versionadded:: 3.2
    Added the ``UTF-16LE``, ``UTF-16BE``, ``UTF-32LE``, ``UTF-32BE`` encodings.

  For example, the code

  .. code-block:: cmake

    file(STRINGS myfile.txt myfile)

  stores a list in the variable ``myfile`` in which each item is a line
  from the input file.

.. signature::
  file(<HASH> <filename> <variable>)
  :target: <HASH>

  Compute a cryptographic hash of the content of ``<filename>`` and
  store it in a ``<variable>``.  The supported ``<HASH>`` algorithm names
  are those listed by the :command:`string(<HASH>)` command.

.. signature::
  file(TIMESTAMP <filename> <variable> [<format>] [UTC])

  Compute a string representation of the modification time of ``<filename>``
  and store it in ``<variable>``.  Should the command be unable to obtain a
  timestamp variable will be set to the empty string ("").

  See the :command:`string(TIMESTAMP)` command for documentation of
  the ``<format>`` and ``UTC`` options.

.. signature::
  file(GET_RUNTIME_DEPENDENCIES [...])

  .. versionadded:: 3.16

  Recursively get the list of libraries depended on by the given files:

  .. code-block:: cmake

    file(GET_RUNTIME_DEPENDENCIES
      [RESOLVED_DEPENDENCIES_VAR <deps_var>]
      [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
      [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
      [EXECUTABLES <executable_files>...]
      [LIBRARIES <library_files>...]
      [MODULES <module_files>...]
      [DIRECTORIES <directories>...]
      [BUNDLE_EXECUTABLE <bundle_executable_file>]
      [PRE_INCLUDE_REGEXES <regexes>...]
      [PRE_EXCLUDE_REGEXES <regexes>...]
      [POST_INCLUDE_REGEXES <regexes>...]
      [POST_EXCLUDE_REGEXES <regexes>...]
      [POST_INCLUDE_FILES <files>...]
      [POST_EXCLUDE_FILES <files>...]
      )

  Please note that this sub-command is not intended to be used in project mode.
  It is intended for use at install time, either from code generated by the
  :command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by
  the project via :command:`install(CODE)` or :command:`install(SCRIPT)`.
  For example:

  .. code-block:: cmake

    install(CODE [[
      file(GET_RUNTIME_DEPENDENCIES
        # ...
        )
      ]])

  The arguments are as follows:

    ``RESOLVED_DEPENDENCIES_VAR <deps_var>``
      Name of the variable in which to store the list of resolved dependencies.

    ``UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>``
      Name of the variable in which to store the list of unresolved
      dependencies. If this variable is not specified, and there are any
      unresolved dependencies, an error is issued.

    ``CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>``
      Variable prefix in which to store conflicting dependency information.
      Dependencies are conflicting if two files with the same name are found in
      two different directories. The list of filenames that conflict are stored
      in ``<conflicting_deps_prefix>_FILENAMES``. For each filename, the list
      of paths that were found for that filename are stored in
      ``<conflicting_deps_prefix>_<filename>``.

    ``EXECUTABLES <executable_files>...``
      List of executable files to read for dependencies. These are executables
      that are typically created with :command:`add_executable`, but they do
      not have to be created by CMake. On Apple platforms, the paths to these
      files determine the value of ``@executable_path`` when recursively
      resolving the libraries. Specifying any kind of library (``STATIC``,
      ``MODULE``, or ``SHARED``) here will result in undefined behavior.

    ``LIBRARIES <library_files>...``
      List of library files to read for dependencies. These are libraries that
      are typically created with :command:`add_library(SHARED)`, but they do
      not have to be created by CMake. Specifying ``STATIC`` libraries,
      ``MODULE`` libraries, or executables here will result in undefined
      behavior.

    ``MODULES <module_files>...``
      List of loadable module files to read for dependencies. These are modules
      that are typically created with :command:`add_library(MODULE)`, but they
      do not have to be created by CMake. They are typically used by calling
      ``dlopen()`` at runtime rather than linked at link time with ``ld -l``.
      Specifying ``STATIC`` libraries, ``SHARED`` libraries, or executables
      here will result in undefined behavior.

    ``DIRECTORIES <directories>...``
      List of additional directories to search for dependencies. On Linux
      platforms, these directories are searched if the dependency is not found
      in any of the other usual paths. If it is found in such a directory, a
      warning is issued, because it means that the file is incomplete (it does
      not list all of the directories that contain its dependencies).
      On Windows platforms, these directories are searched if the dependency
      is not found in any of the other search paths, but no warning is issued,
      because searching other paths is a normal part of Windows dependency
      resolution. On Apple platforms, this argument has no effect.

    ``BUNDLE_EXECUTABLE <bundle_executable_file>``
      Executable to treat as the "bundle executable" when resolving libraries.
      On Apple platforms, this argument determines the value of
      ``@executable_path`` when recursively resolving libraries for
      ``LIBRARIES`` and ``MODULES`` files. It has no effect on ``EXECUTABLES``
      files. On other platforms, it has no effect. This is typically (but not
      always) one of the executables in the ``EXECUTABLES`` argument which
      designates the "main" executable of the package.

  The following arguments specify filters for including or excluding libraries
  to be resolved. See below for a full description of how they work.

    ``PRE_INCLUDE_REGEXES <regexes>...``
      List of pre-include regexes through which to filter the names of
      not-yet-resolved dependencies.

    ``PRE_EXCLUDE_REGEXES <regexes>...``
      List of pre-exclude regexes through which to filter the names of
      not-yet-resolved dependencies.

    ``POST_INCLUDE_REGEXES <regexes>...``
      List of post-include regexes through which to filter the names of
      resolved dependencies.

    ``POST_EXCLUDE_REGEXES <regexes>...``
      List of post-exclude regexes through which to filter the names of
      resolved dependencies.

    ``POST_INCLUDE_FILES <files>...``
      .. versionadded:: 3.21

      List of post-include filenames through which to filter the names of
      resolved dependencies. Symlinks are resolved when attempting to match
      these filenames.

    ``POST_EXCLUDE_FILES <files>...``
      .. versionadded:: 3.21

      List of post-exclude filenames through which to filter the names of
      resolved dependencies. Symlinks are resolved when attempting to match
      these filenames.

  These arguments can be used to exclude unwanted system libraries when
  resolving the dependencies, or to include libraries from a specific
  directory. The filtering works as follows:

  1. If the not-yet-resolved dependency matches any of the
     ``PRE_INCLUDE_REGEXES``, steps 2 and 3 are skipped, and the dependency
     resolution proceeds to step 4.

  2. If the not-yet-resolved dependency matches any of the
     ``PRE_EXCLUDE_REGEXES``, dependency resolution stops for that dependency.

  3. Otherwise, dependency resolution proceeds.

  4. ``file(GET_RUNTIME_DEPENDENCIES)`` searches for the dependency according
     to the linking rules of the platform (see below).

  5. If the dependency is found, and its full path matches one of the
     ``POST_INCLUDE_REGEXES`` or ``POST_INCLUDE_FILES``, the full path is added
     to the resolved dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``
     recursively resolves that library's own dependencies. Otherwise, resolution
     proceeds to step 6.

  6. If the dependency is found, but its full path matches one of the
     ``POST_EXCLUDE_REGEXES`` or ``POST_EXCLUDE_FILES``, it is not added to the
     resolved dependencies, and dependency resolution stops for that dependency.

  7. If the dependency is found, and its full path does not match either
     ``POST_INCLUDE_REGEXES``, ``POST_INCLUDE_FILES``, ``POST_EXCLUDE_REGEXES``,
     or ``POST_EXCLUDE_FILES``, the full path is added to the resolved
     dependencies, and ``file(GET_RUNTIME_DEPENDENCIES)``  recursively resolves
     that library's own dependencies.

  Different platforms have different rules for how dependencies are resolved.
  These specifics are described here.

  On Linux platforms, library resolution works as follows:

  1. If the depending file does not have any ``RUNPATH`` entries, and the
     library exists in one of the depending file's ``RPATH`` entries, or its
     parents', in that order, the dependency is resolved to that file.
  2. Otherwise, if the depending file has any ``RUNPATH`` entries, and the
     library exists in one of those entries, the dependency is resolved to that
     file.
  3. Otherwise, if the library exists in one of the directories listed by
     ``ldconfig``, the dependency is resolved to that file.
  4. Otherwise, if the library exists in one of the ``DIRECTORIES`` entries,
     the dependency is resolved to that file. In this case, a warning is
     issued, because finding a file in one of the ``DIRECTORIES`` means that
     the depending file is not complete (it does not list all the directories
     from which it pulls dependencies).

  5. Otherwise, the dependency is unresolved.

  On Windows platforms, library resolution works as follows:

  1. DLL dependency names are converted to lowercase for matching filters.
     Windows DLL names are case-insensitive, and some linkers mangle the
     case of the DLL dependency names.  However, this makes it more difficult
     for ``PRE_INCLUDE_REGEXES``, ``PRE_EXCLUDE_REGEXES``,
     ``POST_INCLUDE_REGEXES``, and ``POST_EXCLUDE_REGEXES`` to properly
     filter DLL names - every regex would have to check for both uppercase
     and lowercase letters.  For example:

     .. code-block:: cmake

       file(GET_RUNTIME_DEPENDENCIES
         # ...
         PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
         )

     Converting the DLL name to lowercase allows the regexes to only match
     lowercase names, thus simplifying the regex. For example:

     .. code-block:: cmake

       file(GET_RUNTIME_DEPENDENCIES
         # ...
         PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
         )

     This regex will match ``mylibrary.dll`` regardless of how it is cased,
     either on disk or in the depending file. (For example, it will match
     ``mylibrary.dll``, ``MyLibrary.dll``, and ``MYLIBRARY.DLL``.)

     .. versionchanged:: 3.27

       The conversion to lowercase only applies while matching filters.
       Results reported after filtering case-preserve each DLL name as it is
       found on disk, if resolved, and otherwise as it is referenced by the
       dependent binary.

       Prior to CMake 3.27, the results were reported with lowercase DLL
       file names, but the directory portion retained its casing.

  2. (**Not yet implemented**) If the depending file is a Windows Store app,
     and the dependency is listed as a dependency in the application's package
     manifest, the dependency is resolved to that file.

  3. Otherwise, if the library exists in the same directory as the depending
     file, the dependency is resolved to that file.

  4. Otherwise, if the library exists in either the operating system's
     ``system32`` directory or the ``Windows`` directory, in that order, the
     dependency is resolved to that file.

  5. Otherwise, if the library exists in one of the directories specified by
     ``DIRECTORIES``, in the order they are listed, the dependency is resolved
     to that file. In this case, a warning is not issued, because searching
     other directories is a normal part of Windows library resolution.

  6. Otherwise, the dependency is unresolved.

  On Apple platforms, library resolution works as follows:

  1. If the dependency starts with ``@executable_path/``, and an
     ``EXECUTABLES`` argument is in the process of being resolved, and
     replacing ``@executable_path/`` with the directory of the executable
     yields an existing file, the dependency is resolved to that file.

  2. Otherwise, if the dependency starts with ``@executable_path/``, and there
     is a ``BUNDLE_EXECUTABLE`` argument, and replacing ``@executable_path/``
     with the directory of the bundle executable yields an existing file, the
     dependency is resolved to that file.

  3. Otherwise, if the dependency starts with ``@loader_path/``, and replacing
     ``@loader_path/`` with the directory of the depending file yields an
     existing file, the dependency is resolved to that file.

  4. Otherwise, if the dependency starts with ``@rpath/``, and replacing
     ``@rpath/`` with one of the ``RPATH`` entries of the depending file
     yields an existing file, the dependency is resolved to that file.
     Note that ``RPATH`` entries that start with ``@executable_path/`` or
     ``@loader_path/`` also have these items replaced with the appropriate
     path.

  5. Otherwise, if the dependency is an absolute file that exists,
     the dependency is resolved to that file.

  6. Otherwise, the dependency is unresolved.

  This function accepts several variables that determine which tool is used for
  dependency resolution:

  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

    Determines which operating system and executable format the files are built
    for. This could be one of several values:

    * ``linux+elf``
    * ``windows+pe``
    * ``macos+macho``

    If this variable is not specified, it is determined automatically by system
    introspection.

  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

    Determines the tool to use for dependency resolution. It could be one of
    several values, depending on the value of
    :variable:`CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM`:

    ================================================= =============================================
       ``CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM``       ``CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL``
    ================================================= =============================================
    ``linux+elf``                                     ``objdump``
    ``windows+pe``                                    ``objdump`` or ``dumpbin``
    ``macos+macho``                                   ``otool``
    ================================================= =============================================

    If this variable is not specified, it is determined automatically by system
    introspection.

  .. variable:: CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

    Determines the path to the tool to use for dependency resolution. This is
    the actual path to ``objdump``, ``dumpbin``, or ``otool``.

    If this variable is not specified, it is determined by the value of
    ``CMAKE_OBJDUMP`` if set, else by system introspection.

    .. versionadded:: 3.18
      Use ``CMAKE_OBJDUMP`` if set.

Writing
^^^^^^^

.. signature::
  file(WRITE <filename> <content>...)
  file(APPEND <filename> <content>...)

  Write ``<content>`` into a file called ``<filename>``.  If the file does
  not exist, it will be created.  If the file already exists, ``WRITE``
  mode will overwrite it and ``APPEND`` mode will append to the end.
  Any directories in the path specified by ``<filename>`` that do not
  exist will be created.

  If the file is a build input, use the :command:`configure_file` command
  to update the file only when its content changes.

.. signature::
  file(TOUCH <files>...)
  file(TOUCH_NOCREATE <files>...)

  .. versionadded:: 3.12

  Create a file with no content if it does not yet exist. If the file already
  exists, its access and/or modification will be updated to the time when the
  function call is executed.

  Use ``TOUCH_NOCREATE`` to touch a file if it exists but not create it.
  If a file does not exist it will be silently ignored.

  With ``TOUCH`` and ``TOUCH_NOCREATE``, the contents of an existing file
  will not be modified.

.. signature::
  file(GENERATE [...])

  Generate an output file for each build configuration supported by the current
  :manual:`CMake Generator <cmake-generators(7)>`.  Evaluate
  :manual:`generator expressions <cmake-generator-expressions(7)>`
  from the input content to produce the output content.

  .. code-block:: cmake

    file(GENERATE OUTPUT <output-file>
         <INPUT <input-file>|CONTENT <content>>
         [CONDITION <expression>] [TARGET <target>]
         [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
          FILE_PERMISSIONS <permissions>...]
         [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

  The options are:

    ``CONDITION <condition>``
      Generate the output file for a particular configuration only if
      the condition is true.  The condition must be either ``0`` or ``1``
      after evaluating generator expressions.

    ``CONTENT <content>``
      Use the content given explicitly as input.

    ``INPUT <input-file>``
      Use the content from a given file as input.

      .. versionchanged:: 3.10
        A relative path is treated with respect to the value of
        :variable:`CMAKE_CURRENT_SOURCE_DIR`.  See policy :policy:`CMP0070`.

    ``OUTPUT <output-file>``
      Specify the output file name to generate.  Use generator expressions
      such as :genex:`$<CONFIG>` to specify a configuration-specific
      output file name.  Multiple configurations may generate the same output
      file only if the generated content is identical.  Otherwise, the
      ``<output-file>`` must evaluate to an unique name for each configuration.

      .. versionchanged:: 3.10
        A relative path (after evaluating generator expressions) is treated
        with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
        See policy :policy:`CMP0070`.

    ``TARGET <target>``
      .. versionadded:: 3.19

      Specify which target to use when evaluating generator expressions that
      require a target for evaluation (e.g.
      :genex:`$<COMPILE_FEATURES:...>`,
      :genex:`$<TARGET_PROPERTY:prop>`).

    ``NO_SOURCE_PERMISSIONS``
      .. versionadded:: 3.20

      The generated file permissions default to the standard 644 value
      (-rw-r--r--).

    ``USE_SOURCE_PERMISSIONS``
      .. versionadded:: 3.20

      Transfer the file permissions of the ``INPUT`` file to the generated
      file. This is already the default behavior if none of the three
      permissions-related keywords are given (``NO_SOURCE_PERMISSIONS``,
      ``USE_SOURCE_PERMISSIONS`` or ``FILE_PERMISSIONS``).  The
      ``USE_SOURCE_PERMISSIONS`` keyword mostly serves as a way of making
      the intended behavior clearer at the call site. It is an error to
      specify this option without ``INPUT``.

    ``FILE_PERMISSIONS <permissions>...``
      .. versionadded:: 3.20

      Use the specified permissions for the generated file.

    ``NEWLINE_STYLE <style>``
      .. versionadded:: 3.20

      Specify the newline style for the generated file.  Specify
      ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
      ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.

  Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
  ``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
  Generated files are modified and their timestamp updated on subsequent cmake
  runs only if their content is changed.

  Note also that ``file(GENERATE)`` does not create the output file until the
  generation phase. The output file will not yet have been written when the
  ``file(GENERATE)`` command returns, it is written only after processing all
  of a project's ``CMakeLists.txt`` files.

.. signature::
  file(CONFIGURE OUTPUT <output-file>
       CONTENT <content>
       [ESCAPE_QUOTES] [@ONLY]
       [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])
  :target: CONFIGURE

  .. versionadded:: 3.18

  Generate an output file using the input given by ``CONTENT`` and substitute
  variable values referenced as ``@VAR@`` or ``${VAR}`` contained therein. The
  substitution rules behave the same as the :command:`configure_file` command.
  In order to match :command:`configure_file`'s behavior, generator expressions
  are not supported for both ``OUTPUT`` and ``CONTENT``.

  The arguments are:

    ``OUTPUT <output-file>``
      Specify the output file name to generate. A relative path is treated with
      respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
      ``<output-file>`` does not support generator expressions.

    ``CONTENT <content>``
      Use the content given explicitly as input.
      ``<content>`` does not support generator expressions.

    ``ESCAPE_QUOTES``
      Escape any substituted quotes with backslashes (C-style).

    ``@ONLY``
      Restrict variable replacement to references of the form ``@VAR@``.
      This is useful for configuring scripts that use ``${VAR}`` syntax.

    ``NEWLINE_STYLE <style>``
      Specify the newline style for the output file.  Specify
      ``UNIX`` or ``LF`` for ``\n`` newlines, or specify
      ``DOS``, ``WIN32``, or ``CRLF`` for ``\r\n`` newlines.

Filesystem
^^^^^^^^^^

.. signature::
  file(GLOB <variable>
       [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
       <globbing-expressions>...)
  file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
       [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
       <globbing-expressions>...)

  Generate a list of files that match the ``<globbing-expressions>`` and
  store it into the ``<variable>``.  Globbing expressions are similar to
  regular expressions, but much simpler.  If ``RELATIVE`` flag is
  specified, the results will be returned as relative paths to the given
  path.

  .. versionchanged:: 3.6
    The results will be ordered lexicographically.

  On Windows and macOS, globbing is case-insensitive even if the underlying
  filesystem is case-sensitive (both filenames and globbing expressions are
  converted to lowercase before matching).  On other platforms, globbing is
  case-sensitive.

  .. versionadded:: 3.3
    By default ``GLOB`` lists directories. Directories are omitted in the
    result if ``LIST_DIRECTORIES`` is set to false.

  .. versionadded:: 3.12
    If the ``CONFIGURE_DEPENDS`` flag is specified, CMake will add logic
    to the main build system check target to rerun the flagged ``GLOB``
    commands at build time. If any of the outputs change, CMake will regenerate
    the build system.

  .. note::
    We do not recommend using GLOB to collect a list of source files from
    your source tree.  If no CMakeLists.txt file changes when a source is
    added or removed then the generated build system cannot know when to
    ask CMake to regenerate.
    The ``CONFIGURE_DEPENDS`` flag may not work reliably on all generators, or
    if a new generator is added in the future that cannot support it, projects
    using it will be stuck. Even if ``CONFIGURE_DEPENDS`` works reliably, there
    is still a cost to perform the check on every rebuild.

  Examples of globbing expressions include:

  ============== ======================================================
  ``*.cxx``      match all files with extension ``cxx``
  ``*.vt?``      match all files with extension ``vta``, ..., ``vtz``
  ``f[3-5].txt`` match files ``f3.txt``, ``f4.txt``, ``f5.txt``
  ============== ======================================================

  The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
  matched directory and match the files.  Subdirectories that are symlinks
  are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
  :policy:`CMP0009` is not set to ``NEW``.

  .. versionadded:: 3.3
    By default ``GLOB_RECURSE`` omits directories from result list. Setting
    ``LIST_DIRECTORIES`` to true adds directories to result list.
    If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
    ``NEW`` then ``LIST_DIRECTORIES`` treats symlinks as directories.

  Examples of recursive globbing include:

  ============== ======================================================
  ``/dir/*.py``  match all python files in ``/dir`` and subdirectories
  ============== ======================================================

.. signature::
  file(MAKE_DIRECTORY <directories>...)

  Create the given directories and their parents as needed.

.. signature::
  file(REMOVE <files>...)
  file(REMOVE_RECURSE <files>...)

  Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
  files and directories, including non-empty directories. No error is emitted
  if a given file does not exist.  Relative input paths are evaluated with
  respect to the current source directory.

  .. versionchanged:: 3.15
    Empty input paths are ignored with a warning.  Previous versions of CMake
    interpreted empty strings as a relative path with respect to the current
    directory and removed its contents.

.. signature::
  file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE])

  Move a file or directory within a filesystem from ``<oldname>`` to
  ``<newname>``, replacing the destination atomically.

  The options are:

    ``RESULT <result>``
      .. versionadded:: 3.21

      Set ``<result>`` variable to ``0`` on success or an error message
      otherwise. If ``RESULT`` is not specified and the operation fails,
      an error is emitted.

    ``NO_REPLACE``
      .. versionadded:: 3.21

      If the ``<newname>`` path already exists, do not replace it.
      If ``RESULT <result>`` is used, the result variable will be
      set to ``NO_REPLACE``.  Otherwise, an error is emitted.

.. signature::
  file(COPY_FILE <oldname> <newname>
       [RESULT <result>]
       [ONLY_IF_DIFFERENT]
       [INPUT_MAY_BE_RECENT])

  .. versionadded:: 3.21

  Copy a file from ``<oldname>`` to ``<newname>``. Directories are not
  supported. Symlinks are ignored and ``<oldfile>``'s content is read and
  written to ``<newname>`` as a new file.

  The options are:

    ``RESULT <result>``
      Set ``<result>`` variable to ``0`` on success or an error message
      otherwise.  If ``RESULT`` is not specified and the operation fails,
      an error is emitted.

    ``ONLY_IF_DIFFERENT``
      If the ``<newname>`` path already exists, do not replace it if the file's
      contents are already the same as ``<oldname>`` (this avoids updating
      ``<newname>``'s timestamp).

    ``INPUT_MAY_BE_RECENT``
      .. versionadded:: 3.26

      Tell CMake that the input file may have been recently created.  This is
      meaningful only on Windows, where files may be inaccessible for a short
      time after they are created.  With this option, if permission is denied,
      CMake will retry reading the input a few times.

  This sub-command has some similarities to :command:`configure_file`
  with the ``COPYONLY`` option.  An important difference is that
  :command:`configure_file` creates a dependency on the source file,
  so CMake will be re-run if it changes. The ``file(COPY_FILE)``
  sub-command does not create such a dependency.

  See also the :command:`file(COPY)` sub-command just below which provides
  further file-copying capabilities.

.. signature::
  file(COPY [...])
  file(INSTALL [...])

  The ``COPY`` signature copies files, directories, and symlinks to a
  destination folder.  Relative input paths are evaluated with respect
  to the current source directory, and a relative destination is
  evaluated with respect to the current build directory.  Copying
  preserves input file timestamps, and optimizes out a file if it exists
  at the destination with the same timestamp.  Copying preserves input
  permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
  are given (default is ``USE_SOURCE_PERMISSIONS``).

  .. code-block:: cmake

    file(<COPY|INSTALL> <files>... DESTINATION <dir>
         [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
         [FILE_PERMISSIONS <permissions>...]
         [DIRECTORY_PERMISSIONS <permissions>...]
         [FOLLOW_SYMLINK_CHAIN]
         [FILES_MATCHING]
         [[PATTERN <pattern> | REGEX <regex>]
          [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

  .. note::

    For a simple file copying operation, the :command:`file(COPY_FILE)`
    sub-command just above may be easier to use.

  .. versionadded:: 3.15
    If ``FOLLOW_SYMLINK_CHAIN`` is specified, ``COPY`` will recursively resolve
    the symlinks at the paths given until a real file is found, and install
    a corresponding symlink in the destination for each symlink encountered.
    For each symlink that is installed, the resolution is stripped of the
    directory, leaving only the filename, meaning that the new symlink points
    to a file in the same directory as the symlink. This feature is useful on
    some Unix systems, where libraries are installed as a chain of symlinks
    with version numbers, with less specific versions pointing to more specific
    versions. ``FOLLOW_SYMLINK_CHAIN`` will install all of these symlinks and
    the library itself into the destination directory. For example, if you have
    the following directory structure:

      * ``/opt/foo/lib/libfoo.so.1.2.3``
      * ``/opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3``
      * ``/opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2``
      * ``/opt/foo/lib/libfoo.so -> libfoo.so.1``

    and you do:

    .. code-block:: cmake

      file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)

    This will install all of the symlinks and ``libfoo.so.1.2.3`` itself into
    ``lib``.

  See the :command:`install(DIRECTORY)` command for documentation of
  permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
  ``EXCLUDE`` options.  Copying directories preserves the structure
  of their content even if options are used to select a subset of
  files.

  The ``INSTALL`` signature differs slightly from ``COPY``: it prints
  status messages, and ``NO_SOURCE_PERMISSIONS`` is default. Installation
  scripts generated by the :command:`install` command use this signature
  (with some undocumented options for internal use).

  .. versionchanged:: 3.22

    The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the
    default copying behavior of :command:`file(INSTALL)`.

.. signature::
  file(SIZE <filename> <variable>)

  .. versionadded:: 3.14

  Determine the file size of the ``<filename>`` and put the result in
  ``<variable>`` variable. Requires that ``<filename>`` is a valid path
  pointing to a file and is readable.

.. signature::
  file(READ_SYMLINK <linkname> <variable>)

  .. versionadded:: 3.14

  Query the symlink ``<linkname>`` and stores the path it points to
  in the result ``<variable>``.  If ``<linkname>`` does not exist
  or is not a symlink, CMake issues a fatal error.

  Note that this command returns the raw symlink path and does not resolve
  a relative path.  The following is an example of how to ensure that an
  absolute path is obtained:

  .. code-block:: cmake

    set(linkname "/path/to/foo.sym")
    file(READ_SYMLINK "${linkname}" result)
    if(NOT IS_ABSOLUTE "${result}")
      get_filename_component(dir "${linkname}" DIRECTORY)
      set(result "${dir}/${result}")
    endif()

.. signature::
  file(CREATE_LINK <original> <linkname>
       [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

  .. versionadded:: 3.14

  Create a link ``<linkname>`` that points to ``<original>``.
  It will be a hard link by default, but providing the ``SYMBOLIC`` option
  results in a symbolic link instead.  Hard links require that ``original``
  exists and is a file, not a directory.  If ``<linkname>`` already exists,
  it will be overwritten.

  The ``<result>`` variable, if specified, receives the status of the
  operation.  It is set to ``0`` upon success or an error message otherwise.
  If ``RESULT`` is not specified and the operation fails, a fatal error is
  emitted.

  Specifying ``COPY_ON_ERROR`` enables copying the file as a fallback if
  creating the link fails.  It can be useful for handling situations such as
  ``<original>`` and ``<linkname>`` being on different drives or mount points,
  which would make them unable to support a hard link.

.. signature::
  file(CHMOD <files>... <directories>...
       [PERMISSIONS <permissions>...]
       [FILE_PERMISSIONS <permissions>...]
       [DIRECTORY_PERMISSIONS <permissions>...])

  .. versionadded:: 3.19

  Set the permissions for the ``<files>...`` and ``<directories>...``
  specified. Valid permissions are  ``OWNER_READ``, ``OWNER_WRITE``,
  ``OWNER_EXECUTE``, ``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``,
  ``WORLD_READ``, ``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, ``SETGID``.

  Valid combination of keywords are:

    ``PERMISSIONS``
      All items are changed.

    ``FILE_PERMISSIONS``
      Only files are changed.

    ``DIRECTORY_PERMISSIONS``
      Only directories are changed.

    ``PERMISSIONS`` and ``FILE_PERMISSIONS``
      ``FILE_PERMISSIONS`` overrides ``PERMISSIONS`` for files.

    ``PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
      ``DIRECTORY_PERMISSIONS`` overrides ``PERMISSIONS`` for directories.

    ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS``
      Use ``FILE_PERMISSIONS`` for files and ``DIRECTORY_PERMISSIONS`` for
      directories.

.. signature::
  file(CHMOD_RECURSE <files>... <directories>...
       [PERMISSIONS <permissions>...]
       [FILE_PERMISSIONS <permissions>...]
       [DIRECTORY_PERMISSIONS <permissions>...])

  .. versionadded:: 3.19

  Same as :cref:`CHMOD`, but change the permissions of files and directories
  present in the ``<directories>...`` recursively.

Path Conversion
^^^^^^^^^^^^^^^

.. signature::
  file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])

  .. versionadded:: 3.19

  Compute the absolute path to an existing file or directory with symlinks
  resolved.  The options are:

    ``BASE_DIRECTORY <dir>``
      If the provided ``<path>`` is a relative path, it is evaluated relative
      to the given base directory ``<dir>``. If no base directory is provided,
      the default base directory will be :variable:`CMAKE_CURRENT_SOURCE_DIR`.

    ``EXPAND_TILDE``
      .. versionadded:: 3.21

      If the ``<path>`` is ``~`` or starts with ``~/``, the ``~`` is replaced
      by the user's home directory.  The path to the home directory is obtained
      from environment variables.  On Windows, the ``USERPROFILE`` environment
      variable is used, falling back to the ``HOME`` environment variable
      if ``USERPROFILE`` is not defined.  On all other platforms, only ``HOME``
      is used.

  .. versionchanged:: 3.28

    All symlinks are resolved before collapsing ``../`` components.
    See policy :policy:`CMP0152`.

.. signature::
  file(RELATIVE_PATH <variable> <directory> <file>)

  Compute the relative path from a ``<directory>`` to a ``<file>`` and
  store it in the ``<variable>``.

.. signature::
  file(TO_CMAKE_PATH "<path>" <variable>)
  file(TO_NATIVE_PATH "<path>" <variable>)

  The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
  path with forward-slashes (``/``).  The input can be a single path or a
  system search path like ``$ENV{PATH}``.  A search path will be converted
  to a cmake-style list separated by ``;`` characters.

  The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
  path with platform-specific slashes (``\`` on Windows hosts and ``/``
  elsewhere).

  Always use double quotes around the ``<path>`` to be sure it is treated
  as a single argument to this command.

Transfer
^^^^^^^^

.. signature::
  file(DOWNLOAD <url> [<file>] <options>...)
  file(UPLOAD <file> <url> <options>...)

  The ``DOWNLOAD`` subcommand downloads the given ``<url>`` to a local
  ``<file>``.  The ``UPLOAD`` mode uploads a local ``<file>`` to a given
  ``<url>``.

  .. versionadded:: 3.19
    If ``<file>`` is not specified for ``file(DOWNLOAD)``, the file is not
    saved. This can be useful if you want to know if a file can be downloaded
    (for example, to check that it exists) without actually saving it anywhere.

  Options to both ``DOWNLOAD`` and ``UPLOAD`` are:

    ``INACTIVITY_TIMEOUT <seconds>``
      Terminate the operation after a period of inactivity.

    ``LOG <variable>``
      Store a human-readable log of the operation in a variable.

    ``SHOW_PROGRESS``
      Print progress information as status messages until the operation is
      complete.

    ``STATUS <variable>``
      Store the resulting status of the operation in a variable.
      The status is a ``;`` separated list of length 2.
      The first element is the numeric return value for the operation,
      and the second element is a string value for the error.
      A ``0`` numeric error means no error in the operation.

    ``TIMEOUT <seconds>``
      Terminate the operation after a given total time has elapsed.

    ``USERPWD <username>:<password>``
      .. versionadded:: 3.7

      Set username and password for operation.

    ``HTTPHEADER <HTTP-header>``
      .. versionadded:: 3.7

      HTTP header for ``DOWNLOAD`` and ``UPLOAD`` operations. ``HTTPHEADER``
      can be repeated for multiple options:

      .. code-block:: cmake

        file(DOWNLOAD <url>
             HTTPHEADER "Authorization: Bearer <auth-token>"
             HTTPHEADER "UserAgent: Mozilla/5.0")

    ``NETRC <level>``
      .. versionadded:: 3.11

      Specify whether the .netrc file is to be used for operation.  If this
      option is not specified, the value of the :variable:`CMAKE_NETRC`
      variable will be used instead.

      Valid levels are:

        ``IGNORED``
          The .netrc file is ignored.
          This is the default.

        ``OPTIONAL``
          The .netrc file is optional, and information in the URL is preferred.
          The file will be scanned to find which ever information is not
          specified in the URL.

        ``REQUIRED``
          The .netrc file is required, and information in the URL is ignored.

    ``NETRC_FILE <file>``
      .. versionadded:: 3.11

      Specify an alternative .netrc file to the one in your home directory,
      if the ``NETRC`` level is ``OPTIONAL`` or ``REQUIRED``. If this option
      is not specified, the value of the :variable:`CMAKE_NETRC_FILE` variable
      will be used instead.

    ``TLS_VERIFY <ON|OFF>``
      Specify whether to verify the server certificate for ``https://`` URLs.
      The default is to *not* verify. If this option is not specified, the
      value of the :variable:`CMAKE_TLS_VERIFY` variable will be used instead.

      .. versionadded:: 3.18
        Added support to ``file(UPLOAD)``.

    ``TLS_CAINFO <file>``
      Specify a custom Certificate Authority file for ``https://`` URLs.
      If this option is not specified, the value of the
      :variable:`CMAKE_TLS_CAINFO` variable will be used instead.

      .. versionadded:: 3.18
        Added support to ``file(UPLOAD)``.

  For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
  certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
  check certificates.

  Additional options to ``DOWNLOAD`` are:

    ``EXPECTED_HASH <algorithm>=<value>``
      Verify that the downloaded content hash matches the expected value, where
      ``<algorithm>`` is one of the algorithms supported by :cref:`<HASH>`.
      If the file already exists and matches the hash, the download is skipped.
      If the file already exists and does not match the hash, the file is
      downloaded again. If after download the file does not match the hash, the
      operation fails with an error. It is an error to specify this option if
      ``DOWNLOAD`` is not given a ``<file>``.

    ``EXPECTED_MD5 <value>``
      Historical short-hand for ``EXPECTED_HASH MD5=<value>``. It is an error
      to specify this if ``DOWNLOAD`` is not given a ``<file>``.

    ``RANGE_START <value>``
      .. versionadded:: 3.24

      Offset of the start of the range in file in bytes. Could be omitted to
      download up to the specified ``RANGE_END``.

    ``RANGE_END <value>``
      .. versionadded:: 3.24

      Offset of the end of the range in file in bytes. Could be omitted to
      download everything from the specified ``RANGE_START`` to the end of
      file.

Locking
^^^^^^^

.. signature::
  file(LOCK <path> [DIRECTORY] [RELEASE]
       [GUARD <FUNCTION|FILE|PROCESS>]
       [RESULT_VARIABLE <variable>]
       [TIMEOUT <seconds>])

  .. versionadded:: 3.2

  Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and
  file ``<path>/cmake.lock`` otherwise.  The file will be locked for the scope
  defined by the ``GUARD`` option (default value is ``PROCESS``).  The
  ``RELEASE`` option can be used to unlock the file explicitly.  If the
  ``TIMEOUT`` option is not specified, CMake will wait until the lock succeeds
  or until a fatal error occurs.  If ``TIMEOUT`` is set to ``0``, locking will
  be tried once and the result will be reported immediately.  If ``TIMEOUT``
  is not ``0``, CMake will try to lock the file for the period specified by
  the ``TIMEOUT <seconds>`` value.  Any errors will be interpreted as fatal if
  there is no ``RESULT_VARIABLE`` option.  Otherwise, the result will be stored
  in ``<variable>`` and will be ``0`` on success or an error message on
  failure.

  Note that lock is advisory; there is no guarantee that other processes will
  respect this lock, i.e. lock synchronize two or more CMake instances sharing
  some modifiable resources. Similar logic applies to the ``DIRECTORY`` option;
  locking a parent directory doesn't prevent other ``LOCK`` commands from
  locking any child directory or file.

  Trying to lock the same file twice is not allowed.  Any intermediate
  directories and the file itself will be created if they not exist.  The
  ``GUARD`` and ``TIMEOUT`` options are ignored on the ``RELEASE`` operation.

Archiving
^^^^^^^^^

.. signature::
  file(ARCHIVE_CREATE OUTPUT <archive>
    PATHS <paths>...
    [FORMAT <format>]
    [COMPRESSION <compression>
     [COMPRESSION_LEVEL <compression-level>]]
    [MTIME <mtime>]
    [VERBOSE])
  :target: ARCHIVE_CREATE
  :break: verbatim

  .. versionadded:: 3.18

  Creates the specified ``<archive>`` file with the files and directories
  listed in ``<paths>``.  Note that ``<paths>`` must list actual files or
  directories; wildcards are not supported.

  Use the ``FORMAT`` option to specify the archive format.  Supported values
  for ``<format>`` are ``7zip``, ``gnutar``, ``pax``, ``paxr``, ``raw`` and
  ``zip``.  If ``FORMAT`` is not given, the default format is ``paxr``.

  Some archive formats allow the type of compression to be specified.
  The ``7zip`` and ``zip`` archive formats already imply a specific type of
  compression.  The other formats use no compression by default, but can be
  directed to do so with the ``COMPRESSION`` option.  Valid values for
  ``<compression>`` are ``None``, ``BZip2``, ``GZip``, ``XZ``, and ``Zstd``.

  .. versionadded:: 3.19
    The compression level can be specified with the ``COMPRESSION_LEVEL``
    option.  The ``<compression-level>`` should be between 0-9, with the
    default being 0.  The ``COMPRESSION`` option must be present when
    ``COMPRESSION_LEVEL`` is given.

  .. versionadded:: 3.26
    The ``<compression-level>`` of the ``Zstd`` algorithm can be set
    between 0-19.

  .. note::
    With ``FORMAT`` set to ``raw``, only one file will be compressed with the
    compression type specified by ``COMPRESSION``.

  The ``VERBOSE`` option enables verbose output for the archive operation.

  To specify the modification time recorded in tarball entries, use
  the ``MTIME`` option.

.. signature::
  file(ARCHIVE_EXTRACT
    INPUT <archive>
    [DESTINATION <dir>]
    [PATTERNS <patterns>...]
    [LIST_ONLY]
    [VERBOSE]
    [TOUCH])
  :target: ARCHIVE_EXTRACT

  .. versionadded:: 3.18

  Extracts or lists the content of the specified ``<archive>``.

  The directory where the content of the archive will be extracted to can
  be specified using the ``DESTINATION`` option.  If the directory does not
  exist, it will be created.  If ``DESTINATION`` is not given, the current
  binary directory will be used.

  If required, you may select which files and directories to list or extract
  from the archive using the specified ``<patterns>``.  Wildcards are
  supported.  If the ``PATTERNS`` option is not given, the entire archive will
  be listed or extracted.

  ``LIST_ONLY`` will list the files in the archive rather than extract them.

  .. note::
    The working directory for this subcommand is the ``DESTINATION`` directory
    (provided or computed) except when ``LIST_ONLY`` is specified. Therefore,
    outside of script mode, it may be best to provide absolute paths to
    ``INPUT`` archives as they are unlikely to be extracted where a relative
    path works.

  .. versionadded:: 3.24
    The ``TOUCH`` option gives extracted files a current local
    timestamp instead of extracting file timestamps from the archive.

  With ``VERBOSE``, the command will produce verbose output.


code:
find_file
---------

.. |FIND_XXX| replace:: find_file
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |SEARCH_XXX| replace:: full path to a file
.. |SEARCH_XXX_DESC| replace:: full path to named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``

.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``

.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`

.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_INCLUDE_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`

.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
   and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
   On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
   This behavior was removed by CMake 3.28.

.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
   :variable:`CMAKE_SYSTEM_INCLUDE_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
   :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`

.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
   :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`

.. include:: FIND_XXX.txt

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
find_library
------------

.. |FIND_XXX| replace:: find_library
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
.. |SEARCH_XXX| replace:: library
.. |SEARCH_XXX_DESC| replace:: library
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``

.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``

.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`

.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_LIBRARY_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`

.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``LIB``
   and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
   On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
   This behavior was removed by CMake 3.28.

.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   ``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
   :variable:`CMAKE_SYSTEM_LIBRARY_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
   :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`

.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
   :variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`

.. include:: FIND_XXX.txt

When more than one value is given to the ``NAMES`` option this command by
default will consider one name at a time and search every directory
for it.  The ``NAMES_PER_DIR`` option tells this command to consider one
directory at a time and search for all names in it.

Each library name given to the ``NAMES`` option is first considered
as a library file name and then considered with platform-specific
prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``).  Therefore one
may specify library file names such as ``libfoo.a`` directly.
This can be used to locate static libraries on UNIX-like systems.

If the library found is a framework, then ``<VAR>`` will be set to the full
path to the framework ``<fullPath>/A.framework``.  When a full path to a
framework is used as a library, CMake will use a ``-framework A``, and a
``-F<fullPath>`` to link the framework to the target.

.. versionadded:: 3.28

  The library found can now be a ``.xcframework`` folder.

If the :variable:`CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX` variable is set all
search paths will be tested as normal, with the suffix appended, and with
all matches of ``lib/`` replaced with
``lib${CMAKE_FIND_LIBRARY_CUSTOM_LIB_SUFFIX}/``.  This variable overrides
the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS`,
:prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS`,
and :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global properties.

If the :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` global property is set
all search paths will be tested as normal, with ``32/`` appended, and
with all matches of ``lib/`` replaced with ``lib32/``.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.

If the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` global property is set
all search paths will be tested as normal, with ``x32/`` appended, and
with all matches of ``lib/`` replaced with ``libx32/``.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.

If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
all search paths will be tested as normal, with ``64/`` appended, and
with all matches of ``lib/`` replaced with ``lib64/``.  This property is
automatically set for the platforms that are known to need it if at
least one of the languages supported by the :command:`project` command
is enabled.


code:
find_package
------------

.. |FIND_XXX| replace:: find_package
.. |FIND_ARGS_XXX| replace:: <PackageName>
.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
   :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`

.. only:: html

   .. contents::

.. note:: The :guide:`Using Dependencies Guide` provides a high-level
  introduction to this general topic. It provides a broader overview of
  where the ``find_package()`` command fits into the bigger picture,
  including its relationship to the :module:`FetchContent` module.
  The guide is recommended pre-reading before moving on to the details below.

Find a package (usually provided by something external to the project),
and load its package-specific details.  Calls to this command can also
be intercepted by :ref:`dependency providers <dependency_providers>`.

Search Modes
^^^^^^^^^^^^

The command has a few modes by which it searches for packages:

**Module mode**
  In this mode, CMake searches for a file called ``Find<PackageName>.cmake``,
  looking first in the locations listed in the :variable:`CMAKE_MODULE_PATH`,
  then among the :ref:`Find Modules` provided by the CMake installation.
  If the file is found, it is read and processed by CMake.  It is responsible
  for finding the package, checking the version, and producing any needed
  messages.  Some Find modules provide limited or no support for versioning;
  check the Find module's documentation.

  The ``Find<PackageName>.cmake`` file is not typically provided by the
  package itself.  Rather, it is normally provided by something external to
  the package, such as the operating system, CMake itself, or even the project
  from which the ``find_package()`` command was called.  Being externally
  provided, :ref:`Find Modules` tend to be heuristic in nature and are
  susceptible to becoming out-of-date.  They typically search for certain
  libraries, files and other package artifacts.

  Module mode is only supported by the
  :ref:`basic command signature <Basic Signature>`.

**Config mode**
  In this mode, CMake searches for a file called
  ``<lowercasePackageName>-config.cmake`` or ``<PackageName>Config.cmake``.
  It will also look for ``<lowercasePackageName>-config-version.cmake`` or
  ``<PackageName>ConfigVersion.cmake`` if version details were specified
  (see :ref:`version selection` for an explanation of how these separate
  version files are used).

  In config mode, the command can be given a list of names to search for
  as package names.  The locations where CMake searches for the config and
  version files is considerably more complicated than for Module mode
  (see :ref:`search procedure`).

  The config and version files are typically installed as part of the
  package, so they tend to be more reliable than Find modules.  They usually
  contain direct knowledge of the package contents, so no searching or
  heuristics are needed within the config or version files themselves.

  Config mode is supported by both the :ref:`basic <Basic Signature>` and
  :ref:`full <Full Signature>` command signatures.

**FetchContent redirection mode**
  .. versionadded:: 3.24
    A call to ``find_package()`` can be redirected internally to a package
    provided by the :module:`FetchContent` module.  To the caller, the behavior
    will appear similar to Config mode, except that the search logic is
    by-passed and the component information is not used.  See
    :command:`FetchContent_Declare` and :command:`FetchContent_MakeAvailable`
    for further details.

When not redirected to a package provided by :module:`FetchContent`, the
command arguments determine whether Module or Config mode is used.  When the
`basic signature`_ is used, the command searches in Module mode first.
If the package is not found, the search falls back to Config mode.
A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable
to true to reverse the priority and direct CMake to search using Config mode
first before falling back to Module mode.  The basic signature can also be
forced to use only Module mode with a ``MODULE`` keyword.  If the
`full signature`_ is used, the command only searches in Config mode.

Where possible, user code should generally look for packages using the
`basic signature`_, since that allows the package to be found with any mode.
Project maintainers wishing to provide a config package should understand
the bigger picture, as explained in :ref:`Full Signature` and all subsequent
sections on this page.

.. _`basic signature`:

Basic Signature
^^^^^^^^^^^^^^^

.. parsed-literal::

  find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE]
               [REQUIRED] [[COMPONENTS] [components...]]
               [OPTIONAL_COMPONENTS components...]
               [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
               [GLOBAL]
               [NO_POLICY_SCOPE]
               [BYPASS_PROVIDER])

The basic signature is supported by both Module and Config modes.
The ``MODULE`` keyword implies that only Module mode can be used to find
the package, with no fallback to Config mode.

Regardless of the mode used, a ``<PackageName>_FOUND`` variable will be
set to indicate whether the package was found.  When the package is found,
package-specific information may be provided through other variables and
:ref:`Imported Targets` documented by the package itself.  The
``QUIET`` option disables informational messages, including those indicating
that the package cannot be found if it is not ``REQUIRED``.  The ``REQUIRED``
option stops processing with an error message if the package cannot be found.

A package-specific list of required components may be listed after the
``COMPONENTS`` keyword.  If any of these components are not able to be
satisfied, the package overall is considered to be not found.  If the
``REQUIRED`` option is also present, this is treated as a fatal error,
otherwise execution still continues.  As a form of shorthand, if the
``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted
and the required components can be listed directly after ``REQUIRED``.

Additional optional components may be listed after
``OPTIONAL_COMPONENTS``.  If these cannot be satisfied, the package overall
can still be considered found, as long as all required components are
satisfied.

The set of available components and their meaning are defined by the
target package.  Formally, it is up to the target package how to
interpret the component information given to it, but it should follow
the expectations stated above.  For calls where no components are specified,
there is no single expected behavior and target packages should clearly
define what occurs in such cases.  Common arrangements include assuming it
should find all components, no components or some well-defined subset of the
available components.

.. versionadded:: 3.24
  The ``REGISTRY_VIEW`` keyword specifies which registry views should be
  queried. This keyword is only meaningful on ``Windows`` platforms and will
  be ignored on all others. Formally, it is up to the target package how to
  interpret the registry view information given to it.

.. versionadded:: 3.24
  Specifying the ``GLOBAL`` keyword will promote all imported targets to
  a global scope in the importing project. Alternatively, this functionality
  can be enabled by setting the :variable:`CMAKE_FIND_PACKAGE_TARGETS_GLOBAL`
  variable.

.. _FIND_PACKAGE_VERSION_FORMAT:

The ``[version]`` argument requests a version with which the package found
should be compatible. There are two possible forms in which it may be
specified:

  * A single version with the format ``major[.minor[.patch[.tweak]]]``, where
    each component is a numeric value.
  * A version range with the format ``versionMin...[<]versionMax`` where
    ``versionMin`` and ``versionMax`` have the same format and constraints
    on components being integers as the single version.  By default, both end
    points are included.  By specifying ``<``, the upper end point will be
    excluded. Version ranges are only supported with CMake 3.19 or later.

The ``EXACT`` option requests that the version be matched exactly. This option
is incompatible with the specification of a version range.

If no ``[version]`` and/or component list is given to a recursive invocation
inside a find-module, the corresponding arguments are forwarded
automatically from the outer call (including the ``EXACT`` flag for
``[version]``).  Version support is currently provided only on a
package-by-package basis (see the `Version Selection`_ section below).
When a version range is specified but the package is only designed to expect
a single version, the package will ignore the upper end point of the range and
only take the single version at the lower end of the range into account.

See the :command:`cmake_policy` command documentation for discussion
of the ``NO_POLICY_SCOPE`` option.

.. versionadded:: 3.24
  The ``BYPASS_PROVIDER`` keyword is only allowed when ``find_package()`` is
  being called by a :ref:`dependency provider <dependency_providers>`.
  It can be used by providers to call the built-in ``find_package()``
  implementation directly and prevent that call from being re-routed back to
  itself.  Future versions of CMake may detect attempts to use this keyword
  from places other than a dependency provider and halt with a fatal error.

.. _`full signature`:

Full Signature
^^^^^^^^^^^^^^

.. parsed-literal::

  find_package(<PackageName> [version] [EXACT] [QUIET]
               [REQUIRED] [[COMPONENTS] [components...]]
               [OPTIONAL_COMPONENTS components...]
               [CONFIG|NO_MODULE]
               [GLOBAL]
               [NO_POLICY_SCOPE]
               [BYPASS_PROVIDER]
               [NAMES name1 [name2 ...]]
               [CONFIGS config1 [config2 ...]]
               [HINTS path1 [path2 ... ]]
               [PATHS path1 [path2 ... ]]
               [REGISTRY_VIEW  (64|32|64_32|32_64|HOST|TARGET|BOTH)]
               [PATH_SUFFIXES suffix1 [suffix2 ...]]
               [NO_DEFAULT_PATH]
               [NO_PACKAGE_ROOT_PATH]
               [NO_CMAKE_PATH]
               [NO_CMAKE_ENVIRONMENT_PATH]
               [NO_SYSTEM_ENVIRONMENT_PATH]
               [NO_CMAKE_PACKAGE_REGISTRY]
               [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
               [NO_CMAKE_SYSTEM_PATH]
               [NO_CMAKE_INSTALL_PREFIX]
               [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
               [CMAKE_FIND_ROOT_PATH_BOTH |
                ONLY_CMAKE_FIND_ROOT_PATH |
                NO_CMAKE_FIND_ROOT_PATH])

The ``CONFIG`` option, the synonymous ``NO_MODULE`` option, or the use
of options not specified in the `basic signature`_ all enforce pure Config
mode.  In pure Config mode, the command skips Module mode search and
proceeds at once with Config mode search.

Config mode search attempts to locate a configuration file provided by the
package to be found.  A cache entry called ``<PackageName>_DIR`` is created to
hold the directory containing the file.  By default, the command searches for
a package with the name ``<PackageName>``.  If the ``NAMES`` option is given,
the names following it are used instead of ``<PackageName>``.  The names are
also considered when determining whether to redirect the call to a package
provided by :module:`FetchContent`.

The command searches for a file called ``<PackageName>Config.cmake`` or
``<lowercasePackageName>-config.cmake`` for each name specified.
A replacement set of possible configuration file names may be given
using the ``CONFIGS`` option.  The :ref:`search procedure` is specified below.
Once found, any :ref:`version constraint <version selection>` is checked,
and if satisfied, the configuration file is read and processed by CMake.
Since the file is provided by the package it already knows the
location of package contents.  The full path to the configuration file
is stored in the cmake variable ``<PackageName>_CONFIG``.

All configuration files which have been considered by CMake while
searching for the package with an appropriate version are stored in the
``<PackageName>_CONSIDERED_CONFIGS`` variable, and the associated versions
in the ``<PackageName>_CONSIDERED_VERSIONS`` variable.

If the package configuration file cannot be found CMake will generate
an error describing the problem unless the ``QUIET`` argument is
specified.  If ``REQUIRED`` is specified and the package is not found a
fatal error is generated and the configure step stops executing.  If
``<PackageName>_DIR`` has been set to a directory not containing a
configuration file CMake will ignore it and search from scratch.

Package maintainers providing CMake package configuration files are
encouraged to name and install them such that the :ref:`search procedure`
outlined below will find them without requiring use of additional options.

.. _`search procedure`:

Config Mode Search Procedure
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
  When Config mode is used, this search procedure is applied regardless of
  whether the :ref:`full <full signature>` or :ref:`basic <basic signature>`
  signature was given.

.. versionadded:: 3.24
  All calls to ``find_package()`` (even in Module mode) first look for a config
  package file in the :variable:`CMAKE_FIND_PACKAGE_REDIRECTS_DIR` directory.
  The :module:`FetchContent` module, or even the project itself, may write files
  to that location to redirect ``find_package()`` calls to content already
  provided by the project.  If no config package file is found in that location,
  the search proceeds with the logic described below.

CMake constructs a set of possible installation prefixes for the
package.  Under each prefix several directories are searched for a
configuration file.  The tables below show the directories searched.
Each entry is meant for installation trees following Windows (``W``), UNIX
(``U``), or Apple (``A``) conventions:

==================================================================== ==========
 Entry                                                               Convention
==================================================================== ==========
 ``<prefix>/``                                                          W
 ``<prefix>/(cmake|CMake)/``                                            W
 ``<prefix>/<name>*/``                                                  W
 ``<prefix>/<name>*/(cmake|CMake)/``                                    W
 ``<prefix>/<name>*/(cmake|CMake)/<name>*/`` [#]_                       W
 ``<prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/``                    U
 ``<prefix>/(lib/<arch>|lib*|share)/<name>*/``                          U
 ``<prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/``            U
 ``<prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/``            W/U
 ``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/``                  W/U
 ``<prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/``    W/U
==================================================================== ==========

.. [#] .. versionadded:: 3.25

On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the
following directories are searched for Frameworks or Application Bundles
containing a configuration file:

=========================================================== ==========
 Entry                                                      Convention
=========================================================== ==========
 ``<prefix>/<name>.framework/Resources/``                      A
 ``<prefix>/<name>.framework/Resources/CMake/``                A
 ``<prefix>/<name>.framework/Versions/*/Resources/``           A
 ``<prefix>/<name>.framework/Versions/*/Resources/CMake/``     A
 ``<prefix>/<name>.app/Contents/Resources/``                   A
 ``<prefix>/<name>.app/Contents/Resources/CMake/``             A
=========================================================== ==========

In all cases the ``<name>`` is treated as case-insensitive and corresponds
to any of the names specified (``<PackageName>`` or names given by ``NAMES``).

If at least one compiled language has been enabled, the architecture-specific
``lib/<arch>`` and ``lib*`` directories may be searched based on the compiler's
target architecture, in the following order:

``lib/<arch>``
  Searched if the :variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set.

``lib64``
  Searched on 64 bit platforms (:variable:`CMAKE_SIZEOF_VOID_P` is 8) and the
  :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``.

``lib32``
  Searched on 32 bit platforms (:variable:`CMAKE_SIZEOF_VOID_P` is 4) and the
  :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``.

``libx32``
  Searched on platforms using the x32 ABI
  if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``.

``lib``
  Always searched.

.. versionchanged:: 3.24
  On ``Windows`` platform, it is possible to include registry queries as part
  of the directories specified through ``HINTS`` and ``PATHS`` keywords, using
  a :ref:`dedicated syntax <Find Using Windows Registry>`. Such specifications
  will be ignored on all other platforms.

.. versionadded:: 3.24
  ``REGISTRY_VIEW`` can be specified to manage ``Windows`` registry queries
  specified as part of ``PATHS`` and ``HINTS``.

  .. include:: FIND_XXX_REGISTRY_VIEW.txt

If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
(``W``) or (``U``) directory entry one-by-one.

This set of directories is intended to work in cooperation with
projects that provide configuration files in their installation trees.
Directories above marked with (``W``) are intended for installations on
Windows where the prefix may point at the top of an application's
installation directory.  Those marked with (``U``) are intended for
installations on UNIX platforms where the prefix is shared by multiple
packages.  This is merely a convention, so all (``W``) and (``U``) directories
are still searched on all platforms.  Directories marked with (``A``) are
intended for installations on Apple platforms.  The
:variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE`
variables determine the order of preference.

The set of installation prefixes is constructed using the following
steps.  If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are
enabled.

1. Search prefixes unique to the current ``<PackageName>`` being found.
   See policy :policy:`CMP0074`.

   .. versionadded:: 3.12

   Specifically, search prefixes specified by the following variables,
   in order:

   a. :variable:`<PackageName>_ROOT` CMake variable,
      where ``<PackageName>`` is the case-preserved package name.

   b. :variable:`<PACKAGENAME>_ROOT` CMake variable,
      where ``<PACKAGENAME>`` is the upper-cased package name.
      See policy :policy:`CMP0144`.

      .. versionadded:: 3.27

   c. :envvar:`<PackageName>_ROOT` environment variable,
      where ``<PackageName>`` is the case-preserved package name.

   d. :envvar:`<PACKAGENAME>_ROOT` environment variable,
      where ``<PACKAGENAME>`` is the upper-cased package name.
      See policy :policy:`CMP0144`.

      .. versionadded:: 3.27

   The package root variables are maintained as a stack so if
   called from within a find module, root paths from the parent's find
   module will also be searched after paths for the current package.
   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
   the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.

2. Search paths specified in cmake-specific cache variables.  These
   are intended to be used on the command line with a :option:`-DVAR=VALUE <cmake -D>`.
   The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
   This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``:

   * :variable:`CMAKE_PREFIX_PATH`
   * :variable:`CMAKE_FRAMEWORK_PATH`
   * :variable:`CMAKE_APPBUNDLE_PATH`

3. Search paths specified in cmake-specific environment variables.
   These are intended to be set in the user's shell configuration,
   and therefore use the host's native path separator
   (``;`` on Windows and ``:`` on UNIX).
   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting
   the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``:

   * ``<PackageName>_DIR``
   * :envvar:`CMAKE_PREFIX_PATH`
   * :envvar:`CMAKE_FRAMEWORK_PATH`
   * :envvar:`CMAKE_APPBUNDLE_PATH`

4. Search paths specified by the ``HINTS`` option.  These should be paths
   computed by system introspection, such as a hint provided by the
   location of another item already found.  Hard-coded guesses should
   be specified with the ``PATHS`` option.

5. Search the standard system environment variables.  This can be
   skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed  or by setting the
   :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries
   ending in ``/bin`` or ``/sbin`` are automatically converted to their
   parent directories:

   * ``PATH``

6. Search paths stored in the CMake :ref:`User Package Registry`.
   This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
   setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY`
   to ``FALSE`` or the deprecated variable
   :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``.

   See the :manual:`cmake-packages(7)` manual for details on the user
   package registry.

7. Search cmake variables defined in the Platform files for the
   current system. The searching of :variable:`CMAKE_INSTALL_PREFIX` and
   :variable:`CMAKE_STAGING_PREFIX` can be
   skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
   :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations
   can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
   :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``:

   * :variable:`CMAKE_SYSTEM_PREFIX_PATH`
   * :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
   * :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`

   The platform paths that these variables contain are locations that
   typically include installed software. An example being ``/usr/local`` for
   UNIX based platforms.

8. Search paths stored in the CMake :ref:`System Package Registry`.
   This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
   or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY`
   variable to ``FALSE`` or the deprecated variable
   :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.

   See the :manual:`cmake-packages(7)` manual for details on the system
   package registry.

9. Search paths specified by the ``PATHS`` option.  These are typically
   hard-coded guesses.

The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
:variable:`CMAKE_SYSTEM_IGNORE_PATH` and
:variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
of the above locations to be ignored.

.. versionadded:: 3.16
   Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable
   various search locations.

.. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt

By default the value stored in the result variable will be the path at
which the file is found.  The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS`
variable may be set to ``TRUE`` before calling ``find_package`` in order
to resolve symbolic links and store the real path to the file.

Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED:

* Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable
  to ``TRUE`` disables the package.  This also disables redirection to a
  package provided by :module:`FetchContent`.

* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable
  to ``TRUE`` makes the package REQUIRED.

Setting both variables to ``TRUE`` simultaneously is an error.

.. _`version selection`:

Config Mode Version Selection
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. note::
  When Config mode is used, this version selection process is applied
  regardless of whether the :ref:`full <full signature>` or
  :ref:`basic <basic signature>` signature was given.

When the ``[version]`` argument is given, Config mode will only find a
version of the package that claims compatibility with the requested
version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the
``EXACT`` option is given, only a version of the package claiming an exact match
of the requested version may be found.  CMake does not establish any
convention for the meaning of version numbers.  Package version
numbers are checked by "version" files provided by the packages themselves
or by :module:`FetchContent`.  For a candidate package configuration file
``<config-file>.cmake`` the corresponding version file is located next
to it and named either ``<config-file>-version.cmake`` or
``<config-file>Version.cmake``.  If no such version file is available
then the configuration file is assumed to not be compatible with any
requested version.  A basic version file containing generic version
matching code can be created using the
:module:`CMakePackageConfigHelpers` module.  When a version file
is found it is loaded to check the requested version number.  The
version file is loaded in a nested scope in which the following
variables have been defined:

``PACKAGE_FIND_NAME``
  The ``<PackageName>``
``PACKAGE_FIND_VERSION``
  Full requested version string
``PACKAGE_FIND_VERSION_MAJOR``
  Major version if requested, else 0
``PACKAGE_FIND_VERSION_MINOR``
  Minor version if requested, else 0
``PACKAGE_FIND_VERSION_PATCH``
  Patch version if requested, else 0
``PACKAGE_FIND_VERSION_TWEAK``
  Tweak version if requested, else 0
``PACKAGE_FIND_VERSION_COUNT``
  Number of version components, 0 to 4

When a version range is specified, the above version variables will hold
values based on the lower end of the version range.  This is to preserve
compatibility with packages that have not been implemented to expect version
ranges.  In addition, the version range will be described by the following
variables:

``PACKAGE_FIND_VERSION_RANGE``
  Full requested version range string
``PACKAGE_FIND_VERSION_RANGE_MIN``
  This specifies whether the lower end point of the version range should be
  included or excluded.  Currently, the only supported value for this variable
  is ``INCLUDE``.
``PACKAGE_FIND_VERSION_RANGE_MAX``
  This specifies whether the upper end point of the version range should be
  included or excluded.  The supported values for this variable are
  ``INCLUDE`` and ``EXCLUDE``.

``PACKAGE_FIND_VERSION_MIN``
  Full requested version string of the lower end point of the range
``PACKAGE_FIND_VERSION_MIN_MAJOR``
  Major version of the lower end point if requested, else 0
``PACKAGE_FIND_VERSION_MIN_MINOR``
  Minor version of the lower end point if requested, else 0
``PACKAGE_FIND_VERSION_MIN_PATCH``
  Patch version of the lower end point if requested, else 0
``PACKAGE_FIND_VERSION_MIN_TWEAK``
  Tweak version of the lower end point if requested, else 0
``PACKAGE_FIND_VERSION_MIN_COUNT``
  Number of version components of the lower end point, 0 to 4

``PACKAGE_FIND_VERSION_MAX``
  Full requested version string of the upper end point of the range
``PACKAGE_FIND_VERSION_MAX_MAJOR``
  Major version of the upper end point if requested, else 0
``PACKAGE_FIND_VERSION_MAX_MINOR``
  Minor version of the upper end point if requested, else 0
``PACKAGE_FIND_VERSION_MAX_PATCH``
  Patch version of the upper end point if requested, else 0
``PACKAGE_FIND_VERSION_MAX_TWEAK``
  Tweak version of the upper end point if requested, else 0
``PACKAGE_FIND_VERSION_MAX_COUNT``
  Number of version components of the upper end point, 0 to 4

Regardless of whether a single version or a version range is specified, the
variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold
the full requested version string as specified.

The version file checks whether it satisfies the requested version and
sets these variables:

``PACKAGE_VERSION``
  Full provided version string
``PACKAGE_VERSION_EXACT``
  True if version is exact match
``PACKAGE_VERSION_COMPATIBLE``
  True if version is compatible
``PACKAGE_VERSION_UNSUITABLE``
  True if unsuitable as any version

These variables are checked by the ``find_package`` command to determine
whether the configuration file provides an acceptable version.  They
are not available after the ``find_package`` call returns.  If the version
is acceptable the following variables are set:

``<PackageName>_VERSION``
  Full provided version string
``<PackageName>_VERSION_MAJOR``
  Major version if provided, else 0
``<PackageName>_VERSION_MINOR``
  Minor version if provided, else 0
``<PackageName>_VERSION_PATCH``
  Patch version if provided, else 0
``<PackageName>_VERSION_TWEAK``
  Tweak version if provided, else 0
``<PackageName>_VERSION_COUNT``
  Number of version components, 0 to 4

and the corresponding package configuration file is loaded.
When multiple package configuration files are available whose version files
claim compatibility with the version requested it is unspecified which
one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
is set no attempt is made to choose a highest or closest version number.

To control the order in which ``find_package`` checks for compatibility use
the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
For instance in order to select the highest version one can set

.. code-block:: cmake

  SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
  SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)

before calling ``find_package``.

Package File Interface Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

When loading a find module or package configuration file ``find_package``
defines variables to provide information about the call arguments (and
restores their original state before returning):

``CMAKE_FIND_PACKAGE_NAME``
  The ``<PackageName>`` which is searched for
``<PackageName>_FIND_REQUIRED``
  True if ``REQUIRED`` option was given
``<PackageName>_FIND_QUIETLY``
  True if ``QUIET`` option was given
``<PackageName>_FIND_REGISTRY_VIEW``
  The requested view if ``REGISTRY_VIEW`` option was given
``<PackageName>_FIND_VERSION``
  Full requested version string
``<PackageName>_FIND_VERSION_MAJOR``
  Major version if requested, else 0
``<PackageName>_FIND_VERSION_MINOR``
  Minor version if requested, else 0
``<PackageName>_FIND_VERSION_PATCH``
  Patch version if requested, else 0
``<PackageName>_FIND_VERSION_TWEAK``
  Tweak version if requested, else 0
``<PackageName>_FIND_VERSION_COUNT``
  Number of version components, 0 to 4
``<PackageName>_FIND_VERSION_EXACT``
  True if ``EXACT`` option was given
``<PackageName>_FIND_COMPONENTS``
  List of specified components (required and optional)
``<PackageName>_FIND_REQUIRED_<c>``
  True if component ``<c>`` is required,
  false if component ``<c>`` is optional

When a version range is specified, the above version variables will hold
values based on the lower end of the version range.  This is to preserve
compatibility with packages that have not been implemented to expect version
ranges.  In addition, the version range will be described by the following
variables:

``<PackageName>_FIND_VERSION_RANGE``
  Full requested version range string
``<PackageName>_FIND_VERSION_RANGE_MIN``
  This specifies whether the lower end point of the version range is
  included or excluded.  Currently, ``INCLUDE`` is the only supported value.
``<PackageName>_FIND_VERSION_RANGE_MAX``
  This specifies whether the upper end point of the version range is
  included or excluded.  The possible values for this variable are
  ``INCLUDE`` or ``EXCLUDE``.

``<PackageName>_FIND_VERSION_MIN``
  Full requested version string of the lower end point of the range
``<PackageName>_FIND_VERSION_MIN_MAJOR``
  Major version of the lower end point if requested, else 0
``<PackageName>_FIND_VERSION_MIN_MINOR``
  Minor version of the lower end point if requested, else 0
``<PackageName>_FIND_VERSION_MIN_PATCH``
  Patch version of the lower end point if requested, else 0
``<PackageName>_FIND_VERSION_MIN_TWEAK``
  Tweak version of the lower end point if requested, else 0
``<PackageName>_FIND_VERSION_MIN_COUNT``
  Number of version components of the lower end point, 0 to 4

``<PackageName>_FIND_VERSION_MAX``
  Full requested version string of the upper end point of the range
``<PackageName>_FIND_VERSION_MAX_MAJOR``
  Major version of the upper end point if requested, else 0
``<PackageName>_FIND_VERSION_MAX_MINOR``
  Minor version of the upper end point if requested, else 0
``<PackageName>_FIND_VERSION_MAX_PATCH``
  Patch version of the upper end point if requested, else 0
``<PackageName>_FIND_VERSION_MAX_TWEAK``
  Tweak version of the upper end point if requested, else 0
``<PackageName>_FIND_VERSION_MAX_COUNT``
  Number of version components of the upper end point, 0 to 4

Regardless of whether a single version or a version range is specified, the
variable ``<PackageName>_FIND_VERSION_COMPLETE`` will be defined and will hold
the full requested version string as specified.

In Module mode the loaded find module is responsible to honor the
request detailed by these variables; see the find module for details.
In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and
``[version]`` options automatically but leaves it to the package
configuration file to handle components in a way that makes sense
for the package.  The package configuration file may set
``<PackageName>_FOUND`` to false to tell ``find_package`` that component
requirements are not satisfied.


code:
find_path
---------

.. |FIND_XXX| replace:: find_path
.. |NAMES| replace:: NAMES name1 [name2 ...]
.. |SEARCH_XXX| replace:: file in a directory
.. |SEARCH_XXX_DESC| replace:: directory containing the named file
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``

.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``TARGET``

.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`

.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
   and |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_INCLUDE_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_FRAMEWORK_PATH`

.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``INCLUDE``
   and ``PATH``.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace::
   On Windows hosts, CMake 3.3 through 3.27 searched additional paths:
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|.
   This behavior was removed by CMake 3.28.

.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   ``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
   is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
   :variable:`CMAKE_SYSTEM_INCLUDE_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
   :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`

.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
   :variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`

.. include:: FIND_XXX.txt

When searching for frameworks, if the file is specified as ``A/b.h``, then
the framework search will look for ``A.framework/Headers/b.h``.  If that
is found the path will be set to the path to the framework.  CMake
will convert this to the correct ``-F`` option to include the file.


code:
find_program
------------

.. |FIND_XXX| replace:: find_program
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
.. |SEARCH_XXX| replace:: program
.. |SEARCH_XXX_DESC| replace:: program
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
.. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin``

.. |FIND_XXX_REGISTRY_VIEW_DEFAULT| replace:: ``BOTH``

.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX| replace::
   |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_PREFIX_PATH_XXX| replace::
   |CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH`

.. |ENV_CMAKE_PREFIX_PATH_XXX| replace::
   |ENV_CMAKE_PREFIX_PATH_XXX_SUBDIR|
.. |ENV_CMAKE_XXX_PATH| replace:: :envvar:`CMAKE_PROGRAM_PATH`
.. |ENV_CMAKE_XXX_MAC_PATH| replace:: :envvar:`CMAKE_APPBUNDLE_PATH`

.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: The directories in ``PATH`` itself.
.. |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX| replace:: \

.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
   |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
.. |CMAKE_SYSTEM_XXX_PATH| replace::
   :variable:`CMAKE_SYSTEM_PROGRAM_PATH`
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
   :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`

.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
   :variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM`

.. include:: FIND_XXX.txt

When more than one value is given to the ``NAMES`` option this command by
default will consider one name at a time and search every directory
for it.  The ``NAMES_PER_DIR`` option tells this command to consider one
directory at a time and search for all names in it.


code:
fltk_wrap_ui
------------

Create FLTK user interfaces Wrappers.

.. code-block:: cmake

  fltk_wrap_ui(resultingLibraryName source1
               source2 ... sourceN )

Produce .h and .cxx files for all the .fl and .fld files listed.  The
resulting .h and .cxx files will be added to a variable named
``resultingLibraryName_FLTK_UI_SRCS`` which should be added to your
library.


code:
foreach
-------

Evaluate a group of commands for each value in a list.

.. code-block:: cmake

  foreach(<loop_var> <items>)
    <commands>
  endforeach()

where ``<items>`` is a list of items that are separated by
semicolon or whitespace.
All commands between ``foreach`` and the matching ``endforeach`` are recorded
without being invoked.  Once the ``endforeach`` is evaluated, the recorded
list of commands is invoked once for each item in ``<items>``.
At the beginning of each iteration the variable ``<loop_var>`` will be set
to the value of the current item.

The scope of ``<loop_var>`` is restricted to the loop scope. See policy
:policy:`CMP0124` for details.

The commands :command:`break` and :command:`continue` provide means to
escape from the normal control flow.

Per legacy, the :command:`endforeach` command admits
an optional ``<loop_var>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``foreach`` command.

.. code-block:: cmake

  foreach(<loop_var> RANGE <stop>)

In this variant, ``foreach`` iterates over the numbers
0, 1, ... up to (and including) the nonnegative integer ``<stop>``.

.. code-block:: cmake

  foreach(<loop_var> RANGE <start> <stop> [<step>])

In this variant, ``foreach`` iterates over the numbers from
``<start>`` up to at most ``<stop>`` in steps of ``<step>``.
If ``<step>`` is not specified, then the step size is 1.
The three arguments ``<start>`` ``<stop>`` ``<step>`` must
all be nonnegative integers, and ``<stop>`` must not be
smaller than ``<start>``; otherwise you enter the danger zone
of undocumented behavior that may change in future releases.

.. code-block:: cmake

  foreach(<loop_var> IN [LISTS [<lists>]] [ITEMS [<items>]])

In this variant, ``<lists>`` is a whitespace or semicolon
separated list of list-valued variables. The ``foreach``
command iterates over each item in each given list.
The ``<items>`` following the ``ITEMS`` keyword are processed
as in the first variant of the ``foreach`` command.
The forms ``LISTS A`` and ``ITEMS ${A}`` are
equivalent.

The following example shows how the ``LISTS`` option is
processed:

.. code-block:: cmake

  set(A 0;1)
  set(B 2 3)
  set(C "4 5")
  set(D 6;7 8)
  set(E "")
  foreach(X IN LISTS A B C D E)
      message(STATUS "X=${X}")
  endforeach()

yields::

  -- X=0
  -- X=1
  -- X=2
  -- X=3
  -- X=4 5
  -- X=6
  -- X=7
  -- X=8

.. code-block:: cmake

  foreach(<loop_var>... IN ZIP_LISTS <lists>)

.. versionadded:: 3.17

In this variant, ``<lists>`` is a whitespace or semicolon
separated list of list-valued variables. The ``foreach``
command iterates over each list simultaneously setting the
iteration variables as follows:

- if the only ``loop_var`` given, then it sets a series of
  ``loop_var_N`` variables to the current item from the
  corresponding list;
- if multiple variable names passed, their count should match
  the lists variables count;
- if any of the lists are shorter, the corresponding iteration
  variable is not defined for the current iteration.

.. code-block:: cmake

  list(APPEND English one two three four)
  list(APPEND Bahasa satu dua tiga)

  foreach(num IN ZIP_LISTS English Bahasa)
      message(STATUS "num_0=${num_0}, num_1=${num_1}")
  endforeach()

  foreach(en ba IN ZIP_LISTS English Bahasa)
      message(STATUS "en=${en}, ba=${ba}")
  endforeach()

yields::

  -- num_0=one, num_1=satu
  -- num_0=two, num_1=dua
  -- num_0=three, num_1=tiga
  -- num_0=four, num_1=
  -- en=one, ba=satu
  -- en=two, ba=dua
  -- en=three, ba=tiga
  -- en=four, ba=

See Also
^^^^^^^^

* :command:`break`
* :command:`continue`
* :command:`endforeach`
* :command:`while`