Help/command/find_package.rst

   1 find_package
   2 ------------
   3
   4 Load settings for an external project.
   5
   6 ::
   7
   8   find_package(<package> [version] [EXACT] [QUIET] [MODULE]
   9                [REQUIRED] [[COMPONENTS] [components...]]
  10                [OPTIONAL_COMPONENTS components...]
  11                [NO_POLICY_SCOPE])
  12
  13 Finds and loads settings from an external project.  ``<package>_FOUND``
  14 will be set to indicate whether the package was found.  When the
  15 package is found package-specific information is provided through
  16 variables and :ref:`Imported Targets` documented by the package itself.  The
  17 ``QUIET`` option disables messages if the package cannot be found.  The
  18 ``MODULE`` option disables the second signature documented below.  The
  19 ``REQUIRED`` option stops processing with an error message if the package
  20 cannot be found.
  21
  22 A package-specific list of required components may be listed after the
  23 ``COMPONENTS`` option (or after the ``REQUIRED`` option if present).
  24 Additional optional components may be listed after
  25 ``OPTIONAL_COMPONENTS``.  Available components and their influence on
  26 whether a package is considered to be found are defined by the target
  27 package.
  28
  29 The ``[version]`` argument requests a version with which the package found
  30 should be compatible (format is ``major[.minor[.patch[.tweak]]]``).  The
  31 ``EXACT`` option requests that the version be matched exactly.  If no
  32 ``[version]`` and/or component list is given to a recursive invocation
  33 inside a find-module, the corresponding arguments are forwarded
  34 automatically from the outer call (including the ``EXACT`` flag for
  35 ``[version]``).  Version support is currently provided only on a
  36 package-by-package basis (details below).
  37
  38 User code should generally look for packages using the above simple
  39 signature.  The remainder of this command documentation specifies the
  40 full command signature and details of the search process.  Project
  41 maintainers wishing to provide a package to be found by this command
  42 are encouraged to read on.
  43
  44 The command has two modes by which it searches for packages: "Module"
  45 mode and "Config" mode.  Module mode is available when the command is
  46 invoked with the above reduced signature.  CMake searches for a file
  47 called ``Find<package>.cmake`` in the :variable:`CMAKE_MODULE_PATH`
  48 followed by the CMake installation.  If the file is found, it is read
  49 and processed by CMake.  It is responsible for finding the package,
  50 checking the version, and producing any needed messages.  Many
  51 find-modules provide limited or no support for versioning; check
  52 the module documentation.  If no module is found and the ``MODULE``
  53 option is not given the command proceeds to Config mode.
  54
  55 The complete Config mode command signature is::
  56
  57   find_package(<package> [version] [EXACT] [QUIET]
  58                [REQUIRED] [[COMPONENTS] [components...]]
  59                [CONFIG|NO_MODULE]
  60                [NO_POLICY_SCOPE]
  61                [NAMES name1 [name2 ...]]
  62                [CONFIGS config1 [config2 ...]]
  63                [HINTS path1 [path2 ... ]]
  64                [PATHS path1 [path2 ... ]]
  65                [PATH_SUFFIXES suffix1 [suffix2 ...]]
  66                [NO_DEFAULT_PATH]
  67                [NO_PACKAGE_ROOT_PATH]
  68                [NO_CMAKE_PATH]
  69                [NO_CMAKE_ENVIRONMENT_PATH]
  70                [NO_SYSTEM_ENVIRONMENT_PATH]
  71                [NO_CMAKE_PACKAGE_REGISTRY]
  72                [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing.
  73                [NO_CMAKE_SYSTEM_PATH]
  74                [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY]
  75                [CMAKE_FIND_ROOT_PATH_BOTH |
  76                 ONLY_CMAKE_FIND_ROOT_PATH |
  77                 NO_CMAKE_FIND_ROOT_PATH])
  78
  79 The ``CONFIG`` option may be used to skip Module mode explicitly and
  80 switch to Config mode.  It is synonymous to using ``NO_MODULE``.  Config
  81 mode is also implied by use of options not specified in the reduced
  82 signature.
  83
  84 Config mode attempts to locate a configuration file provided by the
  85 package to be found.  A cache entry called ``<package>_DIR`` is created to
  86 hold the directory containing the file.  By default the command
  87 searches for a package with the name ``<package>``.  If the ``NAMES`` option
  88 is given the names following it are used instead of ``<package>``.  The
  89 command searches for a file called ``<name>Config.cmake`` or
  90 ``<lower-case-name>-config.cmake`` for each name specified.  A
  91 replacement set of possible configuration file names may be given
  92 using the ``CONFIGS`` option.  The search procedure is specified below.
  93 Once found, the configuration file is read and processed by CMake.
  94 Since the file is provided by the package it already knows the
  95 location of package contents.  The full path to the configuration file
  96 is stored in the cmake variable ``<package>_CONFIG``.
  97
  98 All configuration files which have been considered by CMake while
  99 searching for an installation of the package with an appropriate
 100 version are stored in the cmake variable ``<package>_CONSIDERED_CONFIGS``,
 101 the associated versions in ``<package>_CONSIDERED_VERSIONS``.
 102
 103 If the package configuration file cannot be found CMake will generate
 104 an error describing the problem unless the ``QUIET`` argument is
 105 specified.  If ``REQUIRED`` is specified and the package is not found a
 106 fatal error is generated and the configure step stops executing.  If
 107 ``<package>_DIR`` has been set to a directory not containing a
 108 configuration file CMake will ignore it and search from scratch.
 109
 110 When the ``[version]`` argument is given Config mode will only find a
 111 version of the package that claims compatibility with the requested
 112 version (format is ``major[.minor[.patch[.tweak]]]``).  If the ``EXACT``
 113 option is given only a version of the package claiming an exact match
 114 of the requested version may be found.  CMake does not establish any
 115 convention for the meaning of version numbers.  Package version
 116 numbers are checked by "version" files provided by the packages
 117 themselves.  For a candidate package configuration file
 118 ``<config-file>.cmake`` the corresponding version file is located next
 119 to it and named either ``<config-file>-version.cmake`` or
 120 ``<config-file>Version.cmake``.  If no such version file is available
 121 then the configuration file is assumed to not be compatible with any
 122 requested version.  A basic version file containing generic version
 123 matching code can be created using the
 124 :module:`CMakePackageConfigHelpers` module.  When a version file
 125 is found it is loaded to check the requested version number.  The
 126 version file is loaded in a nested scope in which the following
 127 variables have been defined:
 128
 129 ``PACKAGE_FIND_NAME``
 130   the ``<package>`` name
 131 ``PACKAGE_FIND_VERSION``
 132   full requested version string
 133 ``PACKAGE_FIND_VERSION_MAJOR``
 134   major version if requested, else 0
 135 ``PACKAGE_FIND_VERSION_MINOR``
 136   minor version if requested, else 0
 137 ``PACKAGE_FIND_VERSION_PATCH``
 138   patch version if requested, else 0
 139 ``PACKAGE_FIND_VERSION_TWEAK``
 140   tweak version if requested, else 0
 141 ``PACKAGE_FIND_VERSION_COUNT``
 142   number of version components, 0 to 4
 143
 144 The version file checks whether it satisfies the requested version and
 145 sets these variables:
 146
 147 ``PACKAGE_VERSION``
 148   full provided version string
 149 ``PACKAGE_VERSION_EXACT``
 150   true if version is exact match
 151 ``PACKAGE_VERSION_COMPATIBLE``
 152   true if version is compatible
 153 ``PACKAGE_VERSION_UNSUITABLE``
 154   true if unsuitable as any version
 155
 156 These variables are checked by the ``find_package`` command to determine
 157 whether the configuration file provides an acceptable version.  They
 158 are not available after the find_package call returns.  If the version
 159 is acceptable the following variables are set:
 160
 161 ``<package>_VERSION``
 162   full provided version string
 163 ``<package>_VERSION_MAJOR``
 164   major version if provided, else 0
 165 ``<package>_VERSION_MINOR``
 166   minor version if provided, else 0
 167 ``<package>_VERSION_PATCH``
 168   patch version if provided, else 0
 169 ``<package>_VERSION_TWEAK``
 170   tweak version if provided, else 0
 171 ``<package>_VERSION_COUNT``
 172   number of version components, 0 to 4
 173
 174 and the corresponding package configuration file is loaded.
 175 When multiple package configuration files are available whose version files
 176 claim compatibility with the version requested it is unspecified which
 177 one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER`
 178 is set no attempt is made to choose a highest or closest version number.
 179
 180 To control the order in which ``find_package`` checks for compatibility use
 181 the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and
 182 :variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`.
 183 For instance in order to select the highest version one can set::
 184
 185   SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL)
 186   SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC)
 187
 188 before calling ``find_package``.
 189
 190 Config mode provides an elaborate interface and search procedure.
 191 Much of the interface is provided for completeness and for use
 192 internally by find-modules loaded by Module mode.  Most user code
 193 should simply call::
 194
 195   find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET])
 196
 197 in order to find a package.  Package maintainers providing CMake
 198 package configuration files are encouraged to name and install them
 199 such that the procedure outlined below will find them without
 200 requiring use of additional options.
 201
 202 CMake constructs a set of possible installation prefixes for the
 203 package.  Under each prefix several directories are searched for a
 204 configuration file.  The tables below show the directories searched.
 205 Each entry is meant for installation trees following Windows (W), UNIX
 206 (U), or Apple (A) conventions::
 207
 208   <prefix>/                                                       (W)
 209   <prefix>/(cmake|CMake)/                                         (W)
 210   <prefix>/<name>*/                                               (W)
 211   <prefix>/<name>*/(cmake|CMake)/                                 (W)
 212   <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/                 (U)
 213   <prefix>/(lib/<arch>|lib*|share)/<name>*/                       (U)
 214   <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/         (U)
 215   <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/         (W/U)
 216   <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/               (W/U)
 217   <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U)
 218
 219 On systems supporting OS X Frameworks and Application Bundles the
 220 following directories are searched for frameworks or bundles
 221 containing a configuration file::
 222
 223   <prefix>/<name>.framework/Resources/                    (A)
 224   <prefix>/<name>.framework/Resources/CMake/              (A)
 225   <prefix>/<name>.framework/Versions/*/Resources/         (A)
 226   <prefix>/<name>.framework/Versions/*/Resources/CMake/   (A)
 227   <prefix>/<name>.app/Contents/Resources/                 (A)
 228   <prefix>/<name>.app/Contents/Resources/CMake/           (A)
 229
 230 In all cases the ``<name>`` is treated as case-insensitive and corresponds
 231 to any of the names specified (``<package>`` or names given by ``NAMES``).
 232
 233 Paths with ``lib/<arch>`` are enabled if the
 234 :variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one
 235 or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in
 236 that order).
 237
 238 * Paths with ``lib64`` are searched on 64 bit platforms if the
 239   :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``.
 240 * Paths with ``lib32`` are searched on 32 bit platforms if the
 241   :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``.
 242 * Paths with ``libx32`` are searched on platforms using the x32 ABI
 243   if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``.
 244 * The ``lib`` path is always searched.
 245
 246 If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each
 247 (W) or (U) directory entry one-by-one.
 248
 249 This set of directories is intended to work in cooperation with
 250 projects that provide configuration files in their installation trees.
 251 Directories above marked with (W) are intended for installations on
 252 Windows where the prefix may point at the top of an application's
 253 installation directory.  Those marked with (U) are intended for
 254 installations on UNIX platforms where the prefix is shared by multiple
 255 packages.  This is merely a convention, so all (W) and (U) directories
 256 are still searched on all platforms.  Directories marked with (A) are
 257 intended for installations on Apple platforms.  The
 258 :variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE`
 259 variables determine the order of preference.
 260
 261 The set of installation prefixes is constructed using the following
 262 steps.  If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are
 263 enabled.
 264
 265 1. Search paths specified in the :variable:`<PackageName>_ROOT` CMake
 266    variable and the :envvar:`<PackageName>_ROOT` environment variable,
 267    where ``<PackageName>`` is the package to be found.
 268    The package root variables are maintained as a stack so if
 269    called from within a find module, root paths from the parent's find
 270    module will also be searched after paths for the current package.
 271    This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed.
 272    See policy :policy:`CMP0074`.
 273
 274 2. Search paths specified in cmake-specific cache variables.  These
 275    are intended to be used on the command line with a ``-DVAR=value``.
 276    The values are interpreted as :ref:`;-lists <CMake Language Lists>`.
 277    This can be skipped if ``NO_CMAKE_PATH`` is passed::
 278
 279      CMAKE_PREFIX_PATH
 280      CMAKE_FRAMEWORK_PATH
 281      CMAKE_APPBUNDLE_PATH
 282
 283 3. Search paths specified in cmake-specific environment variables.
 284    These are intended to be set in the user's shell configuration,
 285    and therefore use the host's native path separator
 286    (``;`` on Windows and ``:`` on UNIX).
 287    This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed::
 288
 289      <package>_DIR
 290      CMAKE_PREFIX_PATH
 291      CMAKE_FRAMEWORK_PATH
 292      CMAKE_APPBUNDLE_PATH
 293
 294 4. Search paths specified by the ``HINTS`` option.  These should be paths
 295    computed by system introspection, such as a hint provided by the
 296    location of another item already found.  Hard-coded guesses should
 297    be specified with the ``PATHS`` option.
 298
 299 5. Search the standard system environment variables.  This can be
 300    skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed.  Path entries
 301    ending in ``/bin`` or ``/sbin`` are automatically converted to their
 302    parent directories::
 303
 304      PATH
 305
 306 6. Search paths stored in the CMake :ref:`User Package Registry`.
 307    This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by
 308    setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY`
 309    to ``TRUE``.
 310    See the :manual:`cmake-packages(7)` manual for details on the user
 311    package registry.
 312
 313 7. Search cmake variables defined in the Platform files for the
 314    current system.  This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is
 315    passed::
 316
 317      CMAKE_SYSTEM_PREFIX_PATH
 318      CMAKE_SYSTEM_FRAMEWORK_PATH
 319      CMAKE_SYSTEM_APPBUNDLE_PATH
 320
 321 8. Search paths stored in the CMake :ref:`System Package Registry`.
 322    This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed
 323    or by setting the
 324    :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``.
 325    See the :manual:`cmake-packages(7)` manual for details on the system
 326    package registry.
 327
 328 9. Search paths specified by the ``PATHS`` option.  These are typically
 329    hard-coded guesses.
 330
 331 .. |FIND_XXX| replace:: find_package
 332 .. |FIND_ARGS_XXX| replace:: <package>
 333 .. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace::
 334    :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE`
 335
 336 .. include:: FIND_XXX_ROOT.txt
 337 .. include:: FIND_XXX_ORDER.txt
 338
 339 Every non-REQUIRED ``find_package`` call can be disabled by setting the
 340 :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``.
 341
 342 When loading a find module or package configuration file ``find_package``
 343 defines variables to provide information about the call arguments (and
 344 restores their original state before returning):
 345
 346 ``CMAKE_FIND_PACKAGE_NAME``
 347   the ``<package>`` name which is searched for
 348 ``<package>_FIND_REQUIRED``
 349   true if ``REQUIRED`` option was given
 350 ``<package>_FIND_QUIETLY``
 351   true if ``QUIET`` option was given
 352 ``<package>_FIND_VERSION``
 353   full requested version string
 354 ``<package>_FIND_VERSION_MAJOR``
 355   major version if requested, else 0
 356 ``<package>_FIND_VERSION_MINOR``
 357   minor version if requested, else 0
 358 ``<package>_FIND_VERSION_PATCH``
 359   patch version if requested, else 0
 360 ``<package>_FIND_VERSION_TWEAK``
 361   tweak version if requested, else 0
 362 ``<package>_FIND_VERSION_COUNT``
 363   number of version components, 0 to 4
 364 ``<package>_FIND_VERSION_EXACT``
 365   true if ``EXACT`` option was given
 366 ``<package>_FIND_COMPONENTS``
 367   list of requested components
 368 ``<package>_FIND_REQUIRED_<c>``
 369   true if component ``<c>`` is required,
 370   false if component ``<c>`` is optional
 371
 372 In Module mode the loaded find module is responsible to honor the
 373 request detailed by these variables; see the find module for details.
 374 In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and
 375 ``[version]`` options automatically but leaves it to the package
 376 configuration file to handle components in a way that makes sense
 377 for the package.  The package configuration file may set
 378 ``<package>_FOUND`` to false to tell ``find_package`` that component
 379 requirements are not satisfied.
 380
 381 See the :command:`cmake_policy` command documentation for discussion
 382 of the ``NO_POLICY_SCOPE`` option.