Finding Packages¶
Many software projects provide tools and libraries that are meant as building blocks for other projects and applications. CMake projects that depend on outside packages locate their dependencies using the find_package command. A typical invocation is of the form:
where is the name of the package to be found, and [version] is an optional version request (of the form major[.minor.[patch]] ). The command’s notion of a package is distinct from that of CPack, which is meant for creating source and binary distributions and installers.
The command operates in two modes: Module mode and Config mode. In Module mode, the command searches for a find module : a file named Find.cmake . It looks first in the CMAKE_MODULE_PATH and then in the CMake installation. If a find module is found, it is loaded to search for individual components of the package. Find modules contain package-specific knowledge of the libraries and other files they expect to find, and internally use commands like find_library to locate them. CMake provides find modules for many common packages; see the cmake-modules(7) manual.
The Config mode of find_package provides a powerful alternative through cooperation with the package to be found. It enters this mode after failing to locate a find module or when explicitly requested by the caller. In Config mode the command searches for a package configuration file : a file named Config.cmake or -config.cmake which is provided by the package to be found. Given the name of a package, the find_package command knows how to search deep inside installation prefixes for locations like:
(see documentation of the find_package command for a complete list of locations). CMake creates a cache entry called _DIR to store the location found or allow the user to set it. Since a package configuration file comes with an installation of its package, it knows exactly where to find everything provided by the installation. Once the find_package command locates the file it provides the locations of package components without any additional searching.
The [version] option asks find_package to locate a particular version of the package. In Module mode, the command passes the request on to the find module. In Config mode the command looks next to each candidate package configuration file for a package version file : a file named ConfigVersion.cmake or -config-.cmake . The version file is loaded to test whether the package version is an acceptable match for the version requested (see documentation of find_package for the version file API specification). If the version file claims compatibility, the configuration file is accepted, or is otherwise ignored. This approach allows each project to define its own rules for version compatibility.
Built-in Find Modules¶
CMake has many predefined modules that can be found in the Modules subdirectory of CMake. The modules can find many common software packages. See the cmake-modules(7) manual for a detailed list.
Each Find.cmake module defines a set of variables that will allow a project to use the software package once it is found. Those variables all start with the name of the software being found . With CMake we have tried to establish a convention for naming these variables, but you should read the comments at the top of the module for a more definitive answer. The following variables are used by convention when needed:
_INCLUDE_DIRS
Where to find the package’s header files, typically .h, etc.
The libraries to link against to use . These include full paths.
_DEFINITIONS
Preprocessor definitions to use when compiling code that uses .
_EXECUTABLE
Where to find the tool that is part of the package.
__EXECUTABLE
Where to find the tool that comes with .
Where to find the base directory of the installation of . This is useful for large packages where you want to reference many files relative to a common base (or root) directory.
Version of the package was found if true. Authors of find modules should make sure at most one of these is ever true. For example TCL_VERSION_84.
If false, then the optional part of package is unavailable.
Set to false or undefined if we haven’t found or don’t want to use .
Not all of the variables are present in each of the FindXX.cmake files . However, the _FOUND should exist under most circumstances. If is a library, then _LIBRARIES should also be defined, and _INCLUDE_DIR should usually be defined.
Modules can be included in a project either with the include command or the find_package command.
include($CMAKE_ROOT>/Modules/FindOpenGL.cmake)