mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-05 13:20:47 -06:00
492ade276b
Add documentation for both the CMake variable and environment variable of this name pattern. Update references to these names to link to their documents. Clarify the pattern used to construct their names.
146 lines
5.2 KiB
Plaintext
146 lines
5.2 KiB
Plaintext
A short-hand signature is:
|
|
|
|
.. parsed-literal::
|
|
|
|
|FIND_XXX| (<VAR> name1 [path1 path2 ...])
|
|
|
|
The general signature is:
|
|
|
|
.. parsed-literal::
|
|
|
|
|FIND_XXX| (
|
|
<VAR>
|
|
name | |NAMES|
|
|
[HINTS path1 [path2 ... ENV var]]
|
|
[PATHS path1 [path2 ... ENV var]]
|
|
[PATH_SUFFIXES suffix1 [suffix2 ...]]
|
|
[DOC "cache documentation string"]
|
|
[NO_DEFAULT_PATH]
|
|
[NO_PACKAGE_ROOT_PATH]
|
|
[NO_CMAKE_PATH]
|
|
[NO_CMAKE_ENVIRONMENT_PATH]
|
|
[NO_SYSTEM_ENVIRONMENT_PATH]
|
|
[NO_CMAKE_SYSTEM_PATH]
|
|
[CMAKE_FIND_ROOT_PATH_BOTH |
|
|
ONLY_CMAKE_FIND_ROOT_PATH |
|
|
NO_CMAKE_FIND_ROOT_PATH]
|
|
)
|
|
|
|
This command is used to find a |SEARCH_XXX_DESC|.
|
|
A cache entry named by ``<VAR>`` is created to store the result
|
|
of this command.
|
|
If the |SEARCH_XXX| is found the result is stored in the variable
|
|
and the search will not be repeated unless the variable is cleared.
|
|
If nothing is found, the result will be
|
|
``<VAR>-NOTFOUND``, and the search will be attempted again the
|
|
next time |FIND_XXX| is invoked with the same variable.
|
|
|
|
Options include:
|
|
|
|
``NAMES``
|
|
Specify one or more possible names for the |SEARCH_XXX|.
|
|
|
|
When using this to specify names with and without a version
|
|
suffix, we recommend specifying the unversioned name first
|
|
so that locally-built packages can be found before those
|
|
provided by distributions.
|
|
|
|
``HINTS``, ``PATHS``
|
|
Specify directories to search in addition to the default locations.
|
|
The ``ENV var`` sub-option reads paths from a system environment
|
|
variable.
|
|
|
|
``PATH_SUFFIXES``
|
|
Specify additional subdirectories to check below each directory
|
|
location otherwise considered.
|
|
|
|
``DOC``
|
|
Specify the documentation string for the ``<VAR>`` cache entry.
|
|
|
|
If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
|
|
added to the search.
|
|
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
|
|
|
|
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
|
|
|prefix_XXX_SUBDIR| for each ``<prefix>`` in the
|
|
:variable:`<PackageName>_ROOT` CMake variable and the
|
|
:envvar:`<PackageName>_ROOT` environment variable if
|
|
called from within a find module loaded by
|
|
:command:`find_package(<PackageName>)`
|
|
|
|
.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
|
|
|prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
|
|
|
|
.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
|
|
|prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
|
|
|entry_XXX_SUBDIR| for other entries in ``PATH``
|
|
|
|
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
|
|
|prefix_XXX_SUBDIR| for each ``<prefix>`` in
|
|
:variable:`CMAKE_SYSTEM_PREFIX_PATH`
|
|
|
|
1. If called from within a find module loaded by
|
|
:command:`find_package(<PackageName>)`, search prefixes unique to the
|
|
current package being found. Specifically look in the
|
|
:variable:`<PackageName>_ROOT` CMake variable and the
|
|
:envvar:`<PackageName>_ROOT` environment variable.
|
|
The package root variables are maintained as a stack so if called from
|
|
nested find modules, root paths from the parent's find module will be
|
|
searched after paths from the current module,
|
|
i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
|
|
``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
|
|
This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
|
|
See policy :policy:`CMP0074`.
|
|
|
|
* |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
|
|
|
|
2. 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 :ref:`;-lists <CMake Language Lists>`.
|
|
This can be skipped if ``NO_CMAKE_PATH`` is passed.
|
|
|
|
* |CMAKE_PREFIX_PATH_XXX|
|
|
* |CMAKE_XXX_PATH|
|
|
* |CMAKE_XXX_MAC_PATH|
|
|
|
|
3. 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.
|
|
|
|
* |CMAKE_PREFIX_PATH_XXX|
|
|
* |CMAKE_XXX_PATH|
|
|
* |CMAKE_XXX_MAC_PATH|
|
|
|
|
4. Search the 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.
|
|
|
|
5. Search the standard system environment variables.
|
|
This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
|
|
|
|
* |SYSTEM_ENVIRONMENT_PATH_XXX|
|
|
|
|
6. 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_XXX|
|
|
* |CMAKE_SYSTEM_XXX_PATH|
|
|
* |CMAKE_SYSTEM_XXX_MAC_PATH|
|
|
|
|
7. Search the paths specified by the PATHS option
|
|
or in the short-hand version of the command.
|
|
These are typically hard-coded guesses.
|
|
|
|
.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name
|
|
|
|
On OS X the :variable:`CMAKE_FIND_FRAMEWORK` and
|
|
:variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
|
|
preference between Apple-style and unix-style package components.
|
|
|
|
.. include:: FIND_XXX_ROOT.txt
|
|
.. include:: FIND_XXX_ORDER.txt
|