Merge topic 'doc-find-path-variables'

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

Help/variable/CMAKE_APPBUNDLE_PATH.rst

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

Help/variable/CMAKE_FIND_ROOT_PATH.rst

@@ -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`,

Help/variable/CMAKE_FRAMEWORK_PATH.rst

@@ -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.

Help/variable/CMAKE_IGNORE_PATH.rst

@@ -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()
+By default this is empty; it is intended to be set by the project.
-commands.  This is useful in cross-compiled environments where some
+Note that ``CMAKE_IGNORE_PATH`` takes a list of directory names, *not*
-system directories contain incompatible but possibly linkable
+a list of prefixes.  To ignore paths under prefixes (``bin``, ``include``,
-libraries.  For example, on cross-compiled cluster environments, this
+``lib``, etc.), specify them explicitly.
-allows a user to ignore directories containing libraries meant for the
+
-front-end machine that modules like FindX11 (and others) would
+See also the :variable:`CMAKE_PREFIX_PATH`, :variable:`CMAKE_LIBRARY_PATH`,
-normally search.  By default this is empty; it is intended to be set
+:variable:`CMAKE_INCLUDE_PATH`, and :variable:`CMAKE_PROGRAM_PATH` variables.
-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.

Help/variable/CMAKE_INCLUDE_PATH.rst

@@ -1,10 +1,7 @@
 CMAKE_INCLUDE_PATH
 ------------------
 
-Path used for searching by FIND_FILE() and FIND_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
-Specifies a path which will be used both by FIND_FILE() and
+is empty, it is intended to be set by the project.  See also
-FIND_PATH().  Both commands will check each of the contained
+:variable:`CMAKE_SYSTEM_INCLUDE_PATH` and :variable:`CMAKE_PREFIX_PATH`.
-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.

Help/variable/CMAKE_LIBRARY_PATH.rst

@@ -1,10 +1,7 @@
 CMAKE_LIBRARY_PATH
 ------------------
 
-Path used for searching by FIND_LIBRARY().
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
-
+for the :command:`find_library` command.  By default it is empty, it is
-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
 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`.

Help/variable/CMAKE_MODULE_PATH.rst

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

Help/variable/CMAKE_PREFIX_PATH.rst

@@ -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
+By default this is empty.  It is intended to be set by the project.
-contains the "base" directories, the FIND_XXX() commands append
+
-appropriate subdirectories to the base directories.  So FIND_PROGRAM()
+See also :variable:`CMAKE_SYSTEM_PREFIX_PATH`, :variable:`CMAKE_INCLUDE_PATH`,
-adds /bin to each of the directories in the path, FIND_LIBRARY()
+:variable:`CMAKE_LIBRARY_PATH`, :variable:`CMAKE_PROGRAM_PATH`, and
-appends /lib to each of the directories, and FIND_PATH() and
+:variable:`CMAKE_IGNORE_PATH`.
-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.

Help/variable/CMAKE_PROGRAM_PATH.rst

@@ -1,10 +1,7 @@
 CMAKE_PROGRAM_PATH
 ------------------
 
-Path used for searching by FIND_PROGRAM().
+:ref:`;-list <CMake Language Lists>` of directories specifying a search path
-
+for the :command:`find_program` command.  By default it is empty, it is
-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
 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`.

Help/variable/CMAKE_SYSTEM_IGNORE_PATH.rst

@@ -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()
+By default this contains a list of directories containing incompatible
-commands.  This is useful in cross-compiled environments where some
+binaries for the host system.  See the :variable:`CMAKE_IGNORE_PATH` variable
-system directories contain incompatible but possibly linkable
+that is intended to be set by the project.
-libraries.  For example, on cross-compiled cluster environments, this
+
-allows a user to ignore directories containing libraries meant for the
+See also the :variable:`CMAKE_SYSTEM_PREFIX_PATH`,
-front-end machine that modules like FindX11 (and others) would
+:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_INCLUDE_PATH`,
-normally search.  By default this contains a list of directories
+and :variable:`CMAKE_SYSTEM_PROGRAM_PATH` variables.
-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.

Help/variable/CMAKE_SYSTEM_INCLUDE_PATH.rst

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

Help/variable/CMAKE_SYSTEM_LIBRARY_PATH.rst

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

Help/variable/CMAKE_SYSTEM_PREFIX_PATH.rst

@@ -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
+By default this contains the standard directories for the current system, the
-contains the "base" directories, the FIND_XXX() commands append
+:variable:`CMAKE_INSTALL_PREFIX`, and the :variable:`CMAKE_STAGING_PREFIX`.
-appropriate subdirectories to the base directories.  So FIND_PROGRAM()
+It is *not* intended to be modified by the project; use
-adds /bin to each of the directories in the path, FIND_LIBRARY()
+:variable:`CMAKE_PREFIX_PATH` for this.
-appends /lib to each of the directories, and FIND_PATH() and
+
-FIND_FILE() append /include .  By default this contains the standard
+See also :variable:`CMAKE_SYSTEM_INCLUDE_PATH`,
-directories for the current system, the CMAKE_INSTALL_PREFIX and
+:variable:`CMAKE_SYSTEM_LIBRARY_PATH`, :variable:`CMAKE_SYSTEM_PROGRAM_PATH`,
-the :variable:`CMAKE_STAGING_PREFIX`.  It is NOT intended to be modified by
+and :variable:`CMAKE_SYSTEM_IGNORE_PATH`.
-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.

Help/variable/CMAKE_SYSTEM_PROGRAM_PATH.rst

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