kolan
/
CMake
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
CMake/Help/command/FIND_XXX.txt

120 lines
4.0 KiB
Plaintext
Raw Normal View History

Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
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_CMAKE_ENVIRONMENT_PATH]
[NO_CMAKE_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.
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
Options include:
``NAMES``
Specify one or more possible names for the |SEARCH_XXX|.
Help: Document find_* command versioned/unversioned name ordering Suggest in the NAMES option that unversioned names go first to prefer local builds over distro-provided files.
2015-06-08 23:11:10 +03:00
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.
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
``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
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
added to the search.
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
|prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
Teach find_(library|file|path) to get prefixes from PATH (#15370) The find_package command already knows how to compute installation prefixes from PATH. Use the same approach to establish prefixes for find_library, find_file, and find_path to use to look in directories like "<prefix>/lib[/<arch>]" and "<prefix>/include" for libraries and headers. This will reduce the amount of configuration end users need to do to establish a work environment rooted under a specific prefix.
2015-02-18 18:54:45 +03:00
.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
|prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
|entry_XXX_SUBDIR| for other entries in ``PATH``
Teach find_(library|file|path) to get prefixes from PATH (#15370) The find_package command already knows how to compute installation prefixes from PATH. Use the same approach to establish prefixes for find_library, find_file, and find_path to use to look in directories like "<prefix>/lib[/<arch>]" and "<prefix>/include" for libraries and headers. This will reduce the amount of configuration end users need to do to establish a work environment rooted under a specific prefix.
2015-02-18 18:54:45 +03:00
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
|prefix_XXX_SUBDIR| for each ``<prefix>`` in
:variable:`CMAKE_SYSTEM_PREFIX_PATH`
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
1. Search paths specified in cmake-specific cache variables.
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
These are intended to be used on the command line with a ``-DVAR=value``.
This can be skipped if ``NO_CMAKE_PATH`` is passed.
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
* |CMAKE_PREFIX_PATH_XXX|
* |CMAKE_XXX_PATH|
* |CMAKE_XXX_MAC_PATH|
2. Search paths specified in cmake-specific environment variables.
These are intended to be set in the user's shell configuration.
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed.
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
* |CMAKE_PREFIX_PATH_XXX|
* |CMAKE_XXX_PATH|
* |CMAKE_XXX_MAC_PATH|
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
3. Search the paths specified by the ``HINTS`` option.
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
These should be paths computed by system introspection, such as a
hint provided by the location of another item already found.
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
Hard-coded guesses should be specified with the ``PATHS`` option.
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
4. Search the standard system environment variables.
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
* |SYSTEM_ENVIRONMENT_PATH_XXX|
5. Search cmake variables defined in the Platform files
Help: Improve documentation formatting of find_* commands Use inline reStructuredText markup and add cross-references in more places.
2015-06-08 22:52:21 +03:00
for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
is passed.
* |CMAKE_SYSTEM_PREFIX_PATH_XXX|
* |CMAKE_SYSTEM_XXX_PATH|
* |CMAKE_SYSTEM_XXX_MAC_PATH|
6. 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
Help: Document CMAKE_FIND_APPBUNDLE and CMAKE_FIND_FRAMEWORK Add dedicated documents for these and link to them instead of duplicating their documentation in every find command.
2015-06-08 22:36:31 +03:00
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.
Help: Factor out find_* command duplication These documents were represented in the builtin documentation using a common starting point with placeholders substituted by each command. Convert them back to this approach using the reStructuredText include directive and substitutions to avoid duplication.
2013-10-01 20:37:02 +04:00
.. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt