Help/command/FIND_XXX.txt

   1 A short-hand signature is:
   2
   3 .. parsed-literal::
   4
   5    |FIND_XXX| (<VAR> name1 [path1 path2 ...])
   6
   7 The general signature is:
   8
   9 .. parsed-literal::
  10
  11    |FIND_XXX| (
  12              <VAR>
  13              name | |NAMES|
  14              [HINTS [path | ENV var]... ]
  15              [PATHS [path | ENV var]... ]
  16              [REGISTRY_VIEW (64|32|64_32|32_64|HOST|TARGET|BOTH)]
  17              [PATH_SUFFIXES suffix1 [suffix2 ...]]
  18              [VALIDATOR function]
  19              [DOC "cache documentation string"]
  20              [NO_CACHE]
  21              [REQUIRED]
  22              [NO_DEFAULT_PATH]
  23              [NO_PACKAGE_ROOT_PATH]
  24              [NO_CMAKE_PATH]
  25              [NO_CMAKE_ENVIRONMENT_PATH]
  26              [NO_SYSTEM_ENVIRONMENT_PATH]
  27              [NO_CMAKE_SYSTEM_PATH]
  28              [NO_CMAKE_INSTALL_PREFIX]
  29              [CMAKE_FIND_ROOT_PATH_BOTH |
  30               ONLY_CMAKE_FIND_ROOT_PATH |
  31               NO_CMAKE_FIND_ROOT_PATH]
  32             )
  33
  34 This command is used to find a |SEARCH_XXX_DESC|.
  35 A cache entry, or a normal variable if ``NO_CACHE`` is specified,
  36 named by ``<VAR>`` is created to store the result of this command.
  37 If the |SEARCH_XXX| is found the result is stored in the variable
  38 and the search will not be repeated unless the variable is cleared.
  39 If nothing is found, the result will be ``<VAR>-NOTFOUND``.
  40
  41 Options include:
  42
  43 ``NAMES``
  44   Specify one or more possible names for the |SEARCH_XXX|.
  45
  46   When using this to specify names with and without a version
  47   suffix, we recommend specifying the unversioned name first
  48   so that locally-built packages can be found before those
  49   provided by distributions.
  50
  51 ``HINTS``, ``PATHS``
  52   Specify directories to search in addition to the default locations.
  53   The ``ENV var`` sub-option reads paths from a system environment
  54   variable.
  55
  56   .. versionchanged:: 3.24
  57     On ``Windows`` platform, it is possible to include registry queries as part
  58     of the directories, using a :ref:`dedicated syntax <Find Using Windows Registry>`.
  59     Such specifications will be ignored on all other platforms.
  60
  61 ``REGISTRY_VIEW``
  62   .. versionadded:: 3.24
  63
  64   .. include:: FIND_XXX_REGISTRY_VIEW.txt
  65
  66 ``PATH_SUFFIXES``
  67   Specify additional subdirectories to check below each directory
  68   location otherwise considered.
  69
  70 ``VALIDATOR``
  71   .. versionadded:: 3.25
  72
  73   Specify a :command:`function` to be called for each candidate item found
  74   (a :command:`macro` cannot be provided, that will result in an error).
  75   Two arguments will be passed to the validator function: the name of a
  76   result variable, and the absolute path to the candidate item.  The item
  77   will be accepted and the search will end unless the function sets the
  78   value in the result variable to false in the calling scope.  The result
  79   variable will hold a true value when the validator function is entered.
  80
  81   .. parsed-literal::
  82
  83      function(my_check validator_result_var item)
  84        if(NOT item MATCHES ...)
  85          set(${validator_result_var} FALSE PARENT_SCOPE)
  86        endif()
  87      endfunction()
  88
  89      |FIND_XXX| (result NAMES ... VALIDATOR my_check)
  90
  91   Note that if a cached result is used, the search is skipped and any
  92   ``VALIDATOR`` is ignored.  The cached result is not required to pass the
  93   validation function.
  94
  95 ``DOC``
  96   Specify the documentation string for the ``<VAR>`` cache entry.
  97
  98 ``NO_CACHE``
  99   .. versionadded:: 3.21
 100
 101   The result of the search will be stored in a normal variable rather than
 102   a cache entry.
 103
 104   .. note::
 105
 106     If the variable is already set before the call (as a normal or cache
 107     variable) then the search will not occur.
 108
 109   .. warning::
 110
 111     This option should be used with caution because it can greatly increase
 112     the cost of repeated configure steps.
 113
 114 ``REQUIRED``
 115   .. versionadded:: 3.18
 116
 117   Stop processing with an error message if nothing is found, otherwise
 118   the search will be attempted again the next time |FIND_XXX| is invoked
 119   with the same variable.
 120
 121 If ``NO_DEFAULT_PATH`` is specified, then no additional paths are
 122 added to the search.
 123 If ``NO_DEFAULT_PATH`` is not specified, the search process is as follows:
 124
 125 .. |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX_SUBDIR| replace::
 126    |prefix_XXX_SUBDIR| for each ``<prefix>`` in the
 127    :variable:`<PackageName>_ROOT` CMake variable and the
 128    :envvar:`<PackageName>_ROOT` environment variable if
 129    called from within a find module loaded by
 130    :command:`find_package(<PackageName>)`
 131
 132 .. |CMAKE_PREFIX_PATH_XXX_SUBDIR| replace::
 133    |prefix_XXX_SUBDIR| for each ``<prefix>`` in :variable:`CMAKE_PREFIX_PATH`
 134
 135 .. |SYSTEM_ENVIRONMENT_PREFIX_PATH_XXX_SUBDIR| replace::
 136    |prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
 137    |entry_XXX_SUBDIR| for other entries in ``PATH``
 138
 139 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
 140    |prefix_XXX_SUBDIR| for each ``<prefix>`` in
 141    :variable:`CMAKE_SYSTEM_PREFIX_PATH`
 142
 143 1. .. versionadded:: 3.12
 144     If called from within a find module or any other script loaded by a call to
 145     :command:`find_package(<PackageName>)`, search prefixes unique to the
 146     current package being found.  Specifically, look in the
 147     :variable:`<PackageName>_ROOT` CMake variable and the
 148     :envvar:`<PackageName>_ROOT` environment variable.
 149     The package root variables are maintained as a stack, so if called from
 150     nested find modules or config packages, root paths from the parent's find
 151     module or config package will be searched after paths from the current
 152     module or package.  In other words, the search order would be
 153     ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
 154     ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
 155     This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting
 156     the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``.
 157     See policy :policy:`CMP0074`.
 158
 159    * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
 160
 161 2. Search paths specified in cmake-specific cache variables.
 162    These are intended to be used on the command line with a ``-DVAR=value``.
 163    The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`.
 164    This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the
 165    :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``.
 166
 167    * |CMAKE_PREFIX_PATH_XXX|
 168    * |CMAKE_XXX_PATH|
 169    * |CMAKE_XXX_MAC_PATH|
 170
 171 3. Search paths specified in cmake-specific environment variables.
 172    These are intended to be set in the user's shell configuration,
 173    and therefore use the host's native path separator
 174    (``;`` on Windows and ``:`` on UNIX).
 175    This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or
 176    by setting the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``.
 177
 178    * |CMAKE_PREFIX_PATH_XXX|
 179    * |CMAKE_XXX_PATH|
 180    * |CMAKE_XXX_MAC_PATH|
 181
 182 4. Search the paths specified by the ``HINTS`` option.
 183    These should be paths computed by system introspection, such as a
 184    hint provided by the location of another item already found.
 185    Hard-coded guesses should be specified with the ``PATHS`` option.
 186
 187 5. Search the standard system environment variables.
 188    This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by
 189    setting the :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``.
 190
 191    * |SYSTEM_ENVIRONMENT_PATH_XXX|
 192    * |SYSTEM_ENVIRONMENT_PATH_WINDOWS_XXX|
 193
 194 6. Search cmake variables defined in the Platform files
 195    for the current system.  The searching of ``CMAKE_INSTALL_PREFIX`` and
 196    ``CMAKE_STAGING_PREFIX`` can be
 197    skipped if ``NO_CMAKE_INSTALL_PREFIX`` is passed or by setting the
 198    :variable:`CMAKE_FIND_USE_INSTALL_PREFIX` to ``FALSE``. All these locations
 199    can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is passed or by setting the
 200    :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` to ``FALSE``.
 201
 202    * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
 203    * |CMAKE_SYSTEM_XXX_PATH|
 204    * |CMAKE_SYSTEM_XXX_MAC_PATH|
 205
 206    The platform paths that these variables contain are locations that
 207    typically include installed software. An example being ``/usr/local`` for
 208    UNIX based platforms.
 209
 210 7. Search the paths specified by the PATHS option
 211    or in the short-hand version of the command.
 212    These are typically hard-coded guesses.
 213
 214 The :variable:`CMAKE_IGNORE_PATH`, :variable:`CMAKE_IGNORE_PREFIX_PATH`,
 215 :variable:`CMAKE_SYSTEM_IGNORE_PATH` and
 216 :variable:`CMAKE_SYSTEM_IGNORE_PREFIX_PATH` variables can also cause some
 217 of the above locations to be ignored.
 218
 219 .. versionadded:: 3.16
 220   Added ``CMAKE_FIND_USE_<CATEGORY>_PATH`` variables to globally disable
 221   various search locations.
 222
 223 .. |FIND_ARGS_XXX| replace:: <VAR> NAMES name
 224
 225 On macOS the :variable:`CMAKE_FIND_FRAMEWORK` and
 226 :variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
 227 preference between Apple-style and unix-style package components.
 228
 229 .. include:: FIND_XXX_ROOT.txt
 230 .. include:: FIND_XXX_ORDER.txt