Skip to content

GitLab

Commit 3de3544f authored by Brad King's avatar Brad King
Browse files

Help: Improve documentation formatting of find_* commands 

Use inline reStructuredText markup and add cross-references in more
places.
parent 8c64c478
Hide whitespace changes
Inline Side-by-side
Showing with 114 additions and 90 deletions
Help/command/FIND_XXX.txt
View file @ 3de3544f
......@@ -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|
......
Help/command/FIND_XXX_ROOT.txt
View file @ 3de3544f
......@@ -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`.
Help/command/find_file.rst
View file @ 3de3544f
......@@ -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`
......
Help/command/find_library.rst
View file @ 3de3544f
......@@ -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.
Help/command/find_path.rst
View file @ 3de3544f
......@@ -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.
Help/command/find_program.rst
View file @ 3de3544f
......@@ -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`
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment