Load settings for an external project.
find_package(<package> [version] [EXACT] [QUIET] [MODULE] [REQUIRED] [[COMPONENTS] [components...]] [OPTIONAL_COMPONENTS components...] [NO_POLICY_SCOPE])
Finds and loads settings from an external project.
<package>_FOUND will be set to indicate whether the package was found. When the package is found package-specific information is provided through variables and Imported Targets documented by the package itself. The
QUIET option disables messages if the package cannot be found. The
MODULE option disables the second signature documented below. 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 option (or after the
REQUIRED option if present). Additional optional components may be listed after
OPTIONAL_COMPONENTS. Available components and their influence on whether a package is considered to be found are defined by the target package.
[version] argument requests a version with which the package found should be compatible (format is
EXACT option requests that the version be matched exactly. 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 (details below).
User code should generally look for packages using the above simple signature. The remainder of this command documentation specifies the full command signature and details of the search process. Project maintainers wishing to provide a package to be found by this command are encouraged to read on.
The command has two modes by which it searches for packages: “Module” mode and “Config” mode. Module mode is available when the command is invoked with the above reduced signature. CMake searches for a file called
Find<package>.cmake in the
CMAKE_MODULE_PATH followed 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. Many find-modules provide limited or no support for versioning; check the module documentation. If no module is found and the
MODULE option is not given the command proceeds to Config mode.
The complete Config mode command signature is:
find_package(<package> [version] [EXACT] [QUIET] [REQUIRED] [[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])
CONFIG option may be used to skip Module mode explicitly and switch to Config mode. It is synonymous to using
NO_MODULE. Config mode is also implied by use of options not specified in the reduced signature.
Config mode attempts to locate a configuration file provided by the package to be found. A cache entry called
<package>_DIR is created to hold the directory containing the file. By default the command searches for a package with the name
<package>. If the
NAMES option is given the names following it are used instead of
<package>. The command searches for a file called
<lower-case-name>-config.cmake for each name specified. A replacement set of possible configuration file names may be given using the
CONFIGS option. The search procedure is specified below. Once found, 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
All configuration files which have been considered by CMake while searching for an installation of the package with an appropriate version are stored in the cmake variable
<package>_CONSIDERED_CONFIGS, the associated versions in
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
<package>_DIR has been set to a directory not containing a configuration file CMake will ignore it and search from scratch.
[version] argument is given Config mode will only find a version of the package that claims compatibility with the requested version (format is
major[.minor[.patch[.tweak]]]). 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. 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:
The version file checks whether it satisfies the requested version and sets these variables:
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:
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
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
CMAKE_FIND_PACKAGE_SORT_DIRECTION. For instance in order to select the highest version one can set:
SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
Config mode provides an elaborate interface and search procedure. Much of the interface is provided for completeness and for use internally by find-modules loaded by Module mode. Most user code should simply call:
find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
in order to find a package. Package maintainers providing CMake package configuration files are encouraged to name and install them such that the procedure outlined below will find them without requiring use of additional options.
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 OS X Frameworks and Application Bundles the following directories are searched for frameworks or 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 (
<package> or names given by
lib/<arch> are enabled if the
CMAKE_LIBRARY_ARCHITECTURE variable is set.
lib* includes one or more of the values
lib (searched in that order).
lib64are searched on 64 bit platforms if the
FIND_LIBRARY_USE_LIB64_PATHSproperty is set to
lib32are searched on 32 bit platforms if the
FIND_LIBRARY_USE_LIB32_PATHSproperty is set to
libx32are searched on platforms using the x32 ABI if the
FIND_LIBRARY_USE_LIBX32_PATHSproperty is set to
libpath is always searched.
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_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.
<PackageName>_ROOTCMake variable and the
<PackageName>_ROOTenvironment 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_PATHis passed. See policy
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 ;-lists. This can be skipped if
NO_CMAKE_PATH is passed:
CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH
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:
<package>_DIR CMAKE_PREFIX_PATH CMAKE_FRAMEWORK_PATH CMAKE_APPBUNDLE_PATH
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 the
Search the standard system environment variables. This can be skipped if
NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries ending in
/sbin are automatically converted to their parent directories:
NO_CMAKE_PACKAGE_REGISTRYis passed or by setting the
TRUE. 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. This can be skipped if
NO_CMAKE_SYSTEM_PATH is passed:
CMAKE_SYSTEM_PREFIX_PATH CMAKE_SYSTEM_FRAMEWORK_PATH CMAKE_SYSTEM_APPBUNDLE_PATH
NO_CMAKE_SYSTEM_PACKAGE_REGISTRYis passed or by setting the
TRUE. See the
cmake-packages(7)manual for details on the system package registry.
PATHSoption. These are typically hard-coded guesses.
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.
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:
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
find_package (<package> PATHS paths... NO_DEFAULT_PATH) find_package (<package>)
Once one of the calls succeeds the result variable will be set and stored in the cache so that no call will search again.
find_package call can be disabled by setting the
CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to
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):
<package>name which is searched for
REQUIREDoption was given
QUIEToption was given
EXACToption was given
<c>is required, false if component
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
[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
<package>_FOUND to false to tell
find_package that component requirements are not satisfied.
cmake_policy() command documentation for discussion of the
© 2000–2018 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.