1find_package 2------------ 3 4.. only:: html 5 6 .. contents:: 7 8Find a package (usually provided by something external to the project), 9and load its package-specific details. 10 11Search Modes 12^^^^^^^^^^^^ 13 14The command has two very distinct ways of conducting the search: 15 16**Module mode** 17 In this mode, CMake searches for a file called ``Find<PackageName>.cmake``, 18 looking first in the locations listed in the :variable:`CMAKE_MODULE_PATH`, 19 then among the :ref:`Find Modules` provided by the CMake installation. 20 If the file is found, it is read and processed by CMake. It is responsible 21 for finding the package, checking the version, and producing any needed 22 messages. Some Find modules provide limited or no support for versioning; 23 check the Find module's documentation. 24 25 The ``Find<PackageName>.cmake`` file is not typically provided by the 26 package itself. Rather, it is normally provided by something external to 27 the package, such as the operating system, CMake itself, or even the project 28 from which the ``find_package()`` command was called. Being externally 29 provided, :ref:`Find Modules` tend to be heuristic in nature and are 30 susceptible to becoming out-of-date. They typically search for certain 31 libraries, files and other package artifacts. 32 33 Module mode is only supported by the 34 :ref:`basic command signature <Basic Signature>`. 35 36**Config mode** 37 In this mode, CMake searches for a file called 38 ``<lowercasePackageName>-config.cmake`` or ``<PackageName>Config.cmake``. 39 It will also look for ``<lowercasePackageName>-config-version.cmake`` or 40 ``<PackageName>ConfigVersion.cmake`` if version details were specified 41 (see :ref:`version selection` for an explanation of how these separate 42 version files are used). 43 44 In config mode, the command can be given a list of names to search for 45 as package names. The locations where CMake searches for the config and 46 version files is considerably more complicated than for Module mode 47 (see :ref:`search procedure`). 48 49 The config and version files are typically installed as part of the 50 package, so they tend to be more reliable than Find modules. They usually 51 contain direct knowledge of the package contents, so no searching or 52 heuristics are needed within the config or version files themselves. 53 54 Config mode is supported by both the :ref:`basic <Basic Signature>` and 55 :ref:`full <Full Signature>` command signatures. 56 57The command arguments determine which of the above modes is used. When the 58`basic signature`_ is used, the command searches in Module mode first. 59If the package is not found, the search falls back to Config mode. 60A user may set the :variable:`CMAKE_FIND_PACKAGE_PREFER_CONFIG` variable 61to true to reverse the priority and direct CMake to search using Config mode 62first before falling back to Module mode. The basic signature can also be 63forced to use only Module mode with a ``MODULE`` keyword. If the 64`full signature`_ is used, the command only searches in Config mode. 65 66Where possible, user code should generally look for packages using the 67`basic signature`_, since that allows the package to be found with either mode. 68Project maintainers wishing to provide a config package should understand 69the bigger picture, as explained in :ref:`Full Signature` and all subsequent 70sections on this page. 71 72.. _`basic signature`: 73 74Basic Signature 75^^^^^^^^^^^^^^^ 76 77.. code-block:: cmake 78 79 find_package(<PackageName> [version] [EXACT] [QUIET] [MODULE] 80 [REQUIRED] [[COMPONENTS] [components...]] 81 [OPTIONAL_COMPONENTS components...] 82 [NO_POLICY_SCOPE]) 83 84The basic signature is supported by both Module and Config modes. 85The ``MODULE`` keyword implies that only Module mode can be used to find 86the package, with no fallback to Config mode. 87 88Regardless of the mode used, a ``<PackageName>_FOUND`` variable will be 89set to indicate whether the package was found. When the package is found, 90package-specific information may be provided through other variables and 91:ref:`Imported Targets` documented by the package itself. The 92``QUIET`` option disables informational messages, including those indicating 93that the package cannot be found if it is not ``REQUIRED``. The ``REQUIRED`` 94option stops processing with an error message if the package cannot be found. 95 96A package-specific list of required components may be listed after the 97``COMPONENTS`` keyword. If any of these components are not able to be 98satisfied, the package overall is considered to be not found. If the 99``REQUIRED`` option is also present, this is treated as a fatal error, 100otherwise execution still continues. As a form of shorthand, if the 101``REQUIRED`` option is present, the ``COMPONENTS`` keyword can be omitted 102and the required components can be listed directly after ``REQUIRED``. 103 104Additional optional components may be listed after 105``OPTIONAL_COMPONENTS``. If these cannot be satisfied, the package overall 106can still be considered found, as long as all required components are 107satisfied. 108 109The set of available components and their meaning are defined by the 110target package. Formally, it is up to the target package how to 111interpret the component information given to it, but it should follow 112the expectations stated above. For calls where no components are specified, 113there is no single expected behavior and target packages should clearly 114define what occurs in such cases. Common arrangements include assuming it 115should find all components, no components or some well-defined subset of the 116available components. 117 118.. _FIND_PACKAGE_VERSION_FORMAT: 119 120The ``[version]`` argument requests a version with which the package found 121should be compatible. There are two possible forms in which it may be 122specified: 123 124 * A single version with the format ``major[.minor[.patch[.tweak]]]``, where 125 each component is a numeric value. 126 * A version range with the format ``versionMin...[<]versionMax`` where 127 ``versionMin`` and ``versionMax`` have the same format and constraints 128 on components being integers as the single version. By default, both end 129 points are included. By specifying ``<``, the upper end point will be 130 excluded. Version ranges are only supported with CMake 3.19 or later. 131 132The ``EXACT`` option requests that the version be matched exactly. This option 133is incompatible with the specification of a version range. 134 135If no ``[version]`` and/or component list is given to a recursive invocation 136inside a find-module, the corresponding arguments are forwarded 137automatically from the outer call (including the ``EXACT`` flag for 138``[version]``). Version support is currently provided only on a 139package-by-package basis (see the `Version Selection`_ section below). 140When a version range is specified but the package is only designed to expect 141a single version, the package will ignore the upper end point of the range and 142only take the single version at the lower end of the range into account. 143 144See the :command:`cmake_policy` command documentation for discussion 145of the ``NO_POLICY_SCOPE`` option. 146 147.. _`full signature`: 148 149Full Signature 150^^^^^^^^^^^^^^ 151 152.. code-block:: cmake 153 154 find_package(<PackageName> [version] [EXACT] [QUIET] 155 [REQUIRED] [[COMPONENTS] [components...]] 156 [OPTIONAL_COMPONENTS components...] 157 [CONFIG|NO_MODULE] 158 [NO_POLICY_SCOPE] 159 [NAMES name1 [name2 ...]] 160 [CONFIGS config1 [config2 ...]] 161 [HINTS path1 [path2 ... ]] 162 [PATHS path1 [path2 ... ]] 163 [PATH_SUFFIXES suffix1 [suffix2 ...]] 164 [NO_DEFAULT_PATH] 165 [NO_PACKAGE_ROOT_PATH] 166 [NO_CMAKE_PATH] 167 [NO_CMAKE_ENVIRONMENT_PATH] 168 [NO_SYSTEM_ENVIRONMENT_PATH] 169 [NO_CMAKE_PACKAGE_REGISTRY] 170 [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing. 171 [NO_CMAKE_SYSTEM_PATH] 172 [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY] 173 [CMAKE_FIND_ROOT_PATH_BOTH | 174 ONLY_CMAKE_FIND_ROOT_PATH | 175 NO_CMAKE_FIND_ROOT_PATH]) 176 177The ``CONFIG`` option, the synonymous ``NO_MODULE`` option, or the use 178of options not specified in the `basic signature`_ all enforce pure Config 179mode. In pure Config mode, the command skips Module mode search and 180proceeds at once with Config mode search. 181 182Config mode search attempts to locate a configuration file provided by the 183package to be found. A cache entry called ``<PackageName>_DIR`` is created to 184hold the directory containing the file. By default the command 185searches for a package with the name ``<PackageName>``. If the ``NAMES`` option 186is given the names following it are used instead of ``<PackageName>``. 187The command searches for a file called ``<PackageName>Config.cmake`` or 188``<lowercasePackageName>-config.cmake`` for each name specified. 189A replacement set of possible configuration file names may be given 190using the ``CONFIGS`` option. The :ref:`search procedure` is specified below. 191Once found, any :ref:`version constraint <version selection>` is checked, 192and if satisfied, the configuration file is read and processed by CMake. 193Since the file is provided by the package it already knows the 194location of package contents. The full path to the configuration file 195is stored in the cmake variable ``<PackageName>_CONFIG``. 196 197All configuration files which have been considered by CMake while 198searching for the package with an appropriate version are stored in the 199``<PackageName>_CONSIDERED_CONFIGS`` variable, and the associated versions 200in the ``<PackageName>_CONSIDERED_VERSIONS`` variable. 201 202If the package configuration file cannot be found CMake will generate 203an error describing the problem unless the ``QUIET`` argument is 204specified. If ``REQUIRED`` is specified and the package is not found a 205fatal error is generated and the configure step stops executing. If 206``<PackageName>_DIR`` has been set to a directory not containing a 207configuration file CMake will ignore it and search from scratch. 208 209Package maintainers providing CMake package configuration files are 210encouraged to name and install them such that the :ref:`search procedure` 211outlined below will find them without requiring use of additional options. 212 213.. _`search procedure`: 214 215Config Mode Search Procedure 216^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 217 218.. note:: 219 When Config mode is used, this search procedure is applied regardless of 220 whether the :ref:`full <full signature>` or :ref:`basic <basic signature>` 221 signature was given. 222 223CMake constructs a set of possible installation prefixes for the 224package. Under each prefix several directories are searched for a 225configuration file. The tables below show the directories searched. 226Each entry is meant for installation trees following Windows (``W``), UNIX 227(``U``), or Apple (``A``) conventions:: 228 229 <prefix>/ (W) 230 <prefix>/(cmake|CMake)/ (W) 231 <prefix>/<name>*/ (W) 232 <prefix>/<name>*/(cmake|CMake)/ (W) 233 <prefix>/(lib/<arch>|lib*|share)/cmake/<name>*/ (U) 234 <prefix>/(lib/<arch>|lib*|share)/<name>*/ (U) 235 <prefix>/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (U) 236 <prefix>/<name>*/(lib/<arch>|lib*|share)/cmake/<name>*/ (W/U) 237 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/ (W/U) 238 <prefix>/<name>*/(lib/<arch>|lib*|share)/<name>*/(cmake|CMake)/ (W/U) 239 240On systems supporting macOS :prop_tgt:`FRAMEWORK` and :prop_tgt:`BUNDLE`, the 241following directories are searched for Frameworks or Application Bundles 242containing a configuration file:: 243 244 <prefix>/<name>.framework/Resources/ (A) 245 <prefix>/<name>.framework/Resources/CMake/ (A) 246 <prefix>/<name>.framework/Versions/*/Resources/ (A) 247 <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A) 248 <prefix>/<name>.app/Contents/Resources/ (A) 249 <prefix>/<name>.app/Contents/Resources/CMake/ (A) 250 251In all cases the ``<name>`` is treated as case-insensitive and corresponds 252to any of the names specified (``<PackageName>`` or names given by ``NAMES``). 253 254Paths with ``lib/<arch>`` are enabled if the 255:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. ``lib*`` includes one 256or more of the values ``lib64``, ``lib32``, ``libx32`` or ``lib`` (searched in 257that order). 258 259* Paths with ``lib64`` are searched on 64 bit platforms if the 260 :prop_gbl:`FIND_LIBRARY_USE_LIB64_PATHS` property is set to ``TRUE``. 261* Paths with ``lib32`` are searched on 32 bit platforms if the 262 :prop_gbl:`FIND_LIBRARY_USE_LIB32_PATHS` property is set to ``TRUE``. 263* Paths with ``libx32`` are searched on platforms using the x32 ABI 264 if the :prop_gbl:`FIND_LIBRARY_USE_LIBX32_PATHS` property is set to ``TRUE``. 265* The ``lib`` path is always searched. 266 267If ``PATH_SUFFIXES`` is specified, the suffixes are appended to each 268(``W``) or (``U``) directory entry one-by-one. 269 270This set of directories is intended to work in cooperation with 271projects that provide configuration files in their installation trees. 272Directories above marked with (``W``) are intended for installations on 273Windows where the prefix may point at the top of an application's 274installation directory. Those marked with (``U``) are intended for 275installations on UNIX platforms where the prefix is shared by multiple 276packages. This is merely a convention, so all (``W``) and (``U``) directories 277are still searched on all platforms. Directories marked with (``A``) are 278intended for installations on Apple platforms. The 279:variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` 280variables determine the order of preference. 281 282The set of installation prefixes is constructed using the following 283steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are 284enabled. 285 2861. .. versionadded:: 3.12 287 Search paths specified in the :variable:`<PackageName>_ROOT` CMake 288 variable and the :envvar:`<PackageName>_ROOT` environment variable, 289 where ``<PackageName>`` is the package to be found. 290 The package root variables are maintained as a stack so if 291 called from within a find module, root paths from the parent's find 292 module will also be searched after paths for the current package. 293 This can be skipped if ``NO_PACKAGE_ROOT_PATH`` is passed or by setting 294 the :variable:`CMAKE_FIND_USE_PACKAGE_ROOT_PATH` to ``FALSE``. 295 See policy :policy:`CMP0074`. 296 2972. Search paths specified in cmake-specific cache variables. These 298 are intended to be used on the command line with a ``-DVAR=value``. 299 The values are interpreted as :ref:`semicolon-separated lists <CMake Language Lists>`. 300 This can be skipped if ``NO_CMAKE_PATH`` is passed or by setting the 301 :variable:`CMAKE_FIND_USE_CMAKE_PATH` to ``FALSE``: 302 303 * :variable:`CMAKE_PREFIX_PATH` 304 * :variable:`CMAKE_FRAMEWORK_PATH` 305 * :variable:`CMAKE_APPBUNDLE_PATH` 306 3073. Search paths specified in cmake-specific environment variables. 308 These are intended to be set in the user's shell configuration, 309 and therefore use the host's native path separator 310 (``;`` on Windows and ``:`` on UNIX). 311 This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed or by setting 312 the :variable:`CMAKE_FIND_USE_CMAKE_ENVIRONMENT_PATH` to ``FALSE``: 313 314 * ``<PackageName>_DIR`` 315 * :envvar:`CMAKE_PREFIX_PATH` 316 * ``CMAKE_FRAMEWORK_PATH`` 317 * ``CMAKE_APPBUNDLE_PATH`` 318 3194. Search paths specified by the ``HINTS`` option. These should be paths 320 computed by system introspection, such as a hint provided by the 321 location of another item already found. Hard-coded guesses should 322 be specified with the ``PATHS`` option. 323 3245. Search the standard system environment variables. This can be 325 skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed or by setting the 326 :variable:`CMAKE_FIND_USE_SYSTEM_ENVIRONMENT_PATH` to ``FALSE``. Path entries 327 ending in ``/bin`` or ``/sbin`` are automatically converted to their 328 parent directories: 329 330 * ``PATH`` 331 3326. Search paths stored in the CMake :ref:`User Package Registry`. 333 This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by 334 setting the variable :variable:`CMAKE_FIND_USE_PACKAGE_REGISTRY` 335 to ``FALSE`` or the deprecated variable 336 :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` to ``TRUE``. 337 338 See the :manual:`cmake-packages(7)` manual for details on the user 339 package registry. 340 3417. Search cmake variables defined in the Platform files for the 342 current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is 343 passed or by setting the :variable:`CMAKE_FIND_USE_CMAKE_SYSTEM_PATH` 344 to ``FALSE``: 345 346 * :variable:`CMAKE_SYSTEM_PREFIX_PATH` 347 * :variable:`CMAKE_SYSTEM_FRAMEWORK_PATH` 348 * :variable:`CMAKE_SYSTEM_APPBUNDLE_PATH` 349 350 The platform paths that these variables contain are locations that 351 typically include installed software. An example being ``/usr/local`` for 352 UNIX based platforms. 353 3548. Search paths stored in the CMake :ref:`System Package Registry`. 355 This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed 356 or by setting the :variable:`CMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY` 357 variable to ``FALSE`` or the deprecated variable 358 :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. 359 360 See the :manual:`cmake-packages(7)` manual for details on the system 361 package registry. 362 3639. Search paths specified by the ``PATHS`` option. These are typically 364 hard-coded guesses. 365 366.. versionadded:: 3.16 367 Added the ``CMAKE_FIND_USE_<CATEGORY>`` variables to globally disable 368 various search locations. 369 370.. |FIND_XXX| replace:: find_package 371.. |FIND_ARGS_XXX| replace:: <PackageName> 372.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: 373 :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` 374 375.. include:: FIND_XXX_ROOT.txt 376.. include:: FIND_XXX_ORDER.txt 377 378By default the value stored in the result variable will be the path at 379which the file is found. The :variable:`CMAKE_FIND_PACKAGE_RESOLVE_SYMLINKS` 380variable may be set to ``TRUE`` before calling ``find_package`` in order 381to resolve symbolic links and store the real path to the file. 382 383Every non-REQUIRED ``find_package`` call can be disabled or made REQUIRED: 384 385* Setting the :variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable 386 to ``TRUE`` disables the package. 387 388* Setting the :variable:`CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>` variable 389 to ``TRUE`` makes the package REQUIRED. 390 391Setting both variables to ``TRUE`` simultaneously is an error. 392 393.. _`version selection`: 394 395Config Mode Version Selection 396^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 397 398.. note:: 399 When Config mode is used, this version selection process is applied 400 regardless of whether the :ref:`full <full signature>` or 401 :ref:`basic <basic signature>` signature was given. 402 403When the ``[version]`` argument is given, Config mode will only find a 404version of the package that claims compatibility with the requested 405version (see :ref:`format specification <FIND_PACKAGE_VERSION_FORMAT>`). If the 406``EXACT`` option is given, only a version of the package claiming an exact match 407of the requested version may be found. CMake does not establish any 408convention for the meaning of version numbers. Package version 409numbers are checked by "version" files provided by the packages 410themselves. For a candidate package configuration file 411``<config-file>.cmake`` the corresponding version file is located next 412to it and named either ``<config-file>-version.cmake`` or 413``<config-file>Version.cmake``. If no such version file is available 414then the configuration file is assumed to not be compatible with any 415requested version. A basic version file containing generic version 416matching code can be created using the 417:module:`CMakePackageConfigHelpers` module. When a version file 418is found it is loaded to check the requested version number. The 419version file is loaded in a nested scope in which the following 420variables have been defined: 421 422``PACKAGE_FIND_NAME`` 423 The ``<PackageName>`` 424``PACKAGE_FIND_VERSION`` 425 Full requested version string 426``PACKAGE_FIND_VERSION_MAJOR`` 427 Major version if requested, else 0 428``PACKAGE_FIND_VERSION_MINOR`` 429 Minor version if requested, else 0 430``PACKAGE_FIND_VERSION_PATCH`` 431 Patch version if requested, else 0 432``PACKAGE_FIND_VERSION_TWEAK`` 433 Tweak version if requested, else 0 434``PACKAGE_FIND_VERSION_COUNT`` 435 Number of version components, 0 to 4 436 437When a version range is specified, the above version variables will hold 438values based on the lower end of the version range. This is to preserve 439compatibility with packages that have not been implemented to expect version 440ranges. In addition, the version range will be described by the following 441variables: 442 443``PACKAGE_FIND_VERSION_RANGE`` 444 Full requested version range string 445``PACKAGE_FIND_VERSION_RANGE_MIN`` 446 This specifies whether the lower end point of the version range should be 447 included or excluded. Currently, the only supported value for this variable 448 is ``INCLUDE``. 449``PACKAGE_FIND_VERSION_RANGE_MAX`` 450 This specifies whether the upper end point of the version range should be 451 included or excluded. The supported values for this variable are 452 ``INCLUDE`` and ``EXCLUDE``. 453 454``PACKAGE_FIND_VERSION_MIN`` 455 Full requested version string of the lower end point of the range 456``PACKAGE_FIND_VERSION_MIN_MAJOR`` 457 Major version of the lower end point if requested, else 0 458``PACKAGE_FIND_VERSION_MIN_MINOR`` 459 Minor version of the lower end point if requested, else 0 460``PACKAGE_FIND_VERSION_MIN_PATCH`` 461 Patch version of the lower end point if requested, else 0 462``PACKAGE_FIND_VERSION_MIN_TWEAK`` 463 Tweak version of the lower end point if requested, else 0 464``PACKAGE_FIND_VERSION_MIN_COUNT`` 465 Number of version components of the lower end point, 0 to 4 466 467``PACKAGE_FIND_VERSION_MAX`` 468 Full requested version string of the upper end point of the range 469``PACKAGE_FIND_VERSION_MAX_MAJOR`` 470 Major version of the upper end point if requested, else 0 471``PACKAGE_FIND_VERSION_MAX_MINOR`` 472 Minor version of the upper end point if requested, else 0 473``PACKAGE_FIND_VERSION_MAX_PATCH`` 474 Patch version of the upper end point if requested, else 0 475``PACKAGE_FIND_VERSION_MAX_TWEAK`` 476 Tweak version of the upper end point if requested, else 0 477``PACKAGE_FIND_VERSION_MAX_COUNT`` 478 Number of version components of the upper end point, 0 to 4 479 480Regardless of whether a single version or a version range is specified, the 481variable ``PACKAGE_FIND_VERSION_COMPLETE`` will be defined and will hold 482the full requested version string as specified. 483 484The version file checks whether it satisfies the requested version and 485sets these variables: 486 487``PACKAGE_VERSION`` 488 Full provided version string 489``PACKAGE_VERSION_EXACT`` 490 True if version is exact match 491``PACKAGE_VERSION_COMPATIBLE`` 492 True if version is compatible 493``PACKAGE_VERSION_UNSUITABLE`` 494 True if unsuitable as any version 495 496These variables are checked by the ``find_package`` command to determine 497whether the configuration file provides an acceptable version. They 498are not available after the ``find_package`` call returns. If the version 499is acceptable the following variables are set: 500 501``<PackageName>_VERSION`` 502 Full provided version string 503``<PackageName>_VERSION_MAJOR`` 504 Major version if provided, else 0 505``<PackageName>_VERSION_MINOR`` 506 Minor version if provided, else 0 507``<PackageName>_VERSION_PATCH`` 508 Patch version if provided, else 0 509``<PackageName>_VERSION_TWEAK`` 510 Tweak version if provided, else 0 511``<PackageName>_VERSION_COUNT`` 512 Number of version components, 0 to 4 513 514and the corresponding package configuration file is loaded. 515When multiple package configuration files are available whose version files 516claim compatibility with the version requested it is unspecified which 517one is chosen: unless the variable :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` 518is set no attempt is made to choose a highest or closest version number. 519 520To control the order in which ``find_package`` checks for compatibility use 521the two variables :variable:`CMAKE_FIND_PACKAGE_SORT_ORDER` and 522:variable:`CMAKE_FIND_PACKAGE_SORT_DIRECTION`. 523For instance in order to select the highest version one can set 524 525.. code-block:: cmake 526 527 SET(CMAKE_FIND_PACKAGE_SORT_ORDER NATURAL) 528 SET(CMAKE_FIND_PACKAGE_SORT_DIRECTION DEC) 529 530before calling ``find_package``. 531 532Package File Interface Variables 533^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 534 535When loading a find module or package configuration file ``find_package`` 536defines variables to provide information about the call arguments (and 537restores their original state before returning): 538 539``CMAKE_FIND_PACKAGE_NAME`` 540 The ``<PackageName>`` which is searched for 541``<PackageName>_FIND_REQUIRED`` 542 True if ``REQUIRED`` option was given 543``<PackageName>_FIND_QUIETLY`` 544 True if ``QUIET`` option was given 545``<PackageName>_FIND_VERSION`` 546 Full requested version string 547``<PackageName>_FIND_VERSION_MAJOR`` 548 Major version if requested, else 0 549``<PackageName>_FIND_VERSION_MINOR`` 550 Minor version if requested, else 0 551``<PackageName>_FIND_VERSION_PATCH`` 552 Patch version if requested, else 0 553``<PackageName>_FIND_VERSION_TWEAK`` 554 Tweak version if requested, else 0 555``<PackageName>_FIND_VERSION_COUNT`` 556 Number of version components, 0 to 4 557``<PackageName>_FIND_VERSION_EXACT`` 558 True if ``EXACT`` option was given 559``<PackageName>_FIND_COMPONENTS`` 560 List of specified components (required and optional) 561``<PackageName>_FIND_REQUIRED_<c>`` 562 True if component ``<c>`` is required, 563 false if component ``<c>`` is optional 564 565When a version range is specified, the above version variables will hold 566values based on the lower end of the version range. This is to preserve 567compatibility with packages that have not been implemented to expect version 568ranges. In addition, the version range will be described by the following 569variables: 570 571``<PackageName>_FIND_VERSION_RANGE`` 572 Full requested version range string 573``<PackageName>_FIND_VERSION_RANGE_MIN`` 574 This specifies whether the lower end point of the version range is 575 included or excluded. Currently, ``INCLUDE`` is the only supported value. 576``<PackageName>_FIND_VERSION_RANGE_MAX`` 577 This specifies whether the upper end point of the version range is 578 included or excluded. The possible values for this variable are 579 ``INCLUDE`` or ``EXCLUDE``. 580 581``<PackageName>_FIND_VERSION_MIN`` 582 Full requested version string of the lower end point of the range 583``<PackageName>_FIND_VERSION_MIN_MAJOR`` 584 Major version of the lower end point if requested, else 0 585``<PackageName>_FIND_VERSION_MIN_MINOR`` 586 Minor version of the lower end point if requested, else 0 587``<PackageName>_FIND_VERSION_MIN_PATCH`` 588 Patch version of the lower end point if requested, else 0 589``<PackageName>_FIND_VERSION_MIN_TWEAK`` 590 Tweak version of the lower end point if requested, else 0 591``<PackageName>_FIND_VERSION_MIN_COUNT`` 592 Number of version components of the lower end point, 0 to 4 593 594``<PackageName>_FIND_VERSION_MAX`` 595 Full requested version string of the upper end point of the range 596``<PackageName>_FIND_VERSION_MAX_MAJOR`` 597 Major version of the upper end point if requested, else 0 598``<PackageName>_FIND_VERSION_MAX_MINOR`` 599 Minor version of the upper end point if requested, else 0 600``<PackageName>_FIND_VERSION_MAX_PATCH`` 601 Patch version of the upper end point if requested, else 0 602``<PackageName>_FIND_VERSION_MAX_TWEAK`` 603 Tweak version of the upper end point if requested, else 0 604``<PackageName>_FIND_VERSION_MAX_COUNT`` 605 Number of version components of the upper end point, 0 to 4 606 607Regardless of whether a single version or a version range is specified, the 608variable ``<PackageName>_FIND_VERSION_COMPLETE`` will be defined and will hold 609the full requested version string as specified. 610 611In Module mode the loaded find module is responsible to honor the 612request detailed by these variables; see the find module for details. 613In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and 614``[version]`` options automatically but leaves it to the package 615configuration file to handle components in a way that makes sense 616for the package. The package configuration file may set 617``<PackageName>_FOUND`` to false to tell ``find_package`` that component 618requirements are not satisfied. 619