find_package¶
Note
The 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 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 dependency providers.
Typical Usage¶
Most calls to find_package() typically have the following form:
find_package(<PackageName> [<version>] [REQUIRED] [COMPONENTS <components>...])
The <PackageName> is the only mandatory argument. The <version> is
often omitted, and REQUIRED should be given if the project cannot be
configured successfully without the package. Some more complicated packages
support components which can be selected with the COMPONENTS keyword, but
most packages don't have that level of complexity.
The above is a reduced form of the basic signature. Where possible, projects should find packages using this form. This reduces complexity and maximizes the ways in which the package can be found or provided.
Understanding the basic signature should be enough for general usage of
find_package(). Project maintainers who intend to provide a config
package should understand the bigger picture, as explained in
Full Signature and all subsequent sections on this page.
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 theCMAKE_MODULE_PATH, then among the 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>.cmakefile 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 thefind_package()command was called. Being externally provided, 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 basic command signature.
- Config mode
In this mode, CMake searches for a file called
<lowercasePackageName>-config.cmakeor<PackageName>Config.cmake. It will also look for<lowercasePackageName>-config-version.cmakeor<PackageName>ConfigVersion.cmakeif version details were specified (see Config Mode 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 Config Mode 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 basic and full command signatures.
- FetchContent redirection mode
Added in version 3.24: A call to
find_package()can be redirected internally to a package provided by theFetchContentmodule. 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. SeeFetchContent_Declare()andFetchContent_MakeAvailable()for further details.
When not redirected to a package provided by 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 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.
Basic Signature¶
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
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.
Added in version 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.
Added in version 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 CMAKE_FIND_PACKAGE_TARGETS_GLOBAL
variable.
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...[<]versionMaxwhereversionMinandversionMaxhave 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 cmake_policy() command documentation for discussion
of the NO_POLICY_SCOPE option.
Added in version 3.24: The BYPASS_PROVIDER keyword is only allowed when find_package() is
being called by a dependency provider.
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¶
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 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 Config Mode Search Procedure is specified below.
Once found, any version constraint 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 Config Mode Search Procedure outlined below will find them without requiring use of additional options.
Config Mode Search Procedure¶
Note
When Config mode is used, this search procedure is applied regardless of whether the full or basic signature was given.
Added in version 3.24: All calls to find_package() (even in Module mode) first look for a config
package file in the CMAKE_FIND_PACKAGE_REDIRECTS_DIR directory.
The 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 |
|---|---|
|
W |
|
W |
|
W |
|
W |
|
W |
|
U |
|
U |
|
U |
|
W/U |
|
W/U |
|
W/U |
On systems supporting macOS FRAMEWORK and BUNDLE, the
following directories are searched for Frameworks or Application Bundles
containing a configuration file:
Entry |
Convention |
|---|---|
|
A |
|
A |
|
A |
|
A |
|
A |
|
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
CMAKE_LIBRARY_ARCHITECTUREvariable is set.lib64Searched on 64 bit platforms (
CMAKE_SIZEOF_VOID_Pis 8) and theFIND_LIBRARY_USE_LIB64_PATHSproperty is set toTRUE.lib32Searched on 32 bit platforms (
CMAKE_SIZEOF_VOID_Pis 4) and theFIND_LIBRARY_USE_LIB32_PATHSproperty is set toTRUE.libx32Searched on platforms using the x32 ABI if the
FIND_LIBRARY_USE_LIBX32_PATHSproperty is set toTRUE.libAlways searched.
Changed in version 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 dedicated syntax. Such specifications
will be ignored on all other platforms.
Added in version 3.24: REGISTRY_VIEW can be specified to manage Windows registry queries
specified as part of PATHS and HINTS.
Specify which registry views must be queried. This option is only meaningful
on Windows platforms and will be ignored on other ones. When not
specified, the TARGET view is used when the
CMP0134 policy is NEW. Refer to CMP0134 for the
default view when the policy is OLD.
64Query the 64-bit registry. On 32-bit Windows, it always returns the string
/REGISTRY-NOTFOUND.32Query the 32-bit registry.
64_32Query both views (
64and32) and generate a path for each.32_64Query both views (
32and64) and generate a path for each.HOSTQuery the registry matching the architecture of the host:
64on 64-bit Windows and32on 32-bit Windows.TARGETQuery the registry matching the architecture specified by the
CMAKE_SIZEOF_VOID_Pvariable. If not defined, fall back toHOSTview.BOTHQuery both views (
32and64). The order depends on the following rules: If theCMAKE_SIZEOF_VOID_Pvariable is defined, use the following view depending on the content of this variable:8:64_324:32_64
If the
CMAKE_SIZEOF_VOID_Pvariable is not defined, rely on the architecture of the host:64-bit:
64_3232-bit:
32
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
CMAKE_FIND_FRAMEWORK and 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.
Search prefixes unique to the current
<PackageName>being found. See policyCMP0074.Added in version 3.12.
Specifically, search prefixes specified by the following variables, in order:
<PackageName>_ROOTCMake variable, where<PackageName>is the case-preserved package name.<PACKAGENAME>_ROOTCMake variable, where<PACKAGENAME>is the upper-cased package name. See policyCMP0144.Added in version 3.27.
<PackageName>_ROOTenvironment variable, where<PackageName>is the case-preserved package name.<PACKAGENAME>_ROOTenvironment variable, where<PACKAGENAME>is the upper-cased package name. See policyCMP0144.Added in version 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_PATHis passed or by setting theCMAKE_FIND_USE_PACKAGE_ROOT_PATHtoFALSE.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 semicolon-separated lists. This can be skipped ifNO_CMAKE_PATHis passed or by setting theCMAKE_FIND_USE_CMAKE_PATHtoFALSE: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 ifNO_CMAKE_ENVIRONMENT_PATHis passed or by setting theCMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATHtoFALSE:<PackageName>_DIR
Search paths specified by the
HINTSoption. 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 thePATHSoption.Search the standard system environment variables. This can be skipped if
NO_SYSTEM_ENVIRONMENT_PATHis passed or by setting theCMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATHtoFALSE. Path entries ending in/binor/sbinare automatically converted to their parent directories:PATH
Search paths stored in the CMake User Package Registry. This can be skipped if
NO_CMAKE_PACKAGE_REGISTRYis passed or by setting the variableCMAKE_FIND_USE_PACKAGE_REGISTRYtoFALSEor the deprecated variableCMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRYtoTRUE.See the
cmake-packages(7)manual for details on the user package registry.Search cmake variables defined in the Platform files for the current system. The searching of
CMAKE_INSTALL_PREFIXandCMAKE_STAGING_PREFIXcan be skipped ifNO_CMAKE_INSTALL_PREFIXis passed or by setting theCMAKE_FIND_USE_INSTALL_PREFIXtoFALSE. All these locations can be skipped ifNO_CMAKE_SYSTEM_PATHis passed or by setting theCMAKE_FIND_USE_CMAKE_SYSTEM_PATHtoFALSE:The platform paths that these variables contain are locations that typically include installed software. An example being
/usr/localfor UNIX based platforms.Search paths stored in the CMake System Package Registry. This can be skipped if
NO_CMAKE_SYSTEM_PACKAGE_REGISTRYis passed or by setting theCMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRYvariable toFALSEor the deprecated variableCMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRYtoTRUE.See the
cmake-packages(7)manual for details on the system package registry.Search paths specified by the
PATHSoption. These are typically hard-coded guesses.
The CMAKE_IGNORE_PATH, CMAKE_IGNORE_PREFIX_PATH,
CMAKE_SYSTEM_IGNORE_PATH and
CMAKE_SYSTEM_IGNORE_PREFIX_PATH variables can also cause some
of the above locations to be ignored.
Paths are searched in the order described above. The first viable package configuration file found is used, even if a newer version of the package resides later in the list of search paths.
For search paths which contain <name>*, the order among matching paths
is unspecified unless the CMAKE_FIND_PACKAGE_SORT_ORDER variable
is set. This variable, along with the
CMAKE_FIND_PACKAGE_SORT_DIRECTION variable, determines the order
in which CMake considers paths that match a single search path containing
<name>*. For example, if the file system contains the package
configuration files
<prefix>/example-1.2/example-config.cmake
<prefix>/example-1.10/example-config.cmake
<prefix>/share/example-2.0/example-config.cmake
it is unspecified (when the aforementioned variables are unset) whether
find_package(example) will find example-1.2 or example-1.10
(assuming that both are viable), but find_package will not find
example-2.0, because one of the other two will be found first.
To control the order in which find_package searches directories that match
a glob expression, use CMAKE_FIND_PACKAGE_SORT_ORDER and
CMAKE_FIND_PACKAGE_SORT_DIRECTION.
For instance, to cause the above example to select example-1.10,
one can set
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
before calling find_package.
Added in version 3.16: Added the CMAKE_FIND_USE_<CATEGORY> variables to globally disable
various search locations.
The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
directories to be prepended to all other search directories. This
effectively "re-roots" the entire search under given locations.
Paths which are descendants of the CMAKE_STAGING_PREFIX are excluded
from this re-rooting, because that variable is always a path on the host system.
By default the CMAKE_FIND_ROOT_PATH is empty.
The CMAKE_SYSROOT variable can also be used to specify exactly one
directory to use as a prefix. Setting CMAKE_SYSROOT also has other
effects. See the documentation for that variable for more.
These variables are especially useful when cross-compiling to
point to the root directory of the target environment and CMake will
search there too. By default at first the directories listed in
CMAKE_FIND_ROOT_PATH are searched, then the CMAKE_SYSROOT
directory is searched, and then the non-rooted directories will be
searched. The default behavior can be adjusted by setting
CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. This behavior can be manually
overridden on a per-call basis using options:
CMAKE_FIND_ROOT_PATH_BOTHSearch in the order described above.
NO_CMAKE_FIND_ROOT_PATHDo not use the
CMAKE_FIND_ROOT_PATHvariable.ONLY_CMAKE_FIND_ROOT_PATHSearch only the re-rooted directories and directories below
CMAKE_STAGING_PREFIX.
The default search order is designed to be most-specific to
least-specific for common use cases.
Projects may override the order by simply calling the command
multiple times and using the NO_* options:
find_package (<PackageName> PATHS paths... NO_DEFAULT_PATH) find_package (<PackageName>)
Once one of the calls succeeds the result variable will be set and stored in the cache so that no call will search again.
By default the value stored in the result variable will be the path at
which the file is found. The 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
CMAKE_DISABLE_FIND_PACKAGE_<PackageName>variable toTRUEdisables the package. This also disables redirection to a package provided byFetchContent.Setting the
CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>variable toTRUEmakes the package REQUIRED.
Setting both variables to TRUE simultaneously is an error.
Config Mode Version Selection¶
Note
When Config mode is used, this version selection process is applied regardless of whether the full or basic 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 format specification). 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 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
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_NAMEThe
<PackageName>PACKAGE_FIND_VERSIONFull requested version string
PACKAGE_FIND_VERSION_MAJORMajor version if requested, else 0
PACKAGE_FIND_VERSION_MINORMinor version if requested, else 0
PACKAGE_FIND_VERSION_PATCHPatch version if requested, else 0
PACKAGE_FIND_VERSION_TWEAKTweak version if requested, else 0
PACKAGE_FIND_VERSION_COUNTNumber 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_RANGEFull requested version range string
PACKAGE_FIND_VERSION_RANGE_MINThis 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_MAXThis specifies whether the upper end point of the version range should be included or excluded. The supported values for this variable are
INCLUDEandEXCLUDE.PACKAGE_FIND_VERSION_MINFull requested version string of the lower end point of the range
PACKAGE_FIND_VERSION_MIN_MAJORMajor version of the lower end point if requested, else 0
PACKAGE_FIND_VERSION_MIN_MINORMinor version of the lower end point if requested, else 0
PACKAGE_FIND_VERSION_MIN_PATCHPatch version of the lower end point if requested, else 0
PACKAGE_FIND_VERSION_MIN_TWEAKTweak version of the lower end point if requested, else 0
PACKAGE_FIND_VERSION_MIN_COUNTNumber of version components of the lower end point, 0 to 4
PACKAGE_FIND_VERSION_MAXFull requested version string of the upper end point of the range
PACKAGE_FIND_VERSION_MAX_MAJORMajor version of the upper end point if requested, else 0
PACKAGE_FIND_VERSION_MAX_MINORMinor version of the upper end point if requested, else 0
PACKAGE_FIND_VERSION_MAX_PATCHPatch version of the upper end point if requested, else 0
PACKAGE_FIND_VERSION_MAX_TWEAKTweak version of the upper end point if requested, else 0
PACKAGE_FIND_VERSION_MAX_COUNTNumber 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_VERSIONFull provided version string
PACKAGE_VERSION_EXACTTrue if version is exact match
PACKAGE_VERSION_COMPATIBLETrue if version is compatible
PACKAGE_VERSION_UNSUITABLETrue 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>_VERSIONFull provided version string
<PackageName>_VERSION_MAJORMajor version if provided, else 0
<PackageName>_VERSION_MINORMinor version if provided, else 0
<PackageName>_VERSION_PATCHPatch version if provided, else 0
<PackageName>_VERSION_TWEAKTweak version if provided, else 0
<PackageName>_VERSION_COUNTNumber of version components, 0 to 4
and the corresponding package configuration file is loaded.
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_NAMEThe
<PackageName>which is searched for<PackageName>_FIND_REQUIREDTrue if
REQUIREDoption was given<PackageName>_FIND_QUIETLYTrue if
QUIEToption was given<PackageName>_FIND_REGISTRY_VIEWThe requested view if
REGISTRY_VIEWoption was given<PackageName>_FIND_VERSIONFull requested version string
<PackageName>_FIND_VERSION_MAJORMajor version if requested, else 0
<PackageName>_FIND_VERSION_MINORMinor version if requested, else 0
<PackageName>_FIND_VERSION_PATCHPatch version if requested, else 0
<PackageName>_FIND_VERSION_TWEAKTweak version if requested, else 0
<PackageName>_FIND_VERSION_COUNTNumber of version components, 0 to 4
<PackageName>_FIND_VERSION_EXACTTrue if
EXACToption was given<PackageName>_FIND_COMPONENTSList 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_RANGEFull requested version range string
<PackageName>_FIND_VERSION_RANGE_MINThis specifies whether the lower end point of the version range is included or excluded. Currently,
INCLUDEis the only supported value.<PackageName>_FIND_VERSION_RANGE_MAXThis specifies whether the upper end point of the version range is included or excluded. The possible values for this variable are
INCLUDEorEXCLUDE.<PackageName>_FIND_VERSION_MINFull requested version string of the lower end point of the range
<PackageName>_FIND_VERSION_MIN_MAJORMajor version of the lower end point if requested, else 0
<PackageName>_FIND_VERSION_MIN_MINORMinor version of the lower end point if requested, else 0
<PackageName>_FIND_VERSION_MIN_PATCHPatch version of the lower end point if requested, else 0
<PackageName>_FIND_VERSION_MIN_TWEAKTweak version of the lower end point if requested, else 0
<PackageName>_FIND_VERSION_MIN_COUNTNumber of version components of the lower end point, 0 to 4
<PackageName>_FIND_VERSION_MAXFull requested version string of the upper end point of the range
<PackageName>_FIND_VERSION_MAX_MAJORMajor version of the upper end point if requested, else 0
<PackageName>_FIND_VERSION_MAX_MINORMinor version of the upper end point if requested, else 0
<PackageName>_FIND_VERSION_MAX_PATCHPatch version of the upper end point if requested, else 0
<PackageName>_FIND_VERSION_MAX_TWEAKTweak version of the upper end point if requested, else 0
<PackageName>_FIND_VERSION_MAX_COUNTNumber 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.