summaryrefslogtreecommitdiff
path: root/Help/command/FIND_XXX.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Help/command/FIND_XXX.txt')
-rw-r--r--Help/command/FIND_XXX.txt122
1 files changed, 122 insertions, 0 deletions
diff --git a/Help/command/FIND_XXX.txt b/Help/command/FIND_XXX.txt
new file mode 100644
index 000000000..7db221cb8
--- /dev/null
+++ b/Help/command/FIND_XXX.txt
@@ -0,0 +1,122 @@
+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_PATH]
+ [NO_CMAKE_ENVIRONMENT_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.
+
+Options include:
+
+``NAMES``
+ Specify one or more possible names for the |SEARCH_XXX|.
+
+ When using this to specify names with and without a version
+ suffix, we recommend specifying the unversioned name first
+ so that locally-built packages can be found before those
+ provided by distributions.
+
+``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:
+
+.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
+ |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``
+
+.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
+ |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``.
+ The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
+ 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,
+ and therefore use the host's native path separator
+ (``;`` on Windows and ``:`` on UNIX).
+ 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
+
+On OS X the :variable:`CMAKE_FIND_FRAMEWORK` and
+:variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
+preference between Apple-style and unix-style package components.
+
+.. include:: FIND_XXX_ROOT.txt
+.. include:: FIND_XXX_ORDER.txt