CMake/Help/command/FIND_XXX.txt

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

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