Help: Improve documentation formatting of find_* commands
Use inline reStructuredText markup and add cross-references in more places.
This commit is contained in:
parent
8c64c4783d
commit
3de3544fcd
|
@ -33,36 +33,42 @@ 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.
|
||||
The name of the |SEARCH_XXX| that
|
||||
is searched for is specified by the names listed
|
||||
after the NAMES argument. Additional search locations
|
||||
can be specified after the PATHS argument. If ENV var is
|
||||
found in the HINTS or PATHS section the environment variable var
|
||||
will be read and converted from a system environment variable to
|
||||
a cmake style list of paths. For example ENV PATH would be a way
|
||||
to list the system path variable. The argument
|
||||
after DOC will be used for the documentation string in
|
||||
the cache.
|
||||
PATH_SUFFIXES specifies additional subdirectories to check below
|
||||
each search path.
|
||||
|
||||
If NO_DEFAULT_PATH is specified, then no additional paths are
|
||||
Options include:
|
||||
|
||||
``NAMES``
|
||||
Specify one or more possible names for the |SEARCH_XXX|.
|
||||
|
||||
``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:
|
||||
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
|
||||
|
||||
.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
|
||||
<prefix>/|XXX_SUBDIR| for each <prefix> in CMAKE_PREFIX_PATH
|
||||
|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
|
||||
|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 CMAKE_SYSTEM_PREFIX_PATH
|
||||
|prefix_XXX_SUBDIR| for each ``<prefix>`` in
|
||||
:variable:`CMAKE_SYSTEM_PREFIX_PATH`
|
||||
|
||||
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.
|
||||
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_XXX|
|
||||
* |CMAKE_XXX_PATH|
|
||||
|
@ -70,24 +76,24 @@ If NO_DEFAULT_PATH is not specified, the search process is as follows:
|
|||
|
||||
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.
|
||||
This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed.
|
||||
|
||||
* |CMAKE_PREFIX_PATH_XXX|
|
||||
* |CMAKE_XXX_PATH|
|
||||
* |CMAKE_XXX_MAC_PATH|
|
||||
|
||||
3. Search the paths specified by the HINTS option.
|
||||
3. 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.
|
||||
Hard-coded guesses should be specified with the ``PATHS`` option.
|
||||
|
||||
4. Search the standard system environment variables.
|
||||
This can be skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
|
||||
This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
|
||||
|
||||
* |SYSTEM_ENVIRONMENT_PATH_XXX|
|
||||
|
||||
5. Search cmake variables defined in the Platform files
|
||||
for the current system. This can be skipped if NO_CMAKE_SYSTEM_PATH
|
||||
for the current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
|
||||
is passed.
|
||||
|
||||
* |CMAKE_SYSTEM_PREFIX_PATH_XXX|
|
||||
|
|
|
@ -16,8 +16,14 @@ search there too. By default at first the directories listed in
|
|||
directory is searched, and then the non-rooted directories will be
|
||||
searched. The default behavior can be adjusted by setting
|
||||
|CMAKE_FIND_ROOT_PATH_MODE_XXX|. This behavior can be manually
|
||||
overridden on a per-call basis. By using CMAKE_FIND_ROOT_PATH_BOTH
|
||||
the search order will be as described above. If
|
||||
NO_CMAKE_FIND_ROOT_PATH is used then :variable:`CMAKE_FIND_ROOT_PATH` will not be
|
||||
used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
|
||||
directories and directories below :variable:`CMAKE_STAGING_PREFIX` will be searched.
|
||||
overridden on a per-call basis using options:
|
||||
|
||||
``CMAKE_FIND_ROOT_PATH_BOTH``
|
||||
Search in the order described above.
|
||||
|
||||
``NO_CMAKE_FIND_ROOT_PATH``
|
||||
Do not use the :variable:`CMAKE_FIND_ROOT_PATH` variable.
|
||||
|
||||
``ONLY_CMAKE_FIND_ROOT_PATH``
|
||||
Search only the re-rooted directories and directories below
|
||||
:variable:`CMAKE_STAGING_PREFIX`.
|
||||
|
|
|
@ -5,24 +5,27 @@ find_file
|
|||
.. |NAMES| replace:: NAMES name1 [name2 ...]
|
||||
.. |SEARCH_XXX| replace:: full path to a file
|
||||
.. |SEARCH_XXX_DESC| replace:: full path to named file
|
||||
.. |XXX_SUBDIR| replace:: include
|
||||
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
|
||||
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
|
||||
|
||||
.. |CMAKE_PREFIX_PATH_XXX| replace::
|
||||
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
|
||||
.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
|
||||
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||
is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
|
||||
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
|
||||
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE,
|
||||
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
|
||||
and the directories in PATH itself.
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``,
|
||||
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
|
||||
directories in ``PATH`` itself.
|
||||
|
||||
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
|
||||
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH
|
||||
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
|
||||
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||
is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_SYSTEM_XXX_PATH| replace::
|
||||
:variable:`CMAKE_SYSTEM_INCLUDE_PATH`
|
||||
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
|
||||
:variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
|
||||
|
||||
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
|
||||
:variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
|
||||
|
|
|
@ -5,33 +5,36 @@ find_library
|
|||
.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
|
||||
.. |SEARCH_XXX| replace:: library
|
||||
.. |SEARCH_XXX_DESC| replace:: library
|
||||
.. |XXX_SUBDIR| replace:: lib
|
||||
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/lib``
|
||||
.. |entry_XXX_SUBDIR| replace:: ``<entry>/lib``
|
||||
|
||||
.. |CMAKE_PREFIX_PATH_XXX| replace::
|
||||
<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH
|
||||
.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
|
||||
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
|
||||
and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_LIBRARY_PATH`
|
||||
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
|
||||
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in LIB,
|
||||
<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
|
||||
and the directories in PATH itself.
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``LIB``,
|
||||
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
|
||||
and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
|
||||
and the directories in ``PATH`` itself.
|
||||
|
||||
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
|
||||
<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_LIBRARY_PATH
|
||||
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
|
||||
``<prefix>/lib/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE` is set,
|
||||
and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_SYSTEM_XXX_PATH| replace::
|
||||
:variable:`CMAKE_SYSTEM_LIBRARY_PATH`
|
||||
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
|
||||
:variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
|
||||
|
||||
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
|
||||
:variable:`CMAKE_FIND_ROOT_PATH_MODE_LIBRARY`
|
||||
|
||||
.. include:: FIND_XXX.txt
|
||||
|
||||
When more than one value is given to the NAMES option this command by
|
||||
When more than one value is given to the ``NAMES`` option this command by
|
||||
default will consider one name at a time and search every directory
|
||||
for it. The NAMES_PER_DIR option tells this command to consider one
|
||||
for it. The ``NAMES_PER_DIR`` option tells this command to consider one
|
||||
directory at a time and search for all names in it.
|
||||
|
||||
Each library name given to the ``NAMES`` option is first considered
|
||||
|
@ -40,14 +43,14 @@ prefixes (e.g. ``lib``) and suffixes (e.g. ``.so``). Therefore one
|
|||
may specify library file names such as ``libfoo.a`` directly.
|
||||
This can be used to locate static libraries on UNIX-like systems.
|
||||
|
||||
If the library found is a framework, then VAR will be set to the full
|
||||
path to the framework <fullPath>/A.framework. When a full path to a
|
||||
framework is used as a library, CMake will use a -framework A, and a
|
||||
-F<fullPath> to link the framework to the target.
|
||||
If the library found is a framework, then ``<VAR>`` will be set to the full
|
||||
path to the framework ``<fullPath>/A.framework``. When a full path to a
|
||||
framework is used as a library, CMake will use a ``-framework A``, and a
|
||||
``-F<fullPath>`` to link the framework to the target.
|
||||
|
||||
If the global property FIND_LIBRARY_USE_LIB64_PATHS is set all search
|
||||
paths will be tested as normal, with "64/" appended, and with all
|
||||
matches of "lib/" replaced with "lib64/". This property is
|
||||
If the :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` global property is set
|
||||
all search paths will be tested as normal, with ``64/`` appended, and
|
||||
with all matches of ``lib/`` replaced with ``lib64/``. This property is
|
||||
automatically set for the platforms that are known to need it if at
|
||||
least one of the languages supported by the PROJECT command is
|
||||
enabled.
|
||||
least one of the languages supported by the :command:`project` command
|
||||
is enabled.
|
||||
|
|
|
@ -5,31 +5,34 @@ find_path
|
|||
.. |NAMES| replace:: NAMES name1 [name2 ...]
|
||||
.. |SEARCH_XXX| replace:: file in a directory
|
||||
.. |SEARCH_XXX_DESC| replace:: directory containing the named file
|
||||
.. |XXX_SUBDIR| replace:: include
|
||||
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/include``
|
||||
.. |entry_XXX_SUBDIR| replace:: ``<entry>/include``
|
||||
|
||||
.. |CMAKE_PREFIX_PATH_XXX| replace::
|
||||
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
|
||||
.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
|
||||
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||
is set, and |CMAKE_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_INCLUDE_PATH`
|
||||
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_FRAMEWORK_PATH`
|
||||
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in INCLUDE,
|
||||
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|,
|
||||
and the directories in PATH itself.
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: Directories in ``INCLUDE``,
|
||||
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||
is set, and |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR|, and the
|
||||
directories in ``PATH`` itself.
|
||||
|
||||
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
|
||||
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
|
||||
|CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_INCLUDE_PATH
|
||||
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_FRAMEWORK_PATH
|
||||
``<prefix>/include/<arch>`` if :variable:`CMAKE_LIBRARY_ARCHITECTURE`
|
||||
is set, and |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_SYSTEM_XXX_PATH| replace::
|
||||
:variable:`CMAKE_SYSTEM_INCLUDE_PATH`
|
||||
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
|
||||
:variable:`CMAKE_SYSTEM_FRAMEWORK_PATH`
|
||||
|
||||
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
|
||||
:variable:`CMAKE_FIND_ROOT_PATH_MODE_INCLUDE`
|
||||
|
||||
.. include:: FIND_XXX.txt
|
||||
|
||||
When searching for frameworks, if the file is specified as A/b.h, then
|
||||
the framework search will look for A.framework/Headers/b.h. If that
|
||||
When searching for frameworks, if the file is specified as ``A/b.h``, then
|
||||
the framework search will look for ``A.framework/Headers/b.h``. If that
|
||||
is found the path will be set to the path to the framework. CMake
|
||||
will convert this to the correct -F option to include the file.
|
||||
will convert this to the correct ``-F`` option to include the file.
|
||||
|
|
|
@ -5,19 +5,22 @@ find_program
|
|||
.. |NAMES| replace:: NAMES name1 [name2 ...]
|
||||
.. |SEARCH_XXX| replace:: program
|
||||
.. |SEARCH_XXX_DESC| replace:: program
|
||||
.. |XXX_SUBDIR| replace:: [s]bin
|
||||
.. |prefix_XXX_SUBDIR| replace:: ``<prefix>/[s]bin``
|
||||
.. |entry_XXX_SUBDIR| replace:: ``<entry>/[s]bin``
|
||||
|
||||
.. |CMAKE_PREFIX_PATH_XXX| replace::
|
||||
|CMAKE_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_XXX_PATH| replace:: CMAKE_PROGRAM_PATH
|
||||
.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_APPBUNDLE_PATH
|
||||
.. |CMAKE_XXX_PATH| replace:: :variable:`CMAKE_PROGRAM_PATH`
|
||||
.. |CMAKE_XXX_MAC_PATH| replace:: :variable:`CMAKE_APPBUNDLE_PATH`
|
||||
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH
|
||||
.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: ``PATH``
|
||||
|
||||
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
|
||||
|CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR|
|
||||
.. |CMAKE_SYSTEM_XXX_PATH| replace:: CMAKE_SYSTEM_PROGRAM_PATH
|
||||
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace:: CMAKE_SYSTEM_APPBUNDLE_PATH
|
||||
.. |CMAKE_SYSTEM_XXX_PATH| replace::
|
||||
:variable:`CMAKE_SYSTEM_PROGRAM_PATH`
|
||||
.. |CMAKE_SYSTEM_XXX_MAC_PATH| replace::
|
||||
:variable:`CMAKE_SYSTEM_APPBUNDLE_PATH`
|
||||
|
||||
.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
|
||||
:variable:`CMAKE_FIND_ROOT_PATH_MODE_PROGRAM`
|
||||
|
|
Loading…
Reference in New Issue