find_package | |
------------ | |
.. only:: html | |
.. contents:: | |
Find a package (usually provided by something external to the project), | |
and load its package-specific details. | |
Search Modes | |
^^^^^^^^^^^^ | |
The command has two very distinct ways of conducting the search: | |
**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. | |
The command arguments determine which of the above modes 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 either 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 | |
^^^^^^^^^^^^^^^ | |
.. code-block:: cmake | |
find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] | |
[REQUIRED] [[COMPONENTS] [components...]] | |
[OPTIONAL_COMPONENTS components...] | |
[NO_POLICY_SCOPE]) | |
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. | |
.. _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. | |
.. _`full signature`: | |
Full Signature | |
^^^^^^^^^^^^^^ | |
.. code-block:: cmake | |
find_package(<PackageName> [version] [EXACT] [QUIET] | |
[REQUIRED] [[COMPONENTS] [components...]] | |
[OPTIONAL_COMPONENTS components...] | |
[CONFIG|NO_MODULE] | |
[NO_POLICY_SCOPE] | |
[NAMES name1 [name2 ...]] | |
[CONFIGS config1 [config2 ...]] | |
[HINTS path1 [path2 ... ]] | |
[PATHS path1 [path2 ... ]] | |
[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_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 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. | |
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:: | |
<prefix>/ (W) | |
<prefix>/(cmake|CMake)/ (W) | |
<prefix>/<name>*/ (W) | |
<prefix>/<name>*/(cmake|CMake)/ (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) | |
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:: | |
<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``). | |
Paths with ``lib/<arch>`` are enabled if the | |
:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one | |
or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in | |
that order). | |
* Paths with ``lib64`` are searched on 64 bit platforms if the | |
:prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``. | |
* Paths with ``lib32`` are searched on 32 bit platforms if the | |
:prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``. | |
* Paths with ``libx32`` are searched on platforms using the x32 ABI | |
if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``. | |
* The ``lib`` path is always searched. | |
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. .. versionadded:: 3.12 | |
Search paths specified in the :variable:`<PackageName>_ROOT` CMake | |
variable and the :envvar:`<PackageName>_ROOT` environment variable, | |
where ``<PackageName>`` is the package to be found. | |
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``. | |
See policy :policy:`CMP0074`. | |
2. Search paths specified in cmake-specific cache variables. These | |
are intended to be used on the command line with a ``-DVAR=value``. | |
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` | |
* ``CMAKE_FRAMEWORK_PATH`` | |
* ``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. This 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. | |
.. |FIND_XXX| replace:: find_package | |
.. |FIND_ARGS_XXX| replace:: <PackageName> | |
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: | |
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` | |
.. 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. | |
* 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. 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_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. |