summaryrefslogtreecommitdiffstats
path: root/Help
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2013-10-01 16:37:02 (GMT)
committerBrad King <brad.king@kitware.com>2013-10-16 13:22:38 (GMT)
commit898216137a184940867a1678b07ca8470b2d7b85 (patch)
tree9609a6314708675177dfe3c48ba19f64f0b8e640 /Help
parent30b21860adaefa7493262c41f0b95b4065d46aa3 (diff)
downloadCMake-898216137a184940867a1678b07ca8470b2d7b85.zip
CMake-898216137a184940867a1678b07ca8470b2d7b85.tar.gz
CMake-898216137a184940867a1678b07ca8470b2d7b85.tar.bz2
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.
Diffstat (limited to 'Help')
-rw-r--r--Help/command/FIND_XXX.txt101
-rw-r--r--Help/command/FIND_XXX_MAC.txt24
-rw-r--r--Help/command/FIND_XXX_ORDER.txt12
-rw-r--r--Help/command/FIND_XXX_ROOT.txt14
-rw-r--r--Help/command/find_file.rst161
-rw-r--r--Help/command/find_library.rst161
-rw-r--r--Help/command/find_package.rst60
-rw-r--r--Help/command/find_path.rst162
-rw-r--r--Help/command/find_program.rst160
9 files changed, 227 insertions, 628 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
new file mode 100644
index 0000000..5889e90
--- /dev/null
+++ b/Help/command/FIND_XXX.txt
@@ -0,0 +1,101 @@
+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.
+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
+added to the search.
+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
+
+.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
+ <prefix>/|XXX_SUBDIR| for each <prefix> in 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.
+
+ * |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.
+ 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.
+ 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.
+
+4. Search the standard system environment variables.
+ 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
+ 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
+
+.. include:: FIND_XXX_MAC.txt
+.. include:: FIND_XXX_ROOT.txt
+.. include:: FIND_XXX_ORDER.txt
diff --git a/Help/command/FIND_XXX_MAC.txt b/Help/command/FIND_XXX_MAC.txt
new file mode 100644
index 0000000..eb3900c
--- /dev/null
+++ b/Help/command/FIND_XXX_MAC.txt
@@ -0,0 +1,24 @@
+On Darwin or systems supporting OS X Frameworks, the cmake variable
+CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
+
+* FIRST: Try to find frameworks before standard libraries or headers.
+ This is the default on Darwin.
+
+* LAST: Try to find frameworks after standard libraries or headers.
+
+* ONLY: Only try to find frameworks.
+
+* NEVER: Never try to find frameworks.
+
+On Darwin or systems supporting OS X Application Bundles, the cmake
+variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
+following:
+
+* FIRST: Try to find application bundles before standard programs.
+ This is the default on Darwin.
+
+* LAST: Try to find application bundles after standard programs.
+
+* ONLY: Only try to find application bundles.
+
+* NEVER: Never try to find application bundles.
diff --git a/Help/command/FIND_XXX_ORDER.txt b/Help/command/FIND_XXX_ORDER.txt
new file mode 100644
index 0000000..bac2419
--- /dev/null
+++ b/Help/command/FIND_XXX_ORDER.txt
@@ -0,0 +1,12 @@
+The default search order is designed to be most-specific to
+least-specific for common use cases.
+Projects may override the order by simply calling the command
+multiple times and using the ``NO_*`` options:
+
+.. parsed-literal::
+
+ |FIND_XXX| (|FIND_ARGS_XXX| PATHS paths... NO_DEFAULT_PATH)
+ |FIND_XXX| (|FIND_ARGS_XXX|)
+
+Once one of the calls succeeds the result variable will be set
+and stored in the cache so that no call will search again.
diff --git a/Help/command/FIND_XXX_ROOT.txt b/Help/command/FIND_XXX_ROOT.txt
new file mode 100644
index 0000000..407375a
--- /dev/null
+++ b/Help/command/FIND_XXX_ROOT.txt
@@ -0,0 +1,14 @@
+The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
+directories to be prepended to all other search directories. This
+effectively "re-roots" the entire search under given locations. By
+default it is empty. It is especially useful when cross-compiling to
+point to the root directory of the target environment and CMake will
+search there too. By default at first the directories listed in
+CMAKE_FIND_ROOT_PATH 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 CMAKE_FIND_ROOT_PATH will not be
+used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
+directories will be searched.
diff --git a/Help/command/find_file.rst b/Help/command/find_file.rst
index c5956f8..549b317 100644
--- a/Help/command/find_file.rst
+++ b/Help/command/find_file.rst
@@ -1,154 +1,27 @@
find_file
---------
-Find the full path to a file.
-
-::
-
- find_file(<VAR> name1 [path1 path2 ...])
-
-This is the short-hand signature for the command that is sufficient in
-many cases. It is the same as find_file(<VAR> name1 [PATHS path1
-path2 ...])
-
-::
-
- find_file(
- <VAR>
- name | NAMES name1 [name2 ...]
- [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 full path to named file. A cache entry
-named by <VAR> is created to store the result of this command. If the
-full path to a file 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_file is invoked with the
-same variable. The name of the full path to a file 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 added to
-the search. If NO_DEFAULT_PATH is not specified, the search process
-is as follows:
-
-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.
-
-::
+.. |FIND_XXX| replace:: 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
+.. |CMAKE_PREFIX_PATH_XXX| replace::
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
- CMAKE_INCLUDE_PATH
- CMAKE_FRAMEWORK_PATH
-
-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.
-
-::
-
- <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
- CMAKE_INCLUDE_PATH
- CMAKE_FRAMEWORK_PATH
-
-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.
+ |CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
+.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
-4. Search the standard system environment variables. This can be
-skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
-
-::
-
- PATH
- INCLUDE
-
-5. Search cmake variables defined in the Platform files for the
-current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
-passed.
-
-::
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE
+.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
- CMAKE_SYSTEM_INCLUDE_PATH
- CMAKE_SYSTEM_FRAMEWORK_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.
-
-On Darwin or systems supporting OS X Frameworks, the cmake variable
-CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
-
-::
-
- "FIRST" - Try to find frameworks before standard
- libraries or headers. This is the default on Darwin.
- "LAST" - Try to find frameworks after standard
- libraries or headers.
- "ONLY" - Only try to find frameworks.
- "NEVER" - Never try to find frameworks.
-
-On Darwin or systems supporting OS X Application Bundles, the cmake
-variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
-following:
-
-::
-
- "FIRST" - Try to find application bundles before standard
- programs. This is the default on Darwin.
- "LAST" - Try to find application bundles after standard
- programs.
- "ONLY" - Only try to find application bundles.
- "NEVER" - Never try to find application bundles.
-
-The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
-directories to be prepended to all other search directories. This
-effectively "re-roots" the entire search under given locations. By
-default it is empty. It is especially useful when cross-compiling to
-point to the root directory of the target environment and CMake will
-search there too. By default at first the directories listed in
-CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
-searched. The default behavior can be adjusted by setting
-CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. 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 CMAKE_FIND_ROOT_PATH will not be
-used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
-directories will be searched.
-
-The default search order is designed to be most-specific to
-least-specific for common use cases. Projects may override the order
-by simply calling the command multiple times and using the NO_*
-options:
-
-::
+ |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
- find_file(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
- find_file(<VAR> NAMES name)
+.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
+ CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
-Once one of the calls succeeds the result variable will be set and
-stored in the cache so that no call will search again.
+.. include:: FIND_XXX.txt
diff --git a/Help/command/find_library.rst b/Help/command/find_library.rst
index 39ec4af..8598be7 100644
--- a/Help/command/find_library.rst
+++ b/Help/command/find_library.rst
@@ -1,157 +1,30 @@
find_library
------------
-Find a library.
-
-::
-
- find_library(<VAR> name1 [path1 path2 ...])
-
-This is the short-hand signature for the command that is sufficient in
-many cases. It is the same as find_library(<VAR> name1 [PATHS path1
-path2 ...])
-
-::
-
- find_library(
- <VAR>
- name | NAMES name1 [name2 ...] [NAMES_PER_DIR]
- [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 library. A cache entry named by <VAR>
-is created to store the result of this command. If the library 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_library is invoked with the same variable. The
-name of the library 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 added to
-the search. If NO_DEFAULT_PATH is not specified, the search process
-is as follows:
-
-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.
-
-::
+.. |FIND_XXX| replace:: find_library
+.. |NAMES| replace:: NAMES name1 [name2 ...] [NAMES_PER_DIR]
+.. |SEARCH_XXX| replace:: library
+.. |SEARCH_XXX_DESC| replace:: library
+.. |XXX_SUBDIR| replace:: lib
+.. |CMAKE_PREFIX_PATH_XXX| replace::
<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
- CMAKE_LIBRARY_PATH
- CMAKE_FRAMEWORK_PATH
-
-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.
-
-::
-
- <prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/lib for each <prefix> in CMAKE_PREFIX_PATH
- CMAKE_LIBRARY_PATH
- CMAKE_FRAMEWORK_PATH
-
-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.
+ |CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_XXX_PATH| replace:: CMAKE_LIBRARY_PATH
+.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
-4. Search the standard system environment variables. This can be
-skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
-
-::
-
- PATH
- LIB
-
-5. Search cmake variables defined in the Platform files for the
-current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
-passed.
-
-::
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and LIB
+.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
<prefix>/lib/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/lib for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
- CMAKE_SYSTEM_LIBRARY_PATH
- CMAKE_SYSTEM_FRAMEWORK_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.
-
-On Darwin or systems supporting OS X Frameworks, the cmake variable
-CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
-
-::
-
- "FIRST" - Try to find frameworks before standard
- libraries or headers. This is the default on Darwin.
- "LAST" - Try to find frameworks after standard
- libraries or headers.
- "ONLY" - Only try to find frameworks.
- "NEVER" - Never try to find frameworks.
-
-On Darwin or systems supporting OS X Application Bundles, the cmake
-variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
-following:
-
-::
-
- "FIRST" - Try to find application bundles before standard
- programs. This is the default on Darwin.
- "LAST" - Try to find application bundles after standard
- programs.
- "ONLY" - Only try to find application bundles.
- "NEVER" - Never try to find application bundles.
-
-The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
-directories to be prepended to all other search directories. This
-effectively "re-roots" the entire search under given locations. By
-default it is empty. It is especially useful when cross-compiling to
-point to the root directory of the target environment and CMake will
-search there too. By default at first the directories listed in
-CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
-searched. The default behavior can be adjusted by setting
-CMAKE_FIND_ROOT_PATH_MODE_LIBRARY. 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 CMAKE_FIND_ROOT_PATH will not be
-used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
-directories will be searched.
-
-The default search order is designed to be most-specific to
-least-specific for common use cases. Projects may override the order
-by simply calling the command multiple times and using the NO_*
-options:
-
-::
+ |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
- find_library(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
- find_library(<VAR> NAMES name)
+.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
+ CMAKE_FIND_ROOT_PATH_MODE_LIBRARY
-Once one of the calls succeeds the result variable will be set and
-stored in the cache so that no call will search again.
+.. include:: FIND_XXX.txt
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
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst
index 27d0ac7..c394a08 100644
--- a/Help/command/find_package.rst
+++ b/Help/command/find_package.rst
@@ -317,58 +317,14 @@ registry on non-Windows platforms.
9. Search paths specified by the PATHS option. These are typically
hard-coded guesses.
-On Darwin or systems supporting OS X Frameworks, the cmake variable
-CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
-
-::
-
- "FIRST" - Try to find frameworks before standard
- libraries or headers. This is the default on Darwin.
- "LAST" - Try to find frameworks after standard
- libraries or headers.
- "ONLY" - Only try to find frameworks.
- "NEVER" - Never try to find frameworks.
-
-On Darwin or systems supporting OS X Application Bundles, the cmake
-variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
-following:
-
-::
-
- "FIRST" - Try to find application bundles before standard
- programs. This is the default on Darwin.
- "LAST" - Try to find application bundles after standard
- programs.
- "ONLY" - Only try to find application bundles.
- "NEVER" - Never try to find application bundles.
-
-The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
-directories to be prepended to all other search directories. This
-effectively "re-roots" the entire search under given locations. By
-default it is empty. It is especially useful when cross-compiling to
-point to the root directory of the target environment and CMake will
-search there too. By default at first the directories listed in
-CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
-searched. The default behavior can be adjusted by setting
-CMAKE_FIND_ROOT_PATH_MODE_PACKAGE. 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 CMAKE_FIND_ROOT_PATH will not be
-used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
-directories will be searched.
-
-The default search order is designed to be most-specific to
-least-specific for common use cases. Projects may override the order
-by simply calling the command multiple times and using the NO_*
-options:
-
-::
-
- find_package(<package> PATHS paths... NO_DEFAULT_PATH)
- find_package(<package>)
-
-Once one of the calls succeeds the result variable will be set and
-stored in the cache so that no call will search again.
+.. |FIND_XXX| replace:: find_package
+.. |FIND_ARGS_XXX| replace:: <package>
+.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
+ CMAKE_FIND_ROOT_PATH_MODE_PACKAGE
+
+.. include:: FIND_XXX_MAC.txt
+.. include:: FIND_XXX_ROOT.txt
+.. include:: FIND_XXX_ORDER.txt
Every non-REQUIRED find_package() call can be disabled by setting the
variable CMAKE_DISABLE_FIND_PACKAGE_<package> to TRUE. See the
diff --git a/Help/command/find_path.rst b/Help/command/find_path.rst
index 2ffe6aa..c85011a 100644
--- a/Help/command/find_path.rst
+++ b/Help/command/find_path.rst
@@ -1,158 +1,30 @@
find_path
---------
-Find the directory containing a file.
-
-::
-
- find_path(<VAR> name1 [path1 path2 ...])
-
-This is the short-hand signature for the command that is sufficient in
-many cases. It is the same as find_path(<VAR> name1 [PATHS path1
-path2 ...])
-
-::
-
- find_path(
- <VAR>
- name | NAMES name1 [name2 ...]
- [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 directory containing the named file. A
-cache entry named by <VAR> is created to store the result of this
-command. If the file in a directory 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_path is
-invoked with the same variable. The name of the file in a directory
-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 added to
-the search. If NO_DEFAULT_PATH is not specified, the search process
-is as follows:
-
-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.
-
-::
+.. |FIND_XXX| replace:: 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
+.. |CMAKE_PREFIX_PATH_XXX| replace::
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
- CMAKE_INCLUDE_PATH
- CMAKE_FRAMEWORK_PATH
-
-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.
-
-::
-
- <prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/include for each <prefix> in CMAKE_PREFIX_PATH
- CMAKE_INCLUDE_PATH
- CMAKE_FRAMEWORK_PATH
-
-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.
+ |CMAKE_PREFIX_PATH_XXX_SUBDIR|
+.. |CMAKE_XXX_PATH| replace:: CMAKE_INCLUDE_PATH
+.. |CMAKE_XXX_MAC_PATH| replace:: CMAKE_FRAMEWORK_PATH
-4. Search the standard system environment variables. This can be
-skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
-
-::
-
- PATH
- INCLUDE
-
-5. Search cmake variables defined in the Platform files for the
-current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
-passed.
-
-::
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH and INCLUDE
+.. |CMAKE_SYSTEM_PREFIX_PATH_XXX| replace::
<prefix>/include/<arch> if CMAKE_LIBRARY_ARCHITECTURE is set, and
- <prefix>/include for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
- CMAKE_SYSTEM_INCLUDE_PATH
- CMAKE_SYSTEM_FRAMEWORK_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.
-
-On Darwin or systems supporting OS X Frameworks, the cmake variable
-CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
-
-::
-
- "FIRST" - Try to find frameworks before standard
- libraries or headers. This is the default on Darwin.
- "LAST" - Try to find frameworks after standard
- libraries or headers.
- "ONLY" - Only try to find frameworks.
- "NEVER" - Never try to find frameworks.
-
-On Darwin or systems supporting OS X Application Bundles, the cmake
-variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
-following:
-
-::
-
- "FIRST" - Try to find application bundles before standard
- programs. This is the default on Darwin.
- "LAST" - Try to find application bundles after standard
- programs.
- "ONLY" - Only try to find application bundles.
- "NEVER" - Never try to find application bundles.
-
-The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
-directories to be prepended to all other search directories. This
-effectively "re-roots" the entire search under given locations. By
-default it is empty. It is especially useful when cross-compiling to
-point to the root directory of the target environment and CMake will
-search there too. By default at first the directories listed in
-CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
-searched. The default behavior can be adjusted by setting
-CMAKE_FIND_ROOT_PATH_MODE_INCLUDE. 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 CMAKE_FIND_ROOT_PATH will not be
-used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
-directories will be searched.
-
-The default search order is designed to be most-specific to
-least-specific for common use cases. Projects may override the order
-by simply calling the command multiple times and using the NO_*
-options:
-
-::
+ |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
- find_path(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
- find_path(<VAR> NAMES name)
+.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
+ CMAKE_FIND_ROOT_PATH_MODE_INCLUDE
-Once one of the calls succeeds the result variable will be set and
-stored in the cache so that no call will search again.
+.. 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
diff --git a/Help/command/find_program.rst b/Help/command/find_program.rst
index 656fbe5..da5a41d 100644
--- a/Help/command/find_program.rst
+++ b/Help/command/find_program.rst
@@ -1,151 +1,25 @@
find_program
------------
-Find an executable program.
+.. |FIND_XXX| replace:: find_program
+.. |NAMES| replace:: NAMES name1 [name2 ...]
+.. |SEARCH_XXX| replace:: program
+.. |SEARCH_XXX_DESC| replace:: program
+.. |XXX_SUBDIR| replace:: [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
- find_program(<VAR> name1 [path1 path2 ...])
+.. |SYSTEM_ENVIRONMENT_PATH_XXX| replace:: PATH
-This is the short-hand signature for the command that is sufficient in
-many cases. It is the same as find_program(<VAR> name1 [PATHS path1
-path2 ...])
+.. |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_FIND_ROOT_PATH_MODE_XXX| replace::
+ CMAKE_FIND_ROOT_PATH_MODE_PROGRAM
- find_program(
- <VAR>
- name | NAMES name1 [name2 ...]
- [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 program. A cache entry named by <VAR>
-is created to store the result of this command. If the program 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_program is invoked with the same variable. The
-name of the program 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 added to
-the search. If NO_DEFAULT_PATH is not specified, the search process
-is as follows:
-
-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.
-
-::
-
- <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
- CMAKE_PROGRAM_PATH
- CMAKE_APPBUNDLE_PATH
-
-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.
-
-::
-
- <prefix>/[s]bin for each <prefix> in CMAKE_PREFIX_PATH
- CMAKE_PROGRAM_PATH
- CMAKE_APPBUNDLE_PATH
-
-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.
-
-4. Search the standard system environment variables. This can be
-skipped if NO_SYSTEM_ENVIRONMENT_PATH is an argument.
-
-::
-
- PATH
-
-
-5. Search cmake variables defined in the Platform files for the
-current system. This can be skipped if NO_CMAKE_SYSTEM_PATH is
-passed.
-
-::
-
- <prefix>/[s]bin for each <prefix> in CMAKE_SYSTEM_PREFIX_PATH
- CMAKE_SYSTEM_PROGRAM_PATH
- CMAKE_SYSTEM_APPBUNDLE_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.
-
-On Darwin or systems supporting OS X Frameworks, the cmake variable
-CMAKE_FIND_FRAMEWORK can be set to empty or one of the following:
-
-::
-
- "FIRST" - Try to find frameworks before standard
- libraries or headers. This is the default on Darwin.
- "LAST" - Try to find frameworks after standard
- libraries or headers.
- "ONLY" - Only try to find frameworks.
- "NEVER" - Never try to find frameworks.
-
-On Darwin or systems supporting OS X Application Bundles, the cmake
-variable CMAKE_FIND_APPBUNDLE can be set to empty or one of the
-following:
-
-::
-
- "FIRST" - Try to find application bundles before standard
- programs. This is the default on Darwin.
- "LAST" - Try to find application bundles after standard
- programs.
- "ONLY" - Only try to find application bundles.
- "NEVER" - Never try to find application bundles.
-
-The CMake variable CMAKE_FIND_ROOT_PATH specifies one or more
-directories to be prepended to all other search directories. This
-effectively "re-roots" the entire search under given locations. By
-default it is empty. It is especially useful when cross-compiling to
-point to the root directory of the target environment and CMake will
-search there too. By default at first the directories listed in
-CMAKE_FIND_ROOT_PATH and then the non-rooted directories will be
-searched. The default behavior can be adjusted by setting
-CMAKE_FIND_ROOT_PATH_MODE_PROGRAM. 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 CMAKE_FIND_ROOT_PATH will not be
-used. If ONLY_CMAKE_FIND_ROOT_PATH is used then only the re-rooted
-directories will be searched.
-
-The default search order is designed to be most-specific to
-least-specific for common use cases. Projects may override the order
-by simply calling the command multiple times and using the NO_*
-options:
-
-::
-
- find_program(<VAR> NAMES name PATHS paths... NO_DEFAULT_PATH)
- find_program(<VAR> NAMES name)
-
-Once one of the calls succeeds the result variable will be set and
-stored in the cache so that no call will search again.
+.. include:: FIND_XXX.txt