Help: Revise CMAKE_*_PATH and CMAKE_SYSTEM_*_PATH variable docs (#15631)

Improve reStructuredText formatting and cross-references.  Specify
explicitly that each variable may be set to a ;-list of multiple values.
This commit is contained in:
Brad King 2015-06-25 10:04:42 -04:00
parent a6916a6c6e
commit 3117b5feec
14 changed files with 88 additions and 97 deletions

View File

@ -1,5 +1,6 @@
CMAKE_APPBUNDLE_PATH
--------------------
Search path for OS X application bundles used by the :command:`find_program`,
and :command:`find_package` commands.
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for OS X application bundles used by the :command:`find_program`, and
:command:`find_package` commands.

View File

@ -1,7 +1,7 @@
CMAKE_FIND_ROOT_PATH
--------------------
List of root paths to search on the filesystem.
:ref:`;-list <CMake Language Lists>` of root paths to search on the filesystem.
This variable is most useful when cross-compiling. CMake uses the paths in
this list as alternative roots to find filesystem items with :command:`find_package`,

View File

@ -1,6 +1,7 @@
CMAKE_FRAMEWORK_PATH
--------------------
Search path for OS X frameworks used by the :command:`find_library`,
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for OS X frameworks used by the :command:`find_library`,
:command:`find_package`, :command:`find_path`, and :command:`find_file`
commands.

View File

@ -1,17 +1,18 @@
CMAKE_IGNORE_PATH
-----------------
Path to be ignored by FIND_XXX() commands.
:ref:`;-list <CMake Language Lists>` of directories to be *ignored* by
the :command:`find_program`, :command:`find_library`, :command:`find_file`,
and :command:`find_path` commands. This is useful in cross-compiling
environments where some system directories contain incompatible but
possibly linkable libraries. For example, on cross-compiled cluster
environments, this allows a user to ignore directories containing
libraries meant for the front-end machine.
Specifies directories to be ignored by searches in FIND_XXX()
commands. This is useful in cross-compiled environments where some
system directories contain incompatible but possibly linkable
libraries. For example, on cross-compiled cluster environments, this
allows a user to ignore directories containing libraries meant for the
front-end machine that modules like FindX11 (and others) would
normally search. By default this is empty; it is intended to be set
by the project. Note that CMAKE_IGNORE_PATH takes a list of directory
names, NOT a list of prefixes. If you want to ignore paths under
prefixes (bin, include, lib, etc.), you'll need to specify them
explicitly. See also CMAKE_PREFIX_PATH, CMAKE_LIBRARY_PATH,
CMAKE_INCLUDE_PATH, CMAKE_PROGRAM_PATH.
By default this is empty; it is intended to be set by the project.
Note that ``CMAKE_IGNORE_PATH`` takes a list of directory names, *not*
a list of prefixes. To ignore paths under prefixes (``bin``, ``include``,
``lib``, etc.), specify them explicitly.
See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`,
:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables.

View File

@ -1,10 +1,7 @@
CMAKE_INCLUDE_PATH
------------------
Path used for searching by FIND_FILE() and FIND_PATH().
Specifies a path which will be used both by FIND_FILE() and
FIND_PATH(). Both commands will check each of the contained
directories for the existence of the file which is currently searched.
By default it is empty, it is intended to be set by the project. See
also CMAKE_SYSTEM_INCLUDE_PATH, CMAKE_PREFIX_PATH.
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for the :command:`find_file` and :command:`find_path` commands. By default it
is empty, it is intended to be set by the project. See also
:variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`.

View File

@ -1,10 +1,7 @@
CMAKE_LIBRARY_PATH
------------------
Path used for searching by FIND_LIBRARY().
Specifies a path which will be used by FIND_LIBRARY(). FIND_LIBRARY()
will check each of the contained directories for the existence of the
library which is currently searched. By default it is empty, it is
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for the :command:`find_library` command. By default it is empty, it is
intended to be set by the project. See also
CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_PREFIX_PATH.
:variable:`CMAKE_SYSTEM_LIBRARY_PATH` and :variable:`CMAKE_PREFIX_PATH`.

View File

@ -1,8 +1,7 @@
CMAKE_MODULE_PATH
-----------------
List of directories to search for CMake modules.
Commands like include() and find_package() search for files in
directories listed by this variable before checking the default
modules that come with CMake.
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for CMake modules to be loaded by the the :command:`include` or
:command:`find_package` commands before checking the default modules that come
with CMake. By default it is empty, it is intended to be set by the project.

View File

@ -1,13 +1,15 @@
CMAKE_PREFIX_PATH
-----------------
Path used for searching by FIND_XXX(), with appropriate suffixes added.
:ref:`;-list <CMake Language Lists>` of directories specifying installation
*prefixes* to be searched by the :command:`find_package`,
:command:`find_program`, :command:`find_library`, :command:`find_file`, and
:command:`find_path` commands. Each command will add appropriate
subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own
documentation.
Specifies a path which will be used by the FIND_XXX() commands. It
contains the "base" directories, the FIND_XXX() commands append
appropriate subdirectories to the base directories. So FIND_PROGRAM()
adds /bin to each of the directories in the path, FIND_LIBRARY()
appends /lib to each of the directories, and FIND_PATH() and
FIND_FILE() append /include . By default it is empty, it is intended
to be set by the project. See also CMAKE_SYSTEM_PREFIX_PATH,
CMAKE_INCLUDE_PATH, CMAKE_LIBRARY_PATH, CMAKE_PROGRAM_PATH.
By default this is empty. It is intended to be set by the project.
See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`, :variable:`CMAKE_INCLUDE_PATH`,
:variable:`CMAKE_LIBRARY_PATH`, :variable:`CMAKE_PROGRAM_PATH`, and
:variable:`CMAKE_IGNORE_PATH`.

View File

@ -1,10 +1,7 @@
CMAKE_PROGRAM_PATH
------------------
Path used for searching by FIND_PROGRAM().
Specifies a path which will be used by FIND_PROGRAM(). FIND_PROGRAM()
will check each of the contained directories for the existence of the
program which is currently searched. By default it is empty, it is
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for the :command:`find_program` command. By default it is empty, it is
intended to be set by the project. See also
CMAKE_SYSTEM_PROGRAM_PATH, CMAKE_PREFIX_PATH.
:variable:`CMAKE_SYSTEM_PROGRAM_PATH` and :variable:`CMAKE_PREFIX_PATH`.

View File

@ -1,15 +1,18 @@
CMAKE_SYSTEM_IGNORE_PATH
------------------------
Path to be ignored by FIND_XXX() commands.
:ref:`;-list <CMake Language Lists>` of directories to be *ignored* by
the :command:`find_program`, :command:`find_library`, :command:`find_file`,
and :command:`find_path` commands. This is useful in cross-compiling
environments where some system directories contain incompatible but
possibly linkable libraries. For example, on cross-compiled cluster
environments, this allows a user to ignore directories containing
libraries meant for the front-end machine.
Specifies directories to be ignored by searches in FIND_XXX()
commands. This is useful in cross-compiled environments where some
system directories contain incompatible but possibly linkable
libraries. For example, on cross-compiled cluster environments, this
allows a user to ignore directories containing libraries meant for the
front-end machine that modules like FindX11 (and others) would
normally search. By default this contains a list of directories
containing incompatible binaries for the host system. See also
CMAKE_SYSTEM_PREFIX_PATH, CMAKE_SYSTEM_LIBRARY_PATH,
CMAKE_SYSTEM_INCLUDE_PATH, and CMAKE_SYSTEM_PROGRAM_PATH.
By default this contains a list of directories containing incompatible
binaries for the host system. See the :variable:`CMAKE_IGNORE_PATH` variable
that is intended to be set by the project.
See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`,
:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`,
and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables.

View File

@ -1,11 +1,8 @@
CMAKE_SYSTEM_INCLUDE_PATH
-------------------------
Path used for searching by FIND_FILE() and FIND_PATH().
Specifies a path which will be used both by FIND_FILE() and
FIND_PATH(). Both commands will check each of the contained
directories for the existence of the file which is currently searched.
By default it contains the standard directories for the current
system. It is NOT intended to be modified by the project, use
CMAKE_INCLUDE_PATH for this. See also CMAKE_SYSTEM_PREFIX_PATH.
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for the :command:`find_file` and :command:`find_path` commands. By default
this contains the standard directories for the current system. It is *not*
intended to be modified by the project; use :variable:`CMAKE_INCLUDE_PATH` for
this. See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`.

View File

@ -1,11 +1,8 @@
CMAKE_SYSTEM_LIBRARY_PATH
-------------------------
Path used for searching by FIND_LIBRARY().
Specifies a path which will be used by FIND_LIBRARY(). FIND_LIBRARY()
will check each of the contained directories for the existence of the
library which is currently searched. By default it contains the
standard directories for the current system. It is NOT intended to be
modified by the project, use CMAKE_LIBRARY_PATH for this. See also
CMAKE_SYSTEM_PREFIX_PATH.
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for the :command:`find_library` command. By default this contains the
standard directories for the current system. It is *not* intended to be
modified by the project; use :variable:`CMAKE_LIBRARY_PATH` for this.
See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`.

View File

@ -1,16 +1,18 @@
CMAKE_SYSTEM_PREFIX_PATH
------------------------
Path used for searching by FIND_XXX(), with appropriate suffixes added.
:ref:`;-list <CMake Language Lists>` of directories specifying installation
*prefixes* to be searched by the :command:`find_package`,
:command:`find_program`, :command:`find_library`, :command:`find_file`, and
:command:`find_path` commands. Each command will add appropriate
subdirectories (like ``bin``, ``lib``, or ``include``) as specified in its own
documentation.
Specifies a path which will be used by the FIND_XXX() commands. It
contains the "base" directories, the FIND_XXX() commands append
appropriate subdirectories to the base directories. So FIND_PROGRAM()
adds /bin to each of the directories in the path, FIND_LIBRARY()
appends /lib to each of the directories, and FIND_PATH() and
FIND_FILE() append /include . By default this contains the standard
directories for the current system, the CMAKE_INSTALL_PREFIX and
the :variable:`CMAKE_STAGING_PREFIX`. It is NOT intended to be modified by
the project, use CMAKE_PREFIX_PATH for this. See also CMAKE_SYSTEM_INCLUDE_PATH,
CMAKE_SYSTEM_LIBRARY_PATH, CMAKE_SYSTEM_PROGRAM_PATH, and
CMAKE_SYSTEM_IGNORE_PATH.
By default this contains the standard directories for the current system, the
:variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`.
It is *not* intended to be modified by the project; use
:variable:`CMAKE_PREFIX_PATH` for this.
See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH`,
:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_PROGRAM_PATH`,
and :variable:`CMAKE_SYSTEM_IGNORE_PATH`.

View File

@ -1,11 +1,8 @@
CMAKE_SYSTEM_PROGRAM_PATH
-------------------------
Path used for searching by FIND_PROGRAM().
Specifies a path which will be used by FIND_PROGRAM(). FIND_PROGRAM()
will check each of the contained directories for the existence of the
program which is currently searched. By default it contains the
standard directories for the current system. It is NOT intended to be
modified by the project, use CMAKE_PROGRAM_PATH for this. See also
CMAKE_SYSTEM_PREFIX_PATH.
:ref:`;-list <CMake Language Lists>` of directories specifying a search path
for the :command:`find_program` command. By default this contains the
standard directories for the current system. It is *not* intended to be
modified by the project; use :variable:`CMAKE_PROGRAM_PATH` for this.
See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`.