kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Help: Format find_package() command documentation 

Add inline markup and explicit markup block syntax as needed.
Add cross-references to other documentation as appropriate.
This commit is contained in:
Brad King 2014-02-17 15:36:03 -05:00
parent bd6887e4d6
commit bf012e0cb6
1 changed files with 169 additions and 187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

318
Help/command/find_package.rst
View File

@ -10,29 +10,29 @@ Load settings for an external project.
[OPTIONAL_COMPONENTS components...] [OPTIONAL_COMPONENTS components...]
[NO_POLICY_SCOPE]) [NO_POLICY_SCOPE])
Finds and loads settings from an external project. <package>_FOUND Finds and loads settings from an external project. ``<package>_FOUND``
will be set to indicate whether the package was found. When the will be set to indicate whether the package was found. When the
package is found package-specific information is provided through package is found package-specific information is provided through
variables and imported targets documented by the package itself. The variables and :ref:`Imported Targets` documented by the package itself. The
QUIET option disables messages if the package cannot be found. The ``QUIET`` option disables messages if the package cannot be found. The
MODULE option disables the second signature documented below. The ``MODULE`` option disables the second signature documented below. The
REQUIRED option stops processing with an error message if the package ``REQUIRED`` option stops processing with an error message if the package
cannot be found. cannot be found.
A package-specific list of required components may be listed after the A package-specific list of required components may be listed after the
COMPONENTS option (or after the REQUIRED option if present). ``COMPONENTS`` option (or after the ``REQUIRED`` option if present).
Additional optional components may be listed after Additional optional components may be listed after
OPTIONAL_COMPONENTS. Available components and their influence on ``OPTIONAL_COMPONENTS``. Available components and their influence on
whether a package is considered to be found are defined by the target whether a package is considered to be found are defined by the target
package. package.
The [version] argument requests a version with which the package found The ``[version]`` argument requests a version with which the package found
should be compatible (format is major[.minor[.patch[.tweak]]]). The should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The
EXACT option requests that the version be matched exactly. If no ``EXACT`` option requests that the version be matched exactly. If no
[version] and/or component list is given to a recursive invocation ``[version]`` and/or component list is given to a recursive invocation
inside a find-module, the corresponding arguments are forwarded inside a find-module, the corresponding arguments are forwarded
automatically from the outer call (including the EXACT flag for automatically from the outer call (including the ``EXACT`` flag for
[version]). Version support is currently provided only on a ``[version]``). Version support is currently provided only on a
package-by-package basis (details below). package-by-package basis (details below).
User code should generally look for packages using the above simple User code should generally look for packages using the above simple
@ -44,17 +44,15 @@ are encouraged to read on.
The command has two modes by which it searches for packages: "Module" The command has two modes by which it searches for packages: "Module"
mode and "Config" mode. Module mode is available when the command is mode and "Config" mode. Module mode is available when the command is
invoked with the above reduced signature. CMake searches for a file invoked with the above reduced signature. CMake searches for a file
called "Find<package>.cmake" in the CMAKE_MODULE_PATH followed by the called ``Find<package>.cmake`` in the :variable:`CMAKE_MODULE_PATH`
CMake installation. If the file is found, it is read and processed by followed by the CMake installation. If the file is found, it is read
CMake. It is responsible for finding the package, checking the and processed by CMake. It is responsible for finding the package,
version, and producing any needed messages. Many find-modules provide checking the version, and producing any needed messages. Many
limited or no support for versioning; check the module documentation. find-modules provide limited or no support for versioning; check
If no module is found and the MODULE option is not given the command the module documentation. If no module is found and the ``MODULE``
proceeds to Config mode. option is not given the command proceeds to Config mode.
The complete Config mode command signature is: The complete Config mode command signature is::
::
find_package(<package> [version] [EXACT] [QUIET] find_package(<package> [version] [EXACT] [QUIET]
[REQUIRED] [[COMPONENTS] [components...]] [REQUIRED] [[COMPONENTS] [components...]]
@ -77,89 +75,100 @@ The complete Config mode command signature is:
ONLY_CMAKE_FIND_ROOT_PATH | ONLY_CMAKE_FIND_ROOT_PATH |
NO_CMAKE_FIND_ROOT_PATH]) NO_CMAKE_FIND_ROOT_PATH])
The CONFIG option may be used to skip Module mode explicitly and The ``CONFIG`` option may be used to skip Module mode explicitly and
switch to Config mode. It is synonymous to using NO_MODULE. Config 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 mode is also implied by use of options not specified in the reduced
signature. signature.
Config mode attempts to locate a configuration file provided by the Config mode attempts to locate a configuration file provided by the
package to be found. A cache entry called <package>_DIR is created to package to be found. A cache entry called ``<package>_DIR`` is created to
hold the directory containing the file. By default the command hold the directory containing the file. By default the command
searches for a package with the name <package>. If the NAMES option searches for a package with the name ``<package>``. If the ``NAMES`` option
is given the names following it are used instead of <package>. The is given the names following it are used instead of ``<package>``. The
command searches for a file called "<name>Config.cmake" or command searches for a file called ``<name>Config.cmake`` or
"<lower-case-name>-config.cmake" for each name specified. A ``<lower-case-name>-config.cmake`` for each name specified. A
replacement set of possible configuration file names may be given replacement set of possible configuration file names may be given
using the CONFIGS option. The search procedure is specified below. using the ``CONFIGS`` option. The search procedure is specified below.
Once found, the configuration file is read and processed by CMake. Once found, the configuration file is read and processed by CMake.
Since the file is provided by the package it already knows the Since the file is provided by the package it already knows the
location of package contents. The full path to the configuration file location of package contents. The full path to the configuration file
is stored in the cmake variable <package>_CONFIG. is stored in the cmake variable ``<package>_CONFIG``.
All configuration files which have been considered by CMake while All configuration files which have been considered by CMake while
searching for an installation of the package with an appropriate searching for an installation of the package with an appropriate
version are stored in the cmake variable <package>_CONSIDERED_CONFIGS, version are stored in the cmake variable ``<package>_CONSIDERED_CONFIGS``,
the associated versions in <package>_CONSIDERED_VERSIONS. the associated versions in ``<package>_CONSIDERED_VERSIONS``.
If the package configuration file cannot be found CMake will generate If the package configuration file cannot be found CMake will generate
an error describing the problem unless the QUIET argument is an error describing the problem unless the ``QUIET`` argument is
specified. If REQUIRED is specified and the package is not found a specified. If ``REQUIRED`` is specified and the package is not found a
fatal error is generated and the configure step stops executing. If fatal error is generated and the configure step stops executing. If
<package>_DIR has been set to a directory not containing a ``<package>_DIR`` has been set to a directory not containing a
configuration file CMake will ignore it and search from scratch. configuration file CMake will ignore it and search from scratch.
When the [version] argument is given Config mode will only find a When the ``[version]`` argument is given Config mode will only find a
version of the package that claims compatibility with the requested version of the package that claims compatibility with the requested
version (format is major[.minor[.patch[.tweak]]]). If the EXACT version (format is ``major[.minor[.patch[.tweak]]]``). If the ``EXACT``
option is given only a version of the package claiming an exact match 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 of the requested version may be found. CMake does not establish any
convention for the meaning of version numbers. Package version convention for the meaning of version numbers. Package version
numbers are checked by "version" files provided by the packages numbers are checked by "version" files provided by the packages
themselves. For a candidate package configuration file themselves. For a candidate package configuration file
"<config-file>.cmake" the corresponding version file is located next ``<config-file>.cmake`` the corresponding version file is located next
to it and named either "<config-file>-version.cmake" or to it and named either ``<config-file>-version.cmake`` or
"<config-file>Version.cmake". If no such version file is available ``<config-file>Version.cmake``. If no such version file is available
then the configuration file is assumed to not be compatible with any then the configuration file is assumed to not be compatible with any
requested version. A basic version file containing generic version requested version. A basic version file containing generic version
matching code can be created using the macro matching code can be created using the
write_basic_package_version_file(), see its documentation for more :module:`CMakePackageConfigHelpers` module. When a version file
details. When a version file is found it is loaded to check the is found it is loaded to check the requested version number. The
requested version number. The version file is loaded in a nested version file is loaded in a nested scope in which the following
scope in which the following variables have been defined: variables have been defined:
:: ``PACKAGE_FIND_NAME``
the ``<package>`` name
PACKAGE_FIND_NAME = the <package> name ``PACKAGE_FIND_VERSION``
PACKAGE_FIND_VERSION = full requested version string full requested version string
PACKAGE_FIND_VERSION_MAJOR = major version if requested, else 0 ``PACKAGE_FIND_VERSION_MAJOR``
PACKAGE_FIND_VERSION_MINOR = minor version if requested, else 0 major version if requested, else 0
PACKAGE_FIND_VERSION_PATCH = patch version if requested, else 0 ``PACKAGE_FIND_VERSION_MINOR``
PACKAGE_FIND_VERSION_TWEAK = tweak version if requested, else 0 minor version if requested, else 0
PACKAGE_FIND_VERSION_COUNT = number of version components, 0 to 4 ``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
The version file checks whether it satisfies the requested version and The version file checks whether it satisfies the requested version and
sets these variables: 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
PACKAGE_VERSION = full provided version string These variables are checked by the ``find_package`` command to determine
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 whether the configuration file provides an acceptable version. They
are not available after the find_package call returns. If the version are not available after the find_package call returns. If the version
is acceptable the following variables are set: is acceptable the following variables are set:
:: ``<package>_VERSION``
full provided version string
<package>_VERSION = full provided version string ``<package>_VERSION_MAJOR``
<package>_VERSION_MAJOR = major version if provided, else 0 major version if provided, else 0
<package>_VERSION_MINOR = minor version if provided, else 0 ``<package>_VERSION_MINOR``
<package>_VERSION_PATCH = patch version if provided, else 0 minor version if provided, else 0
<package>_VERSION_TWEAK = tweak version if provided, else 0 ``<package>_VERSION_PATCH``
<package>_VERSION_COUNT = number of version components, 0 to 4 patch version if provided, else 0
``<package>_VERSION_TWEAK``
tweak version if provided, else 0
``<package>_VERSION_COUNT``
number of version components, 0 to 4
and the corresponding package configuration file is loaded. When and the corresponding package configuration file is loaded. When
multiple package configuration files are available whose version files multiple package configuration files are available whose version files
@ -170,9 +179,7 @@ version number.
Config mode provides an elaborate interface and search procedure. Config mode provides an elaborate interface and search procedure.
Much of the interface is provided for completeness and for use Much of the interface is provided for completeness and for use
internally by find-modules loaded by Module mode. Most user code internally by find-modules loaded by Module mode. Most user code
should simply call should simply call::
::
find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET]) find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
@ -185,9 +192,7 @@ CMake constructs a set of possible installation prefixes for the
package. Under each prefix several directories are searched for a package. Under each prefix several directories are searched for a
configuration file. The tables below show the directories searched. configuration file. The tables below show the directories searched.
Each entry is meant for installation trees following Windows (W), UNIX Each entry is meant for installation trees following Windows (W), UNIX
(U), or Apple (A) conventions. (U), or Apple (A) conventions::
::
<prefix>/ (W) <prefix>/ (W)
<prefix>/(cmake|CMake)/ (W) <prefix>/(cmake|CMake)/ (W)
@ -199,9 +204,7 @@ Each entry is meant for installation trees following Windows (W), UNIX
On systems supporting OS X Frameworks and Application Bundles the On systems supporting OS X Frameworks and Application Bundles the
following directories are searched for frameworks or bundles following directories are searched for frameworks or bundles
containing a configuration file: containing a configuration file::
::
<prefix>/<name>.framework/Resources/ (A) <prefix>/<name>.framework/Resources/ (A)
<prefix>/<name>.framework/Resources/CMake/ (A) <prefix>/<name>.framework/Resources/CMake/ (A)
@ -210,11 +213,12 @@ containing a configuration file:
<prefix>/<name>.app/Contents/Resources/ (A) <prefix>/<name>.app/Contents/Resources/ (A)
<prefix>/<name>.app/Contents/Resources/CMake/ (A) <prefix>/<name>.app/Contents/Resources/CMake/ (A)
In all cases the <name> is treated as case-insensitive and corresponds In all cases the ``<name>`` is treated as case-insensitive and corresponds
to any of the names specified (<package> or names given by NAMES). to any of the names specified (``<package>`` or names given by ``NAMES``).
Paths with lib/<arch> are enabled if CMAKE_LIBRARY_ARCHITECTURE is Paths with ``lib/<arch>`` are enabled if the
set. If PATH_SUFFIXES is specified the suffixes are appended to each :variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. If ``PATH_SUFFIXES``
(W) or (U) directory entry one-by-one. 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 This set of directories is intended to work in cooperation with
projects that provide configuration files in their installation trees. projects that provide configuration files in their installation trees.
@ -225,96 +229,66 @@ installations on UNIX platforms where the prefix is shared by multiple
packages. This is merely a convention, so all (W) and (U) directories packages. This is merely a convention, so all (W) and (U) directories
are still searched on all platforms. Directories marked with (A) are are still searched on all platforms. Directories marked with (A) are
intended for installations on Apple platforms. The cmake variables intended for installations on Apple platforms. The cmake variables
CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the order of ``CMAKE_FIND_FRAMEWORK`` and ``CMAKE_FIND_APPBUNDLE``
preference as specified below. determine the order of preference as specified below.
The set of installation prefixes is constructed using the following The set of installation prefixes is constructed using the following
steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled. steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are
enabled.
1. Search paths specified in cmake-specific cache variables. These 1. Search paths specified in cmake-specific cache variables. These
are intended to be used on the command line with a -DVAR=value. This are intended to be used on the command line with a ``-DVAR=value``.
can be skipped if NO_CMAKE_PATH is passed. This can be skipped if ``NO_CMAKE_PATH`` is passed::
::
CMAKE_PREFIX_PATH CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH CMAKE_APPBUNDLE_PATH
2. Search paths specified in cmake-specific environment variables. 2. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration. This These are intended to be set in the user's shell configuration.
can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed. This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed::
::
<package>_DIR <package>_DIR
CMAKE_PREFIX_PATH CMAKE_PREFIX_PATH
CMAKE_FRAMEWORK_PATH CMAKE_FRAMEWORK_PATH
CMAKE_APPBUNDLE_PATH CMAKE_APPBUNDLE_PATH
3. Search paths specified by the HINTS option. These should be paths 3. Search paths specified by the ``HINTS`` option. These should be paths
computed by system introspection, such as a hint provided by the computed by system introspection, such as a hint provided by the
location of another item already found. Hard-coded guesses should be location of another item already found. Hard-coded guesses should
specified with the PATHS option. be specified with the ``PATHS`` option.
4. Search the standard system environment variables. This can be 4. Search the standard system environment variables. This can be
skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries ending skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries
in "/bin" or "/sbin" are automatically converted to their parent ending in ``/bin`` or ``/sbin`` are automatically converted to their
directories. parent directories::
::
PATH PATH
5. Search project build trees recently configured in a CMake GUI. 5. Search project build trees recently configured in a :manual:`cmake-gui(1)`.
This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It is intended This can be skipped if ``NO_CMAKE_BUILDS_PATH`` is passed. It is intended
for the case when a user is building multiple dependent projects one for the case when a user is building multiple dependent projects one
after another. after another.
6. Search paths stored in the CMake user package registry. This can 6. Search paths stored in the CMake :ref:`User Package Registry`.
be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. On Windows a This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed.
<package> may appear under registry key See the :manual:`cmake-packages(7)` manual for details on the user
package registry.
::
HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
as a REG_SZ value, with arbitrary name, that specifies the directory
containing the package configuration file. On UNIX platforms a
<package> may appear under the directory
::
~/.cmake/packages/<package>
as a file, with arbitrary name, whose content specifies the directory
containing the package configuration file. See the export(PACKAGE)
command to create user package registry entries for project build
trees.
7. Search cmake variables defined in the Platform files for the 7. Search cmake variables defined in the Platform files for the
current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
passed. passed::
::
CMAKE_SYSTEM_PREFIX_PATH CMAKE_SYSTEM_PREFIX_PATH
CMAKE_SYSTEM_FRAMEWORK_PATH CMAKE_SYSTEM_FRAMEWORK_PATH
CMAKE_SYSTEM_APPBUNDLE_PATH CMAKE_SYSTEM_APPBUNDLE_PATH
8. Search paths stored in the CMake system package registry. This 8. Search paths stored in the CMake :ref:`System Package Registry`.
can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed. On This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed.
Windows a <package> may appear under registry key 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
HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
as a REG_SZ value, with arbitrary name, that specifies the directory
containing the package configuration file. There is no system package
registry on non-Windows platforms.
9. Search paths specified by the PATHS option. These are typically
hard-coded guesses. hard-coded guesses.
.. |FIND_XXX| replace:: find_package .. |FIND_XXX| replace:: find_package
@ -326,37 +300,45 @@ hard-coded guesses.
.. include:: FIND_XXX_ROOT.txt .. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt .. include:: FIND_XXX_ORDER.txt
Every non-REQUIRED find_package() call can be disabled by setting the Every non-REQUIRED ``find_package`` call can be disabled by setting the
variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE. See the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``.
documentation for the CMAKE_DISABLE_FIND_PACKAGE_<package> variable
for more information.
When loading a find module or package configuration file find_package When loading a find module or package configuration file ``find_package``
defines variables to provide information about the call arguments (and defines variables to provide information about the call arguments (and
restores their original state before returning): restores their original state before returning):
:: ``<package>_FIND_REQUIRED``
true if ``REQUIRED`` option was given
<package>_FIND_REQUIRED = true if REQUIRED option was given ``<package>_FIND_QUIETLY``
<package>_FIND_QUIETLY = true if QUIET option was given true if ``QUIET`` option was given
<package>_FIND_VERSION = full requested version string ``<package>_FIND_VERSION``
<package>_FIND_VERSION_MAJOR = major version if requested, else 0 full requested version string
<package>_FIND_VERSION_MINOR = minor version if requested, else 0 ``<package>_FIND_VERSION_MAJOR``
<package>_FIND_VERSION_PATCH = patch version if requested, else 0 major version if requested, else 0
<package>_FIND_VERSION_TWEAK = tweak version if requested, else 0 ``<package>_FIND_VERSION_MINOR``
<package>_FIND_VERSION_COUNT = number of version components, 0 to 4 minor version if requested, else 0
<package>_FIND_VERSION_EXACT = true if EXACT option was given ``<package>_FIND_VERSION_PATCH``
<package>_FIND_COMPONENTS = list of requested components patch version if requested, else 0
<package>_FIND_REQUIRED_<c> = true if component <c> is required ``<package>_FIND_VERSION_TWEAK``
false if component <c> is optional tweak version if requested, else 0
``<package>_FIND_VERSION_COUNT``
number of version components, 0 to 4
``<package>_FIND_VERSION_EXACT``
true if ``EXACT`` option was given
``<package>_FIND_COMPONENTS``
list of requested components
``<package>_FIND_REQUIRED_<c>``
true if component ``<c>`` is required,
false if component ``<c>`` is optional
In Module mode the loaded find module is responsible to honor the In Module mode the loaded find module is responsible to honor the
request detailed by these variables; see the find module for details. request detailed by these variables; see the find module for details.
In Config mode find_package handles REQUIRED, QUIET, and version In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and
options automatically but leaves it to the package configuration file ``[version]`` options automatically but leaves it to the package
to handle components in a way that makes sense for the package. The configuration file to handle components in a way that makes sense
package configuration file may set <package>_FOUND to false to tell for the package. The package configuration file may set
find_package that component requirements are not satisfied. ``<package>_FOUND`` to false to tell ``find_package`` that component
requirements are not satisfied.
See the cmake_policy() command documentation for discussion of the See the :command:`cmake_policy` command documentation for discussion
NO_POLICY_SCOPE option. of the ``NO_POLICY_SCOPE`` option.