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 path1 [path2 ... ENV var]]
  15              [PATHS path1 [path2 ... ENV var]]
  16              [PATH_SUFFIXES suffix1 [suffix2 ...]]
  17              [DOC "cache documentation string"]
  18              [NO_DEFAULT_PATH]
  19              [NO_PACKAGE_ROOT_PATH]
  20              [NO_CMAKE_PATH]
  21              [NO_CMAKE_ENVIRONMENT_PATH]
  22              [NO_SYSTEM_ENVIRONMENT_PATH]
  23              [NO_CMAKE_SYSTEM_PATH]
  24              [CMAKE_FIND_ROOT_PATH_BOTH |
  25               ONLY_CMAKE_FIND_ROOT_PATH |
  26               NO_CMAKE_FIND_ROOT_PATH]
  27             )
  28
  29 This command is used to find a |SEARCH_XXX_DESC|.
  30 A cache entry named by ``<VAR>`` is created to store the result
  31 of this command.
  32 If the |SEARCH_XXX| is found the result is stored in the variable
  33 and the search will not be repeated unless the variable is cleared.
  34 If nothing is found, the result will be
  35 ``<VAR>-NOTFOUND``, and the search will be attempted again the
  36 next time |FIND_XXX| is invoked with the same variable.
  37
  38 Options include:
  39
  40 ``NAMES``
  41   Specify one or more possible names for the |SEARCH_XXX|.
  42
  43   When using this to specify names with and without a version
  44   suffix, we recommend specifying the unversioned name first
  45   so that locally-built packages can be found before those
  46   provided by distributions.
  47
  48 ``HINTS``, ``PATHS``
  49   Specify directories to search in addition to the default locations.
  50   The ``ENV var`` sub-option reads paths from a system environment
  51   variable.
  52
  53 ``PATH_SUFFIXES``
  54   Specify additional subdirectories to check below each directory
  55   location otherwise considered.
  56
  57 ``DOC``
  58   Specify the documentation string for the ``<VAR>`` cache entry.
  59
  60 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    |prefix_XXX_SUBDIR| for each ``<prefix>`` in the
  66    :variable:`<PackageName>_ROOT` CMake variable and the
  67    :envvar:`<PackageName>_ROOT` environment variable if
  68    called from within a find module loaded by
  69    :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    |prefix_XXX_SUBDIR| for each ``<prefix>/[s]bin`` in ``PATH``, and
  76    |entry_XXX_SUBDIR| for other entries in ``PATH``
  77
  78 .. |CMAKE_SYSTEM_PREFIX_PATH_XXX_SUBDIR| replace::
  79    |prefix_XXX_SUBDIR| for each ``<prefix>`` in
  80    :variable:`CMAKE_SYSTEM_PREFIX_PATH`
  81
  82 1. If called from within a find module loaded by
  83    :command:`find_package(<PackageName>)`, search prefixes unique to the
  84    current package being found.  Specifically look in the
  85    :variable:`<PackageName>_ROOT` CMake variable and the
  86    :envvar:`<PackageName>_ROOT` environment variable.
  87    The package root variables are maintained as a stack so if called from
  88    nested find modules, root paths from the parent's find module will be
  89    searched after paths from the current module,
  90    i.e. ``<CurrentPackage>_ROOT``, ``ENV{<CurrentPackage>_ROOT}``,
  91    ``<ParentPackage>_ROOT``, ``ENV{<ParentPackage>_ROOT}``, etc.
  92    This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
  93    See policy :policy:`CMP0074`.
  94
  95    * |FIND_PACKAGE_ROOT_PREFIX_PATH_XXX|
  96
  97 2. Search paths specified in cmake-specific cache variables.
  98    These are intended to be used on the command line with a ``-DVAR=value``.
  99    The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
 100    This can be skipped if ``NO_CMAKE_PATH`` is passed.
 101
 102    * |CMAKE_PREFIX_PATH_XXX|
 103    * |CMAKE_XXX_PATH|
 104    * |CMAKE_XXX_MAC_PATH|
 105
 106 3. Search paths specified in cmake-specific environment variables.
 107    These are intended to be set in the user's shell configuration,
 108    and therefore use the host's native path separator
 109    (``;`` on Windows and ``:`` on UNIX).
 110    This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed.
 111
 112    * |CMAKE_PREFIX_PATH_XXX|
 113    * |CMAKE_XXX_PATH|
 114    * |CMAKE_XXX_MAC_PATH|
 115
 116 4. Search the paths specified by the ``HINTS`` option.
 117    These should be paths computed by system introspection, such as a
 118    hint provided by the location of another item already found.
 119    Hard-coded guesses should be specified with the ``PATHS`` option.
 120
 121 5. Search the standard system environment variables.
 122    This can be skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is an argument.
 123
 124    * |SYSTEM_ENVIRONMENT_PATH_XXX|
 125
 126 6. Search cmake variables defined in the Platform files
 127    for the current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH``
 128    is passed.
 129
 130    * |CMAKE_SYSTEM_PREFIX_PATH_XXX|
 131    * |CMAKE_SYSTEM_XXX_PATH|
 132    * |CMAKE_SYSTEM_XXX_MAC_PATH|
 133
 134 7. Search the paths specified by the PATHS option
 135    or in the short-hand version of the command.
 136    These are typically hard-coded guesses.
 137
 138 .. |FIND_ARGS_XXX| replace:: <VAR> NAMES name
 139
 140 On OS X the :variable:`CMAKE_FIND_FRAMEWORK` and
 141 :variable:`CMAKE_FIND_APPBUNDLE` variables determine the order of
 142 preference between Apple-style and unix-style package components.
 143
 144 .. include:: FIND_XXX_ROOT.txt
 145 .. include:: FIND_XXX_ORDER.txt