FIND_XXX.txt 5.77 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
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]
19
             [NO_PACKAGE_ROOT_PATH]
20
             [NO_CMAKE_PATH]
21
             [NO_CMAKE_ENVIRONMENT_PATH]
22 23 24 25 26 27 28 29 30 31 32 33 34 35 36
             [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.
37 38 39 40 41 42

Options include:

``NAMES``
  Specify one or more possible names for the |SEARCH_XXX|.

43 44 45 46 47
  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.

48 49 50 51 52 53 54 55 56 57 58 59 60
``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
61
added to the search.
62
If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
63

64
.. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
65 66 67 68 69
   |prefix_XXX_SUBDIR| for each ``<prefix>`` in the
   :variable:`<PackageName>_ROOT` CMake variable and the
   :envvar:`<PackageName>_ROOT` environment variable if
   called from within a find module loaded by
   :command:`find_package(<PackageName>)`
70

71
.. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
72
   |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
73

74
.. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
75 76
   |prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
   |entry_XXX_SUBDIR| for other entries in ``PATH``
77

78
.. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
79 80
   |prefix_XXX_SUBDIR| for each ``<prefix>`` in
   :variable:`CMAKE_SYSTEM_PREFIX_PATH`
81

82
1. If called from within a find module or any other script loaded by a call to
83
   :command:`find_package(<PackageName>)`, search prefixes unique to the
84
   current package being found.  Specifically, look in the
85 86
   :variable:`<PackageName>_ROOT` CMake variable and the
   :envvar:`<PackageName>_ROOT` environment variable.
87 88 89 90 91
   The package root variables are maintained as a stack, so if called from
   nested find modules or config packages, root paths from the parent's find
   module or config package will be searched after paths from the current
   module or package.  In other words, the search order would be
   ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
92
   ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
93
   This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
94
   the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
95 96 97 98 99
   See policy :policy:`CMP0074`.

   * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|

2. Search paths specified in cmake-specific cache variables.
100
   These are intended to be used on the command line with a ``-DVAR=value``.
101
   The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
102 103
   This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
   :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``.
104 105 106 107 108

   * |CMAKE_PREFIX_PATH_XXX|
   * |CMAKE_XXX_PATH|
   * |CMAKE_XXX_MAC_PATH|

109
3. Search paths specified in cmake-specific environment variables.
110 111 112
   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).
113 114
   This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or
   by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``.
115 116 117 118 119

   * |CMAKE_PREFIX_PATH_XXX|
   * |CMAKE_XXX_PATH|
   * |CMAKE_XXX_MAC_PATH|

120
4. Search the paths specified by the ``HINTS`` option.
121 122
   These should be paths computed by system introspection, such as a
   hint provided by the location of another item already found.
123
   Hard-coded guesses should be specified with the ``PATHS`` option.
124

125
5. Search the standard system environment variables.
126 127
   This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by
   setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.
128 129

   * |SYSTEM_ENVIRONMENT_PATH_XXX|
130
   * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
131

132
6. Search cmake variables defined in the Platform files
133
   for the current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
134 135
   is passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH`
   to ``FALSE``.
136 137 138 139 140

   * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
   * |CMAKE_SYSTEM_XXX_PATH|
   * |CMAKE_SYSTEM_XXX_MAC_PATH|

141
7. Search the paths specified by the PATHS option
142 143 144 145 146
   or in the short-hand version of the command.
   These are typically hard-coded guesses.

.. |FIND_ARGS_XXX| replace:: <VAR> NAMES name

147
On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and
148 149 150
:variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
preference between Apple-style and unix-style package components.

151 152
.. include:: FIND_XXX_ROOT.txt
.. include:: FIND_XXX_ORDER.txt