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.

repo_name: lazytadpole/codenamesilverfish

license: mit


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`


code:
function
--------

Start recording a function for later invocation as a command.

.. code-block:: cmake

  function(<name> [<arg1> ...])
    <commands>
  endfunction()

Defines a function named ``<name>`` that takes arguments named
``<arg1>``, ...  The ``<commands>`` in the function definition
are recorded; they are not executed until the function is invoked.

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

A function opens a new scope: see :command:`set(var PARENT_SCOPE)` for
details.

See the :command:`cmake_policy()` command documentation for the behavior
of policies inside functions.

See the :command:`macro()` command documentation for differences
between CMake functions and macros.

Invocation
^^^^^^^^^^

The function invocation is case-insensitive. A function defined as

.. code-block:: cmake

  function(foo)
    <commands>
  endfunction()

can be invoked through any of

.. code-block:: cmake

  foo()
  Foo()
  FOO()
  cmake_language(CALL foo)

and so on. However, it is strongly recommended to stay with the
case chosen in the function definition. Typically functions use
all-lowercase names.

.. versionadded:: 3.18
  The :command:`cmake_language(CALL ...)` command can also be used to
  invoke the function.

Arguments
^^^^^^^^^

When the function is invoked, the recorded ``<commands>`` are first
modified by replacing formal parameters (``${arg1}``, ...) with the
arguments passed, and then invoked as normal commands.

In addition to referencing the formal parameters you can reference the
``ARGC`` variable which will be set to the number of arguments passed
into the function as well as ``ARGV0``, ``ARGV1``, ``ARGV2``, ...  which
will have the actual values of the arguments passed in.  This facilitates
creating functions with optional arguments.

Furthermore, ``ARGV`` holds the list of all arguments given to the
function and ``ARGN`` holds the list of arguments past the last expected
argument.  Referencing to ``ARGV#`` arguments beyond ``ARGC`` have
undefined behavior.  Checking that ``ARGC`` is greater than ``#`` is
the only way to ensure that ``ARGV#`` was passed to the function as an
extra argument.

See Also
^^^^^^^^

* :command:`cmake_parse_arguments`
* :command:`endfunction`
* :command:`return`


code:
get_cmake_property
------------------

Get a global property of the CMake instance.

.. code-block:: cmake

  get_cmake_property(<variable> <property>)

Gets a global property from the CMake instance.  The value of
the ``<property>`` is stored in the specified ``<variable>``.
If the property is not found, ``<variable>`` will be set to ``NOTFOUND``.
See the :manual:`cmake-properties(7)` manual for available properties.

In addition to global properties, this command (for historical reasons)
also supports the :prop_dir:`VARIABLES` and :prop_dir:`MACROS` directory
properties.  It also supports a special ``COMPONENTS`` global property that
lists the components given to the :command:`install` command.

See Also
^^^^^^^^

* the :command:`get_property` command ``GLOBAL`` option


code:
get_directory_property
----------------------

Get a property of ``DIRECTORY`` scope.

.. code-block:: cmake

  get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)

Stores a property of directory scope in the named ``<variable>``.

The ``DIRECTORY`` argument specifies another directory from which
to retrieve the property value instead of the current directory.
Relative paths are treated as relative to the
current source directory.  CMake must already know about the directory,
either by having added it through a call to :command:`add_subdirectory`
or being the top level directory.

.. versionadded:: 3.19
  ``<dir>`` may reference a binary directory.

If the property is not defined for the nominated directory scope,
an empty string is returned.  In the case of ``INHERITED`` properties,
if the property is not found for the nominated directory scope,
the search will chain to a parent scope as described for the
:command:`define_property` command.

.. code-block:: cmake

  get_directory_property(<variable> [DIRECTORY <dir>]
                         DEFINITION <var-name>)

Get a variable definition from a directory.  This form is useful to
get a variable definition from another directory.

See Also
^^^^^^^^

* :command:`define_property`
* the more general :command:`get_property` command


code:
get_filename_component
----------------------

Get a specific component of a full filename.

.. versionchanged:: 3.20
  This command has been superseded by the :command:`cmake_path` command, except
  for ``REALPATH``, which is now offered by :command:`file(REAL_PATH)`, and
  ``PROGRAM``, now available in :command:`separate_arguments(PROGRAM)`.

.. versionchanged:: 3.24
  The undocumented feature offering the capability to query the ``Windows``
  registry is superseded by
  :ref:`cmake_host_system_information(QUERY WINDOWS_REGISTRY)<Query Windows registry>`
  command.

.. code-block:: cmake

  get_filename_component(<var> <FileName> <mode> [CACHE])

Sets ``<var>`` to a component of ``<FileName>``, where ``<mode>`` is one of:

::

 DIRECTORY = Directory without file name
 NAME      = File name without directory
 EXT       = File name longest extension (.b.c from d/a.b.c)
 NAME_WE   = File name with neither the directory nor the longest extension
 LAST_EXT  = File name last extension (.c from d/a.b.c)
 NAME_WLE  = File name with neither the directory nor the last extension
 PATH      = Legacy alias for DIRECTORY (use for CMake <= 2.8.11)

.. versionadded:: 3.14
  Added the ``LAST_EXT`` and ``NAME_WLE`` modes.

Paths are returned with forward slashes and have no trailing slashes.
If the optional ``CACHE`` argument is specified, the result variable is
added to the cache.

.. code-block:: cmake

  get_filename_component(<var> <FileName> <mode> [BASE_DIR <dir>] [CACHE])

.. versionadded:: 3.4

Sets ``<var>`` to the absolute path of ``<FileName>``, where ``<mode>`` is one
of:

::

 ABSOLUTE  = Full path to file
 REALPATH  = Full path to existing file with symlinks resolved

If the provided ``<FileName>`` 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`.

Paths are returned with forward slashes and have no trailing slashes.  If the
optional ``CACHE`` argument is specified, the result variable is added to the
cache.

.. code-block:: cmake

  get_filename_component(<var> <FileName> PROGRAM [PROGRAM_ARGS <arg_var>] [CACHE])

The program in ``<FileName>`` will be found in the system search path or
left as a full path.  If ``PROGRAM_ARGS`` is present with ``PROGRAM``, then
any command-line arguments present in the ``<FileName>`` string are split
from the program name and stored in ``<arg_var>``.  This is used to
separate a program name from its arguments in a command line string.

See Also
^^^^^^^^

* :command:`cmake_path`


code:
get_property
------------

Get a property.

.. code-block:: cmake

  get_property(<variable>
               <GLOBAL             |
                DIRECTORY [<dir>]  |
                TARGET    <target> |
                SOURCE    <source>
                          [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
                INSTALL   <file>   |
                TEST      <test>
                          [DIRECTORY <dir>] |
                CACHE     <entry>  |
                VARIABLE           >
               PROPERTY <name>
               [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])

Gets one property from one object in a scope.

The first argument specifies the variable in which to store the result.
The second argument determines the scope from which to get the property.
It must be one of the following:

``GLOBAL``
  Scope is unique and does not accept a name.

``DIRECTORY``
  Scope defaults to the current directory but another
  directory (already processed by CMake) may be named by the
  full or relative path ``<dir>``.
  Relative paths are treated as relative to the current source directory.
  See also the :command:`get_directory_property` command.

  .. versionadded:: 3.19
    ``<dir>`` may reference a binary directory.

``TARGET``
  Scope must name one existing target.
  See also the :command:`get_target_property` command.

``SOURCE``
  Scope must name one source file.  By default, the source file's property
  will be read from the current source directory's scope.

  .. versionadded:: 3.18
    Directory scope can be overridden with one of the following sub-options:

    ``DIRECTORY <dir>``
      The source file property will be read from the ``<dir>`` directory's
      scope.  CMake must already know about
      the directory, either by having added it through a call
      to :command:`add_subdirectory` or ``<dir>`` being the top level directory.
      Relative paths are treated as relative to the current source directory.

      .. versionadded:: 3.19
        ``<dir>`` may reference a binary directory.

    ``TARGET_DIRECTORY <target>``
      The source file property will be read from the directory scope in which
      ``<target>`` was created (``<target>`` must therefore already exist).

  See also the :command:`get_source_file_property` command.

``INSTALL``
  .. versionadded:: 3.1

  Scope must name one installed file path.

``TEST``
  Scope must name one existing test.
  See also the :command:`get_test_property` command.

  .. versionadded:: 3.28
    Directory scope can be overridden with the following sub-option:

    ``DIRECTORY <dir>``
      The test property will be read from the ``<dir>`` directory's
      scope.  CMake must already know about the directory, either by having added
      it through a call to :command:`add_subdirectory` or ``<dir>`` being the top
      level directory. Relative paths are treated as relative to the current
      source directory. ``<dir>`` may reference a binary directory.

``CACHE``
  Scope must name one cache entry.

``VARIABLE``
  Scope is unique and does not accept a name.

The required ``PROPERTY`` option is immediately followed by the name of
the property to get.  If the property is not set an empty value is
returned, although some properties support inheriting from a parent scope
if defined to behave that way (see :command:`define_property`).

If the ``SET`` option is given the variable is set to a boolean
value indicating whether the property has been set.  If the ``DEFINED``
option is given the variable is set to a boolean value indicating
whether the property has been defined such as with the
:command:`define_property` command.

If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
string containing documentation for the requested property.  If
documentation is requested for a property that has not been defined
``NOTFOUND`` is returned.

.. note::

  The :prop_sf:`GENERATED` source file property may be globally visible.
  See its documentation for details.

See Also
^^^^^^^^

* :command:`define_property`
* :command:`set_property`


code:
get_source_file_property
------------------------

Get a property for a source file.

.. code-block:: cmake

  get_source_file_property(<variable> <file>
                           [DIRECTORY <dir> | TARGET_DIRECTORY <target>]
                           <property>)

Gets a property from a source file.  The value of the property is stored in
the specified ``<variable>``.  If the ``<file>`` is not a source file, or the
source property is not found, ``<variable>`` will be set to ``NOTFOUND``.
If the source property was defined to be an ``INHERITED`` property (see
:command:`define_property`), the search will include the relevant parent
scopes, as described for the :command:`define_property` command.

By default, the source file's property will be read from the current source
directory's scope.

.. versionadded:: 3.18
  Directory scope can be overridden with one of the following sub-options:

  ``DIRECTORY <dir>``
    The source file property will be read from the ``<dir>`` directory's
    scope.  CMake must already know about that source directory, either by
    having added it through a call to :command:`add_subdirectory` or ``<dir>``
    being the top level source directory.  Relative paths are treated as
    relative to the current source directory.

  ``TARGET_DIRECTORY <target>``
    The source file property will be read from the directory scope in which
    ``<target>`` was created (``<target>`` must therefore already exist).

Use :command:`set_source_files_properties` to set property values.  Source
file properties usually control how the file is built. One property that is
always there is :prop_sf:`LOCATION`.

.. note::

  The :prop_sf:`GENERATED` source file property may be globally visible.
  See its documentation for details.

See Also
^^^^^^^^

* :command:`define_property`
* the more general :command:`get_property` command
* :command:`set_source_files_properties`


code:
get_target_property
-------------------

Get a property from a target.

.. code-block:: cmake

  get_target_property(<variable> <target> <property>)

Get a property from a target.  The value of the property is stored in the
specified ``<variable>``.  If the target property is not found, ``<variable>``
will be set to ``<variable>-NOTFOUND``.  If the target property was defined to
be an ``INHERITED`` property (see :command:`define_property`), the search will
include the relevant parent scopes, as described for the
:command:`define_property` command.

Use :command:`set_target_properties` to set target property values.
Properties are usually used to control how a target is built, but some
query the target instead.  This command can get properties for any
target so far created.  The targets do not need to be in the current
``CMakeLists.txt`` file.

See Also
^^^^^^^^

* :command:`define_property`
* the more general :command:`get_property` command
* :command:`set_target_properties`
* :ref:`Target Properties` for the list of properties known to CMake


code:
get_test_property
-----------------

Get a property of the test.

.. code-block:: cmake

  get_test_property(<test> <property> [DIRECTORY <dir>] <variable>)

Get a property from the test.  The value of the property is stored in
the specified ``<variable>``.  If the ``<test>`` is not defined, or the
test property is not found, ``<variable>`` will be set to ``NOTFOUND``.
If the test property was defined to be an ``INHERITED`` property (see
:command:`define_property`), the search will include the relevant parent
scopes, as described for the :command:`define_property` command.

For a list of standard properties you can type
:option:`cmake --help-property-list`.

.. versionadded:: 3.28
  Directory scope can be overridden with the following sub-option:

  ``DIRECTORY <dir>``
    The test property will be read from the ``<dir>`` directory's
    scope.  CMake must already know about that source directory, either by
    having added it through a call to :command:`add_subdirectory` or ``<dir>``
    being the top level source directory.  Relative paths are treated as
    relative to the current source directory. ``<dir>`` may reference a binary
    directory.

See Also
^^^^^^^^

* :command:`define_property`
* the more general :command:`get_property` command


code:
if
--

Conditionally execute a group of commands.

Synopsis
^^^^^^^^

.. code-block:: cmake

  if(<condition>)
    <commands>
  elseif(<condition>) # optional block, can be repeated
    <commands>
  else()              # optional block
    <commands>
  endif()

Evaluates the ``condition`` argument of the ``if`` clause according to the
`Condition syntax`_ described below. If the result is true, then the
``commands`` in the ``if`` block are executed.
Otherwise, optional ``elseif`` blocks are processed in the same way.
Finally, if no ``condition`` is true, ``commands`` in the optional ``else``
block are executed.

Per legacy, the :command:`else` and :command:`endif` commands admit
an optional ``<condition>`` argument.
If used, it must be a verbatim
repeat of the argument of the opening
``if`` command.

.. _`Condition Syntax`:

Condition Syntax
^^^^^^^^^^^^^^^^

The following syntax applies to the ``condition`` argument of
the ``if``, ``elseif`` and :command:`while` clauses.

Compound conditions are evaluated in the following order of precedence:

1. `Parentheses`_.

2. Unary tests such as `EXISTS`_, `COMMAND`_, and `DEFINED`_.

3. Binary tests such as `EQUAL`_, `LESS`_, `LESS_EQUAL`_, `GREATER`_,
   `GREATER_EQUAL`_, `STREQUAL`_, `STRLESS`_, `STRLESS_EQUAL`_,
   `STRGREATER`_, `STRGREATER_EQUAL`_, `VERSION_EQUAL`_, `VERSION_LESS`_,
   `VERSION_LESS_EQUAL`_, `VERSION_GREATER`_, `VERSION_GREATER_EQUAL`_,
   `PATH_EQUAL`_, and `MATCHES`_.

4. Unary logical operator `NOT`_.

5. Binary logical operators `AND`_ and `OR`_, from left to right,
   without any short-circuit.

Basic Expressions
"""""""""""""""""

.. signature:: if(<constant>)
  :target: constant

  True if the constant is ``1``, ``ON``, ``YES``, ``TRUE``, ``Y``,
  or a non-zero number (including floating point numbers).
  False if the constant is ``0``, ``OFF``,
  ``NO``, ``FALSE``, ``N``, ``IGNORE``, ``NOTFOUND``, the empty string,
  or ends in the suffix ``-NOTFOUND``.  Named boolean constants are
  case-insensitive.  If the argument is not one of these specific
  constants, it is treated as a variable or string (see `Variable Expansion`_
  further below) and one of the following two forms applies.

.. signature:: if(<variable>)
  :target: variable

  True if given a variable that is defined to a value that is not a false
  constant.  False otherwise, including if the variable is undefined.
  Note that macro arguments are not variables.
  :ref:`Environment Variables <CMake Language Environment Variables>` also
  cannot be tested this way, e.g. ``if(ENV{some_var})`` will always evaluate
  to false.

.. signature:: if(<string>)
  :target: string

  A quoted string always evaluates to false unless:

  * The string's value is one of the true constants, or
  * Policy :policy:`CMP0054` is not set to ``NEW`` and the string's value
    happens to be a variable name that is affected by :policy:`CMP0054`'s
    behavior.

Logic Operators
"""""""""""""""

.. signature:: if(NOT <condition>)

  True if the condition is not true.

.. signature:: if(<cond1> AND <cond2>)
  :target: AND

  True if both conditions would be considered true individually.

.. signature:: if(<cond1> OR <cond2>)
  :target: OR

  True if either condition would be considered true individually.

.. signature:: if((condition) AND (condition OR (condition)))
  :target: parentheses

  The conditions inside the parenthesis are evaluated first and then
  the remaining condition is evaluated as in the other examples.
  Where there are nested parenthesis the innermost are evaluated as part
  of evaluating the condition that contains them.

Existence Checks
""""""""""""""""

.. signature:: if(COMMAND <command-name>)

  True if the given name is a command, macro or function that can be
  invoked.

.. signature:: if(POLICY <policy-id>)

  True if the given name is an existing policy (of the form ``CMP<NNNN>``).

.. signature:: if(TARGET <target-name>)

  True if the given name is an existing logical target name created
  by a call to the :command:`add_executable`, :command:`add_library`,
  or :command:`add_custom_target` command that has already been invoked
  (in any directory).

.. signature:: if(TEST <test-name>)

  .. versionadded:: 3.3

  True if the given name is an existing test name created by the
  :command:`add_test` command.

.. signature:: if(DEFINED <name>|CACHE{<name>}|ENV{<name>})

  True if a variable, cache variable or environment variable
  with given ``<name>`` is defined. The value of the variable
  does not matter. Note the following caveats:

  * Macro arguments are not variables.
  * It is not possible to test directly whether a `<name>` is a non-cache
    variable.  The expression ``if(DEFINED someName)`` will evaluate to true
    if either a cache or non-cache variable ``someName`` exists.  In
    comparison, the expression ``if(DEFINED CACHE{someName})`` will only
    evaluate to true if a cache variable ``someName`` exists.  Both expressions
    need to be tested if you need to know whether a non-cache variable exists:
    ``if(DEFINED someName AND NOT DEFINED CACHE{someName})``.

 .. versionadded:: 3.14
  Added support for ``CACHE{<name>}`` variables.

.. signature:: if(<variable|string> IN_LIST <variable>)
  :target: IN_LIST

  .. versionadded:: 3.3

  True if the given element is contained in the named list variable.

File Operations
"""""""""""""""

.. signature:: if(EXISTS <path-to-file-or-directory>)

  True if the named file or directory exists and is readable.  Behavior
  is well-defined only for explicit full paths (a leading ``~/`` is not
  expanded as a home directory and is considered a relative path).
  Resolves symbolic links, i.e. if the named file or directory is a
  symbolic link, returns true if the target of the symbolic link exists.

  False if the given path is an empty string.

  .. note::
    Prefer ``if(IS_READABLE)`` to check file readability.  ``if(EXISTS)``
    may be changed in the future to to only check file existence.

.. signature:: if(IS_READABLE <path-to-file-or-directory>)

  .. versionadded:: 3.29

  True if the named file or directory is readable.  Behavior
  is well-defined only for explicit full paths (a leading ``~/`` is not
  expanded as a home directory and is considered a relative path).
  Resolves symbolic links, i.e. if the named file or directory is a
  symbolic link, returns true if the target of the symbolic link is readable.

  False if the given path is an empty string.

.. signature:: if(IS_WRITABLE <path-to-file-or-directory>)

  .. versionadded:: 3.29

  True if the named file or directory is writable.  Behavior
  is well-defined only for explicit full paths (a leading ``~/`` is not
  expanded as a home directory and is considered a relative path).
  Resolves symbolic links, i.e. if the named file or directory is a
  symbolic link, returns true if the target of the symbolic link is writable.

  False if the given path is an empty string.

.. signature:: if(IS_EXECUTABLE <path-to-file-or-directory>)

  .. versionadded:: 3.29

  True if the named file or directory is executable.  Behavior
  is well-defined only for explicit full paths (a leading ``~/`` is not
  expanded as a home directory and is considered a relative path).
  Resolves symbolic links, i.e. if the named file or directory is a
  symbolic link, returns true if the target of the symbolic link is executable.

  False if the given path is an empty string.

.. signature:: if(<file1> IS_NEWER_THAN <file2>)
  :target: IS_NEWER_THAN

  True if ``file1`` is newer than ``file2`` or if one of the two files doesn't
  exist.  Behavior is well-defined only for full paths.  If the file
  time stamps are exactly the same, an ``IS_NEWER_THAN`` comparison returns
  true, so that any dependent build operations will occur in the event
  of a tie.  This includes the case of passing the same file name for
  both file1 and file2.

.. signature:: if(IS_DIRECTORY <path>)

  True if ``path`` is a directory.  Behavior is well-defined only
  for full paths.

  False if the given path is an empty string.

.. signature:: if(IS_SYMLINK <path>)

  True if the given path is a symbolic link.  Behavior is well-defined
  only for full paths.

.. signature:: if(IS_ABSOLUTE <path>)

  True if the given path is an absolute path.  Note the following special
  cases:

  * An empty ``path`` evaluates to false.
  * On Windows hosts, any ``path`` that begins with a drive letter and colon
    (e.g. ``C:``), a forward slash or a backslash will evaluate to true.
    This means a path like ``C:no\base\dir`` will evaluate to true, even
    though the non-drive part of the path is relative.
  * On non-Windows hosts, any ``path`` that begins with a tilde (``~``)
    evaluates to true.

Comparisons
"""""""""""

.. signature:: if(<variable|string> MATCHES <regex>)
  :target: MATCHES

  True if the given string or variable's value matches the given regular
  expression.  See :ref:`Regex Specification` for regex format.

  .. versionadded:: 3.9
   ``()`` groups are captured in :variable:`CMAKE_MATCH_<n>` variables.

.. signature:: if(<variable|string> LESS <variable|string>)
  :target: LESS

  True if the given string or variable's value parses as a real number
  (like a C ``double``) and less than that on the right.

.. signature:: if(<variable|string> GREATER <variable|string>)
  :target: GREATER

  True if the given string or variable's value parses as a real number
  (like a C ``double``) and greater than that on the right.

.. signature:: if(<variable|string> EQUAL <variable|string>)
  :target: EQUAL

  True if the given string or variable's value parses as a real number
  (like a C ``double``) and equal to that on the right.

.. signature:: if(<variable|string> LESS_EQUAL <variable|string>)
  :target: LESS_EQUAL

  .. versionadded:: 3.7

  True if the given string or variable's value parses as a real number
  (like a C ``double``) and less than or equal to that on the right.

.. signature:: if(<variable|string> GREATER_EQUAL <variable|string>)
  :target: GREATER_EQUAL

  .. versionadded:: 3.7

  True if the given string or variable's value parses as a real number
  (like a C ``double``) and greater than or equal to that on the right.

.. signature:: if(<variable|string> STRLESS <variable|string>)
  :target: STRLESS

  True if the given string or variable's value is lexicographically less
  than the string or variable on the right.

.. signature:: if(<variable|string> STRGREATER <variable|string>)
  :target: STRGREATER

  True if the given string or variable's value is lexicographically greater
  than the string or variable on the right.

.. signature:: if(<variable|string> STREQUAL <variable|string>)
  :target: STREQUAL

  True if the given string or variable's value is lexicographically equal
  to the string or variable on the right.

.. signature:: if(<variable|string> STRLESS_EQUAL <variable|string>)
  :target: STRLESS_EQUAL

  .. versionadded:: 3.7

  True if the given string or variable's value is lexicographically less
  than or equal to the string or variable on the right.

.. signature:: if(<variable|string> STRGREATER_EQUAL <variable|string>)
  :target: STRGREATER_EQUAL

  .. versionadded:: 3.7

  True if the given string or variable's value is lexicographically greater
  than or equal to the string or variable on the right.

Version Comparisons
"""""""""""""""""""

.. signature:: if(<variable|string> VERSION_LESS <variable|string>)
  :target: VERSION_LESS

  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
  Any non-integer version component or non-integer trailing part of a version
  component effectively truncates the string at that point.

.. signature:: if(<variable|string> VERSION_GREATER <variable|string>)
  :target: VERSION_GREATER

  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
  Any non-integer version component or non-integer trailing part of a version
  component effectively truncates the string at that point.

.. signature:: if(<variable|string> VERSION_EQUAL <variable|string>)
  :target: VERSION_EQUAL

  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
  Any non-integer version component or non-integer trailing part of a version
  component effectively truncates the string at that point.

.. signature:: if(<variable|string> VERSION_LESS_EQUAL <variable|string>)
  :target: VERSION_LESS_EQUAL

  .. versionadded:: 3.7

  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
  Any non-integer version component or non-integer trailing part of a version
  component effectively truncates the string at that point.

.. signature:: if(<variable|string> VERSION_GREATER_EQUAL <variable|string>)
  :target: VERSION_GREATER_EQUAL

  .. versionadded:: 3.7

  Component-wise integer version number comparison (version format is
  ``major[.minor[.patch[.tweak]]]``, omitted components are treated as zero).
  Any non-integer version component or non-integer trailing part of a version
  component effectively truncates the string at that point.

Path Comparisons
""""""""""""""""

.. signature:: if(<variable|string> PATH_EQUAL <variable|string>)
  :target: PATH_EQUAL

  .. versionadded:: 3.24

  Compares the two paths component-by-component.  Only if every component of
  both paths match will the two paths compare equal.  Multiple path separators
  are effectively collapsed into a single separator, but note that backslashes
  are not converted to forward slashes.  No other
  :ref:`path normalization <Normalization>` is performed.

  Component-wise comparison is superior to string-based comparison due to the
  handling of multiple path separators.  In the following example, the
  expression evaluates to true using ``PATH_EQUAL``, but false with
  ``STREQUAL``:

  .. code-block:: cmake

    # comparison is TRUE
    if ("/a//b/c" PATH_EQUAL "/a/b/c")
       ...
    endif()

    # comparison is FALSE
    if ("/a//b/c" STREQUAL "/a/b/c")
       ...
    endif()

  See :ref:`cmake_path(COMPARE) <Path COMPARE>` for more details.

Variable Expansion
^^^^^^^^^^^^^^^^^^

The if command was written very early in CMake's history, predating
the ``${}`` variable evaluation syntax, and for convenience evaluates
variables named by its arguments as shown in the above signatures.
Note that normal variable evaluation with ``${}`` applies before the if
command even receives the arguments.  Therefore code like

.. code-block:: cmake

 set(var1 OFF)
 set(var2 "var1")
 if(${var2})

appears to the if command as

.. code-block:: cmake

  if(var1)

and is evaluated according to the ``if(<variable>)`` case documented
above.  The result is ``OFF`` which is false.  However, if we remove the
``${}`` from the example then the command sees

.. code-block:: cmake

  if(var2)

which is true because ``var2`` is defined to ``var1`` which is not a false
constant.

Automatic evaluation applies in the other cases whenever the
above-documented condition syntax accepts ``<variable|string>``:

* The left hand argument to `MATCHES`_ is first checked to see if it is
  a defined variable.  If so, the variable's value is used, otherwise the
  original value is used.

* If the left hand argument to `MATCHES`_ is missing it returns false
  without error

* Both left and right hand arguments to `LESS`_, `GREATER`_, `EQUAL`_,
  `LESS_EQUAL`_, and `GREATER_EQUAL`_, are independently tested to see if
  they are defined variables.  If so, their defined values are used otherwise
  the original value is used.

* Both left and right hand arguments to `STRLESS`_, `STRGREATER`_,
  `STREQUAL`_, `STRLESS_EQUAL`_, and `STRGREATER_EQUAL`_ are independently
  tested to see if they are defined variables.  If so, their defined values are
  used otherwise the original value is used.

* Both left and right hand arguments to `VERSION_LESS`_,
  `VERSION_GREATER`_, `VERSION_EQUAL`_, `VERSION_LESS_EQUAL`_, and
  `VERSION_GREATER_EQUAL`_ are independently tested to see if they are defined
  variables.  If so, their defined values are used otherwise the original value
  is used.

* The right hand argument to `NOT`_ is tested to see if it is a boolean
  constant.  If so, the value is used, otherwise it is assumed to be a
  variable and it is dereferenced.

* The left and right hand arguments to `AND`_ and `OR`_ are independently
  tested to see if they are boolean constants.  If so, they are used as
  such, otherwise they are assumed to be variables and are dereferenced.

.. versionchanged:: 3.1
  To prevent ambiguity, potential variable or keyword names can be
  specified in a :ref:`Quoted Argument` or a :ref:`Bracket Argument`.
  A quoted or bracketed variable or keyword will be interpreted as a
  string and not dereferenced or interpreted.
  See policy :policy:`CMP0054`.

There is no automatic evaluation for environment or cache
:ref:`Variable References`.  Their values must be referenced as
``$ENV{<name>}`` or ``$CACHE{<name>}`` wherever the above-documented
condition syntax accepts ``<variable|string>``.

See also
^^^^^^^^

* :command:`else`
* :command:`elseif`
* :command:`endif`


code:
include
-------

Load and run CMake code from a file or module.

.. code-block:: cmake

  include(<file|module> [OPTIONAL] [RESULT_VARIABLE <var>]
                        [NO_POLICY_SCOPE])

Loads and runs CMake code from the file given.  Variable reads and
writes access the scope of the caller (dynamic scoping).  If ``OPTIONAL``
is present, then no error is raised if the file does not exist.  If
``RESULT_VARIABLE`` is given the variable ``<var>`` will be set to the
full filename which has been included or ``NOTFOUND`` if it failed.

If a module is specified instead of a file, the file with name
``<modulename>.cmake`` is searched first in :variable:`CMAKE_MODULE_PATH`,
then in the CMake module directory.  There is one exception to this: if
the file which calls ``include()`` is located itself in the CMake builtin
module directory, then first the CMake builtin module directory is searched and
:variable:`CMAKE_MODULE_PATH` afterwards.  See also policy :policy:`CMP0017`.

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


code:
include_directories
-------------------

Add include directories to the build.

.. code-block:: cmake

  include_directories([AFTER|BEFORE] [SYSTEM] dir1 [dir2 ...])

Add the given directories to those the compiler uses to search for
include files.  Relative paths are interpreted as relative to the
current source directory.

The include directories are added to the :prop_dir:`INCLUDE_DIRECTORIES`
directory property for the current ``CMakeLists`` file.  They are also
added to the :prop_tgt:`INCLUDE_DIRECTORIES` target property for each
target in the current ``CMakeLists`` file.  The target property values
are the ones used by the generators.

By default the directories specified are appended onto the current list of
directories.  This default behavior can be changed by setting
:variable:`CMAKE_INCLUDE_DIRECTORIES_BEFORE` to ``ON``.  By using
``AFTER`` or ``BEFORE`` explicitly, you can select between appending and
prepending, independent of the default.

If the ``SYSTEM`` option is given, the compiler will be told the
directories are meant as system include directories on some platforms.
Signaling this setting might achieve effects such as the compiler
skipping warnings, or these fixed-install system files not being
considered in dependency calculations - see compiler docs.

.. |command_name| replace:: ``include_directories``
.. include:: GENEX_NOTE.txt

.. note::

  Prefer the :command:`target_include_directories` command to add include
  directories to individual targets and optionally propagate/export them
  to dependents.

See Also
^^^^^^^^

* :command:`target_include_directories`


code:
include_external_msproject
--------------------------

Include an external Microsoft project file in a workspace.

.. code-block:: cmake

  include_external_msproject(projectname location
                             [TYPE projectTypeGUID]
                             [GUID projectGUID]
                             [PLATFORM platformName]
                             dep1 dep2 ...)

Includes an external Microsoft project in the generated workspace
file.  Currently does nothing on UNIX.  This will create a target
named ``[projectname]``.  This can be used in the :command:`add_dependencies`
command to make things depend on the external project.

``TYPE``, ``GUID`` and ``PLATFORM`` are optional parameters that allow one to
specify the type of project, id (``GUID``) of the project and the name of
the target platform.  This is useful for projects requiring values
other than the default (e.g.  WIX projects).

.. versionadded:: 3.9
  If the imported project has different configuration names than the
  current project, set the :prop_tgt:`MAP_IMPORTED_CONFIG_<CONFIG>`
  target property to specify the mapping.


code:
include_guard
-------------

.. versionadded:: 3.10

Provides an include guard for the file currently being processed by CMake.

.. code-block:: cmake

  include_guard([DIRECTORY|GLOBAL])

Sets up an include guard for the current CMake file (see the
:variable:`CMAKE_CURRENT_LIST_FILE` variable documentation).

CMake will end its processing of the current file at the location of the
``include_guard`` command if the current file has already been
processed for the applicable scope (see below). This provides functionality
similar to the include guards commonly used in source headers or to the
``#pragma once`` directive. If the current file has been processed previously
for the applicable scope, the effect is as though :command:`return` had been
called. Do not call this command from inside a function being defined within
the current file.

An optional argument specifying the scope of the guard may be provided.
Possible values for the option are:

``DIRECTORY``
  The include guard applies within the current directory and below. The file
  will only be included once within this directory scope, but may be included
  again by other files outside of this directory (i.e. a parent directory or
  another directory not pulled in by :command:`add_subdirectory` or
  :command:`include` from the current file or its children).

``GLOBAL``
  The include guard applies globally to the whole build. The current file
  will only be included once regardless of the scope.

If no arguments given, ``include_guard`` has the same scope as a variable,
meaning that the include guard effect is isolated by the most recent
function scope or current directory if no inner function scopes exist.
In this case the command behavior is the same as:

.. code-block:: cmake

  if(__CURRENT_FILE_VAR__)
    return()
  endif()
  set(__CURRENT_FILE_VAR__ TRUE)


code:
include_regular_expression
--------------------------

Set the regular expression used for dependency checking.

.. code-block:: cmake

  include_regular_expression(regex_match [regex_complain])

Sets the regular expressions used in dependency checking.  Only files
matching ``regex_match`` will be traced as dependencies.  Only files
matching ``regex_complain`` will generate warnings if they cannot be found
(standard header paths are not searched).  The defaults are:

::

  regex_match    = "^.*$" (match everything)
  regex_complain = "^$" (match empty string only)