mirror of
https://github.com/reactos/CMake.git
synced 2024-11-24 03:59:58 +00:00
Merge topic 'doc-package-registry'
bf012e0cHelp: Format find_package() command documentationbd6887e4Help: Document the package registry in cmake-packages.7
This commit is contained in:
Brad King
CMake Topic Stage
commit
5a607c4a6f
@ -10,29 +10,29 @@ Load settings for an external project.
|
||||
[OPTIONAL_COMPONENTS components...]
|
||||
[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
|
||||
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
|
||||
variables and :ref:`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).
|
||||
``COMPONENTS`` option (or after the ``REQUIRED`` option if present).
|
||||
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
|
||||
package.
|
||||
|
||||
The [version] argument requests a version with which the package found
|
||||
should be compatible (format is major[.minor[.patch[.tweak]]]). The
|
||||
EXACT option requests that the version be matched exactly. If no
|
||||
[version] and/or component list is given to a recursive invocation
|
||||
The ``[version]`` argument requests a version with which the package found
|
||||
should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The
|
||||
``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
|
||||
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
|
||||
@ -44,17 +44,15 @@ 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.
|
||||
called ``Find<package>.cmake`` in the :variable:`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:
|
||||
|
||||
::
|
||||
The complete Config mode command signature is::
|
||||
|
||||
find_package(<package> [version] [EXACT] [QUIET]
|
||||
[REQUIRED] [[COMPONENTS] [components...]]
|
||||
@ -77,89 +75,100 @@ The complete Config mode command signature is:
|
||||
ONLY_CMAKE_FIND_ROOT_PATH |
|
||||
NO_CMAKE_FIND_ROOT_PATH])
|
||||
|
||||
The CONFIG option may be used to skip Module mode explicitly and
|
||||
switch to Config mode. It is synonymous to using NO_MODULE. Config
|
||||
The ``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
|
||||
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 "<name>Config.cmake" or
|
||||
"<lower-case-name>-config.cmake" for each name specified. A
|
||||
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 ``<name>Config.cmake`` or
|
||||
``<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.
|
||||
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 <package>_CONFIG.
|
||||
is stored in the cmake variable ``<package>_CONFIG``.
|
||||
|
||||
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 <package>_CONSIDERED_VERSIONS.
|
||||
version are stored in the cmake variable ``<package>_CONSIDERED_CONFIGS``,
|
||||
the associated versions in ``<package>_CONSIDERED_VERSIONS``.
|
||||
|
||||
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
|
||||
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
|
||||
``<package>_DIR`` has been set to a directory not containing a
|
||||
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 (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
|
||||
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
|
||||
``<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 macro
|
||||
write_basic_package_version_file(), see its documentation for more
|
||||
details. 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:
|
||||
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 <package> name
|
||||
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
|
||||
``PACKAGE_FIND_NAME``
|
||||
the ``<package>`` name
|
||||
``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
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
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:
|
||||
|
||||
::
|
||||
|
||||
<package>_VERSION = full provided version string
|
||||
<package>_VERSION_MAJOR = major version if provided, else 0
|
||||
<package>_VERSION_MINOR = minor version if provided, else 0
|
||||
<package>_VERSION_PATCH = 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
|
||||
``<package>_VERSION``
|
||||
full provided version string
|
||||
``<package>_VERSION_MAJOR``
|
||||
major version if provided, else 0
|
||||
``<package>_VERSION_MINOR``
|
||||
minor version if provided, else 0
|
||||
``<package>_VERSION_PATCH``
|
||||
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
|
||||
multiple package configuration files are available whose version files
|
||||
@ -170,9 +179,7 @@ version number.
|
||||
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
|
||||
|
||||
::
|
||||
should simply call::
|
||||
|
||||
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
|
||||
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.
|
||||
|
||||
::
|
||||
(U), or Apple (A) conventions::
|
||||
|
||||
<prefix>/ (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
|
||||
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/CMake/ (A)
|
||||
@ -210,11 +213,12 @@ containing a configuration file:
|
||||
<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 NAMES).
|
||||
Paths with lib/<arch> are enabled if CMAKE_LIBRARY_ARCHITECTURE is
|
||||
set. If PATH_SUFFIXES is specified the suffixes are appended to each
|
||||
(W) or (U) directory entry one-by-one.
|
||||
In all cases the ``<name>`` is treated as case-insensitive and corresponds
|
||||
to any of the names specified (``<package>`` or names given by ``NAMES``).
|
||||
Paths with ``lib/<arch>`` are enabled if the
|
||||
:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. 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.
|
||||
@ -225,97 +229,67 @@ 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 variables
|
||||
CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the order of
|
||||
preference as specified below.
|
||||
``CMAKE_FIND_FRAMEWORK`` and ``CMAKE_FIND_APPBUNDLE``
|
||||
determine the order of preference as specified below.
|
||||
|
||||
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
|
||||
are intended to be used on the command line with a -DVAR=value. This
|
||||
can be skipped if NO_CMAKE_PATH is passed.
|
||||
1. Search paths specified in cmake-specific cache variables. These
|
||||
are intended to be used on the command line with a ``-DVAR=value``.
|
||||
This can be skipped if ``NO_CMAKE_PATH`` is passed::
|
||||
|
||||
::
|
||||
CMAKE_PREFIX_PATH
|
||||
CMAKE_FRAMEWORK_PATH
|
||||
CMAKE_APPBUNDLE_PATH
|
||||
|
||||
CMAKE_PREFIX_PATH
|
||||
CMAKE_FRAMEWORK_PATH
|
||||
CMAKE_APPBUNDLE_PATH
|
||||
2. Search paths specified in cmake-specific environment variables.
|
||||
These are intended to be set in the user's shell configuration.
|
||||
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed::
|
||||
|
||||
2. Search paths specified in cmake-specific environment variables.
|
||||
These are intended to be set in the user's shell configuration. This
|
||||
can be skipped if NO_CMAKE_ENVIRONMENT_PATH is passed.
|
||||
<package>_DIR
|
||||
CMAKE_PREFIX_PATH
|
||||
CMAKE_FRAMEWORK_PATH
|
||||
CMAKE_APPBUNDLE_PATH
|
||||
|
||||
::
|
||||
3. 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.
|
||||
|
||||
<package>_DIR
|
||||
CMAKE_PREFIX_PATH
|
||||
CMAKE_FRAMEWORK_PATH
|
||||
CMAKE_APPBUNDLE_PATH
|
||||
4. Search the standard system environment variables. This can be
|
||||
skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries
|
||||
ending in ``/bin`` or ``/sbin`` are automatically converted to their
|
||||
parent directories::
|
||||
|
||||
3. 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.
|
||||
PATH
|
||||
|
||||
4. Search the standard system environment variables. This can be
|
||||
skipped if NO_SYSTEM_ENVIRONMENT_PATH is passed. Path entries ending
|
||||
in "/bin" or "/sbin" are automatically converted to their parent
|
||||
directories.
|
||||
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
|
||||
for the case when a user is building multiple dependent projects one
|
||||
after another.
|
||||
|
||||
::
|
||||
6. Search paths stored in the CMake :ref:`User Package Registry`.
|
||||
This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed.
|
||||
See the :manual:`cmake-packages(7)` manual for details on the user
|
||||
package registry.
|
||||
|
||||
PATH
|
||||
7. Search cmake variables defined in the Platform files for the
|
||||
current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
|
||||
passed::
|
||||
|
||||
5. Search project build trees recently configured in a CMake GUI.
|
||||
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
|
||||
after another.
|
||||
CMAKE_SYSTEM_PREFIX_PATH
|
||||
CMAKE_SYSTEM_FRAMEWORK_PATH
|
||||
CMAKE_SYSTEM_APPBUNDLE_PATH
|
||||
|
||||
6. Search paths stored in the CMake user package registry. This can
|
||||
be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. On Windows a
|
||||
<package> may appear under registry key
|
||||
8. Search paths stored in the CMake :ref:`System Package Registry`.
|
||||
This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed.
|
||||
See the :manual:`cmake-packages(7)` manual for details on the system
|
||||
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
|
||||
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
|
||||
|
||||
8. Search paths stored in the CMake system package registry. This
|
||||
can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed. On
|
||||
Windows a <package> may appear under registry key
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
9. Search paths specified by the ``PATHS`` option. These are typically
|
||||
hard-coded guesses.
|
||||
|
||||
.. |FIND_XXX| replace:: find_package
|
||||
.. |FIND_ARGS_XXX| replace:: <package>
|
||||
@ -326,37 +300,45 @@ hard-coded guesses.
|
||||
.. include:: FIND_XXX_ROOT.txt
|
||||
.. include:: FIND_XXX_ORDER.txt
|
||||
|
||||
Every non-REQUIRED find_package() call can be disabled by setting the
|
||||
variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE. See the
|
||||
documentation for the CMAKE_DISABLE_FIND_PACKAGE_<package> variable
|
||||
for more information.
|
||||
Every non-REQUIRED ``find_package`` call can be disabled by setting the
|
||||
:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``.
|
||||
|
||||
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
|
||||
restores their original state before returning):
|
||||
|
||||
::
|
||||
|
||||
<package>_FIND_REQUIRED = true if REQUIRED option was given
|
||||
<package>_FIND_QUIETLY = true if QUIET option was given
|
||||
<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
|
||||
<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
|
||||
``<package>_FIND_REQUIRED``
|
||||
true if ``REQUIRED`` option was given
|
||||
``<package>_FIND_QUIETLY``
|
||||
true if ``QUIET`` option was given
|
||||
``<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
|
||||
``<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
|
||||
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 <package>_FOUND to false to tell
|
||||
find_package that component requirements are not satisfied.
|
||||
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
|
||||
``<package>_FOUND`` to false to tell ``find_package`` that component
|
||||
requirements are not satisfied.
|
||||
|
||||
See the cmake_policy() command documentation for discussion of the
|
||||
NO_POLICY_SCOPE option.
|
||||
See the :command:`cmake_policy` command documentation for discussion
|
||||
of the ``NO_POLICY_SCOPE`` option.
|
||||
|
||||
@ -488,3 +488,132 @@ Here, the ``ClimbingStats_NOTFOUND_MESSAGE`` is set to a diagnosis that the pack
|
||||
could not be found because an invalid component was specified. This message
|
||||
variable can be set for any case where the ``_FOUND`` variable is set to ``False``,
|
||||
and will be displayed to the user.
|
||||
|
||||
.. _`Package Registry`:
|
||||
|
||||
Package Registry
|
||||
================
|
||||
|
||||
CMake provides two central locations to register packages that have
|
||||
been built or installed anywhere on a system:
|
||||
|
||||
* `User Package Registry`_
|
||||
* `System Package Registry`_
|
||||
|
||||
The registries are especially useful to help projects find packages in
|
||||
non-standard install locations or directly in their own build trees.
|
||||
A project may populate either the user or system registry (using its own
|
||||
means, see below) to refer to its location.
|
||||
In either case the package should store at the registered location a
|
||||
`Package Configuration File`_ (``<package>Config.cmake``) and optionally a
|
||||
`Package Version File`_ (``<package>ConfigVersion.cmake``).
|
||||
|
||||
The :command:`find_package` command searches the two package registries
|
||||
as two of the search steps specified in its documentation. If it has
|
||||
sufficient permissions it also removes stale package registry entries
|
||||
that refer to directories that do not exist or do not contain a matching
|
||||
package configuration file.
|
||||
|
||||
.. _`User Package Registry`:
|
||||
|
||||
User Package Registry
|
||||
---------------------
|
||||
|
||||
The User Package Registry is stored in a per-user location.
|
||||
The :command:`export(PACKAGE)` command may be used to register a project
|
||||
build tree in the user package registry. CMake currently provides no
|
||||
interface to add install trees to the user package registry. Installers
|
||||
must be manually taught to register their packages if desired.
|
||||
|
||||
On Windows the user package registry is stored in the Windows registry
|
||||
under a key in ``HKEY_CURRENT_USER``.
|
||||
|
||||
A ``<package>`` may appear under registry key::
|
||||
|
||||
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 the user package registry is stored in the user home
|
||||
directory under ``~/.cmake/packages``. 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.
|
||||
|
||||
.. _`System Package Registry`:
|
||||
|
||||
System Package Registry
|
||||
-----------------------
|
||||
|
||||
The System Package Registry is stored in a system-wide location.
|
||||
CMake currently provides no interface to add to the system package registry.
|
||||
Installers must be manually taught to register their packages if desired.
|
||||
|
||||
On Windows the system package registry is stored in the Windows registry
|
||||
under a key in ``HKEY_LOCAL_MACHINE``. A ``<package>`` may appear under
|
||||
registry key::
|
||||
|
||||
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.
|
||||
|
||||
Package Registry Example
|
||||
------------------------
|
||||
|
||||
A simple convention for naming package registry entries is to use content
|
||||
hashes. They are deterministic and unlikely to collide
|
||||
(:command:`export(PACKAGE)` uses this approach).
|
||||
The name of an entry referencing a specific directory is simply the content
|
||||
hash of the directory path itself.
|
||||
|
||||
If a project arranges for package registry entries to exist, such as::
|
||||
|
||||
> reg query HKCU\Software\Kitware\CMake\Packages\MyPackage
|
||||
HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage
|
||||
45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage
|
||||
7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build
|
||||
|
||||
or::
|
||||
|
||||
$ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
|
||||
/home/me/work/lib/cmake/MyPackage
|
||||
$ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
|
||||
/home/me/work/MyPackage-build
|
||||
|
||||
then the ``CMakeLists.txt`` code:
|
||||
|
||||
.. code-block:: cmake
|
||||
|
||||
find_package(MyPackage)
|
||||
|
||||
will search the registered locations for package configuration files
|
||||
(``MyPackageConfig.cmake``). The search order among package registry
|
||||
entries for a single package is unspecified and the entry names
|
||||
(hashes in this example) have no meaning. Registered locations may
|
||||
contain package version files (``MyPackageConfigVersion.cmake``) to
|
||||
tell :command:`find_package` whether a specific location is suitable
|
||||
for the version requested.
|
||||
|
||||
Package Registry Ownership
|
||||
--------------------------
|
||||
|
||||
Package registry entries are individually owned by the project installations
|
||||
that they reference. A package installer is responsible for adding its own
|
||||
entry and the corresponding uninstaller is responsible for removing it.
|
||||
|
||||
The :command:`export(PACKAGE)` command populates the user package registry
|
||||
with the location of a project build tree. Build trees tend to be deleted by
|
||||
developers and have no "uninstall" event that could trigger removal of their
|
||||
entries. In order to keep the registries clean the :command:`find_package`
|
||||
command automatically removes stale entries it encounters if it has sufficient
|
||||
permissions. CMake provides no interface to remove an entry referencing an
|
||||
existing build tree once :command:`export(PACKAGE)` has been invoked.
|
||||
However, if the project removes its package configuration file from the build
|
||||
tree then the entry referencing the location will be considered stale.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user