diff options
Diffstat (limited to 'share/cmake-3.6/Help/command/find_package.rst')
| -rw-r--r-- | share/cmake-3.6/Help/command/find_package.rst | 344 |
1 files changed, 0 insertions, 344 deletions
diff --git a/share/cmake-3.6/Help/command/find_package.rst b/share/cmake-3.6/Help/command/find_package.rst deleted file mode 100644 index 58dff9d..0000000 --- a/share/cmake-3.6/Help/command/find_package.rst +++ /dev/null @@ -1,344 +0,0 @@ -find_package ------------- - -Load settings for an external project. - -:: - - find_package(<package> [version] [EXACT] [QUIET] [MODULE] - [REQUIRED] [[COMPONENTS] [components...]] - [OPTIONAL_COMPONENTS components...] - [NO_POLICY_SCOPE]) - -Finds and loads settings from an external project. ``<package>_FOUND`` -will be set to indicate whether the package was found. When the -package is found package-specific information is provided through -variables and :ref:`Imported Targets` documented by the package itself. The -``QUIET`` option disables messages if the package cannot be found. The -``MODULE`` option disables the second signature documented below. The -``REQUIRED`` option stops processing with an error message if the package -cannot be found. - -A package-specific list of required components may be listed after the -``COMPONENTS`` option (or after the ``REQUIRED`` option if present). -Additional optional components may be listed after -``OPTIONAL_COMPONENTS``. Available components and their influence on -whether a package is considered to be found are defined by the target -package. - -The ``[version]`` argument requests a version with which the package found -should be compatible (format is ``major[.minor[.patch[.tweak]]]``). The -``EXACT`` option requests that the version be matched exactly. If no -``[version]`` and/or component list is given to a recursive invocation -inside a find-module, the corresponding arguments are forwarded -automatically from the outer call (including the ``EXACT`` flag for -``[version]``). Version support is currently provided only on a -package-by-package basis (details below). - -User code should generally look for packages using the above simple -signature. The remainder of this command documentation specifies the -full command signature and details of the search process. Project -maintainers wishing to provide a package to be found by this command -are encouraged to read on. - -The command has two modes by which it searches for packages: "Module" -mode and "Config" mode. Module mode is available when the command is -invoked with the above reduced signature. CMake searches for a file -called ``Find<package>.cmake`` in the :variable:`CMAKE_MODULE_PATH` -followed by the CMake installation. If the file is found, it is read -and processed by CMake. It is responsible for finding the package, -checking the version, and producing any needed messages. Many -find-modules provide limited or no support for versioning; check -the module documentation. If no module is found and the ``MODULE`` -option is not given the command proceeds to Config mode. - -The complete Config mode command signature is:: - - find_package(<package> [version] [EXACT] [QUIET] - [REQUIRED] [[COMPONENTS] [components...]] - [CONFIG|NO_MODULE] - [NO_POLICY_SCOPE] - [NAMES name1 [name2 ...]] - [CONFIGS config1 [config2 ...]] - [HINTS path1 [path2 ... ]] - [PATHS path1 [path2 ... ]] - [PATH_SUFFIXES suffix1 [suffix2 ...]] - [NO_DEFAULT_PATH] - [NO_CMAKE_ENVIRONMENT_PATH] - [NO_CMAKE_PATH] - [NO_SYSTEM_ENVIRONMENT_PATH] - [NO_CMAKE_PACKAGE_REGISTRY] - [NO_CMAKE_BUILDS_PATH] # Deprecated; does nothing. - [NO_CMAKE_SYSTEM_PATH] - [NO_CMAKE_SYSTEM_PACKAGE_REGISTRY] - [CMAKE_FIND_ROOT_PATH_BOTH | - ONLY_CMAKE_FIND_ROOT_PATH | - NO_CMAKE_FIND_ROOT_PATH]) - -The ``CONFIG`` option may be used to skip Module mode explicitly and -switch to Config mode. It is synonymous to using ``NO_MODULE``. Config -mode is also implied by use of options not specified in the reduced -signature. - -Config mode attempts to locate a configuration file provided by the -package to be found. A cache entry called ``<package>_DIR`` is created to -hold the directory containing the file. By default the command -searches for a package with the name ``<package>``. If the ``NAMES`` option -is given the names following it are used instead of ``<package>``. The -command searches for a file called ``<name>Config.cmake`` or -``<lower-case-name>-config.cmake`` for each name specified. A -replacement set of possible configuration file names may be given -using the ``CONFIGS`` option. The search procedure is specified below. -Once found, the configuration file is read and processed by CMake. -Since the file is provided by the package it already knows the -location of package contents. The full path to the configuration file -is stored in the cmake variable ``<package>_CONFIG``. - -All configuration files which have been considered by CMake while -searching for an installation of the package with an appropriate -version are stored in the cmake variable ``<package>_CONSIDERED_CONFIGS``, -the associated versions in ``<package>_CONSIDERED_VERSIONS``. - -If the package configuration file cannot be found CMake will generate -an error describing the problem unless the ``QUIET`` argument is -specified. If ``REQUIRED`` is specified and the package is not found a -fatal error is generated and the configure step stops executing. If -``<package>_DIR`` has been set to a directory not containing a -configuration file CMake will ignore it and search from scratch. - -When the ``[version]`` argument is given Config mode will only find a -version of the package that claims compatibility with the requested -version (format is ``major[.minor[.patch[.tweak]]]``). If the ``EXACT`` -option is given only a version of the package claiming an exact match -of the requested version may be found. CMake does not establish any -convention for the meaning of version numbers. Package version -numbers are checked by "version" files provided by the packages -themselves. For a candidate package configuration file -``<config-file>.cmake`` the corresponding version file is located next -to it and named either ``<config-file>-version.cmake`` or -``<config-file>Version.cmake``. If no such version file is available -then the configuration file is assumed to not be compatible with any -requested version. A basic version file containing generic version -matching code can be created using the -:module:`CMakePackageConfigHelpers` module. When a version file -is found it is loaded to check the requested version number. The -version file is loaded in a nested scope in which the following -variables have been defined: - -``PACKAGE_FIND_NAME`` - the ``<package>`` name -``PACKAGE_FIND_VERSION`` - full requested version string -``PACKAGE_FIND_VERSION_MAJOR`` - major version if requested, else 0 -``PACKAGE_FIND_VERSION_MINOR`` - minor version if requested, else 0 -``PACKAGE_FIND_VERSION_PATCH`` - patch version if requested, else 0 -``PACKAGE_FIND_VERSION_TWEAK`` - tweak version if requested, else 0 -``PACKAGE_FIND_VERSION_COUNT`` - number of version components, 0 to 4 - -The version file checks whether it satisfies the requested version and -sets these variables: - -``PACKAGE_VERSION`` - full provided version string -``PACKAGE_VERSION_EXACT`` - true if version is exact match -``PACKAGE_VERSION_COMPATIBLE`` - true if version is compatible -``PACKAGE_VERSION_UNSUITABLE`` - true if unsuitable as any version - -These variables are checked by the ``find_package`` command to determine -whether the configuration file provides an acceptable version. They -are not available after the find_package call returns. If the version -is acceptable the following variables are set: - -``<package>_VERSION`` - full provided version string -``<package>_VERSION_MAJOR`` - major version if provided, else 0 -``<package>_VERSION_MINOR`` - minor version if provided, else 0 -``<package>_VERSION_PATCH`` - patch version if provided, else 0 -``<package>_VERSION_TWEAK`` - tweak version if provided, else 0 -``<package>_VERSION_COUNT`` - number of version components, 0 to 4 - -and the corresponding package configuration file is loaded. When -multiple package configuration files are available whose version files -claim compatibility with the version requested it is unspecified which -one is chosen. No attempt is made to choose a highest or closest -version number. - -Config mode provides an elaborate interface and search procedure. -Much of the interface is provided for completeness and for use -internally by find-modules loaded by Module mode. Most user code -should simply call:: - - find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET]) - -in order to find a package. Package maintainers providing CMake -package configuration files are encouraged to name and install them -such that the procedure outlined below will find them without -requiring use of additional options. - -CMake constructs a set of possible installation prefixes for the -package. Under each prefix several directories are searched for a -configuration file. The tables below show the directories searched. -Each entry is meant for installation trees following Windows (W), UNIX -(U), or Apple (A) conventions:: - - <prefix>/ (W) - <prefix>/(cmake|CMake)/ (W) - <prefix>/<name>*/ (W) - <prefix>/<name>*/(cmake|CMake)/ (W) - <prefix>/(lib/<arch>|lib|share)/cmake/<name>*/ (U) - <prefix>/(lib/<arch>|lib|share)/<name>*/ (U) - <prefix>/(lib/<arch>|lib|share)/<name>*/(cmake|CMake)/ (U) - -On systems supporting OS X Frameworks and Application Bundles the -following directories are searched for frameworks or bundles -containing a configuration file:: - - <prefix>/<name>.framework/Resources/ (A) - <prefix>/<name>.framework/Resources/CMake/ (A) - <prefix>/<name>.framework/Versions/*/Resources/ (A) - <prefix>/<name>.framework/Versions/*/Resources/CMake/ (A) - <prefix>/<name>.app/Contents/Resources/ (A) - <prefix>/<name>.app/Contents/Resources/CMake/ (A) - -In all cases the ``<name>`` is treated as case-insensitive and corresponds -to any of the names specified (``<package>`` or names given by ``NAMES``). -Paths with ``lib/<arch>`` are enabled if the -:variable:`CMAKE_LIBRARY_ARCHITECTURE` variable is set. If ``PATH_SUFFIXES`` -is specified the suffixes are appended to each (W) or (U) directory entry -one-by-one. - -This set of directories is intended to work in cooperation with -projects that provide configuration files in their installation trees. -Directories above marked with (W) are intended for installations on -Windows where the prefix may point at the top of an application's -installation directory. Those marked with (U) are intended for -installations on UNIX platforms where the prefix is shared by multiple -packages. This is merely a convention, so all (W) and (U) directories -are still searched on all platforms. Directories marked with (A) are -intended for installations on Apple platforms. The -:variable:`CMAKE_FIND_FRAMEWORK` and :variable:`CMAKE_FIND_APPBUNDLE` -variables determine the order of preference. - -The set of installation prefixes is constructed using the following -steps. If ``NO_DEFAULT_PATH`` is specified all ``NO_*`` options are -enabled. - -1. Search paths specified in cmake-specific cache variables. These - are intended to be used on the command line with a ``-DVAR=value``. - This can be skipped if ``NO_CMAKE_PATH`` is passed:: - - CMAKE_PREFIX_PATH - CMAKE_FRAMEWORK_PATH - CMAKE_APPBUNDLE_PATH - -2. Search paths specified in cmake-specific environment variables. - These are intended to be set in the user's shell configuration. - This can be skipped if ``NO_CMAKE_ENVIRONMENT_PATH`` is passed:: - - <package>_DIR - CMAKE_PREFIX_PATH - CMAKE_FRAMEWORK_PATH - CMAKE_APPBUNDLE_PATH - -3. Search paths specified by the ``HINTS`` option. These should be paths - computed by system introspection, such as a hint provided by the - location of another item already found. Hard-coded guesses should - be specified with the ``PATHS`` option. - -4. Search the standard system environment variables. This can be - skipped if ``NO_SYSTEM_ENVIRONMENT_PATH`` is passed. Path entries - ending in ``/bin`` or ``/sbin`` are automatically converted to their - parent directories:: - - PATH - -5. Search paths stored in the CMake :ref:`User Package Registry`. - This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed or by - setting the :variable:`CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY` - to ``TRUE``. - See the :manual:`cmake-packages(7)` manual for details on the user - package registry. - -6. Search cmake variables defined in the Platform files for the - current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is - passed:: - - CMAKE_SYSTEM_PREFIX_PATH - CMAKE_SYSTEM_FRAMEWORK_PATH - CMAKE_SYSTEM_APPBUNDLE_PATH - -7. Search paths stored in the CMake :ref:`System Package Registry`. - This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed - or by setting the - :variable:`CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY` to ``TRUE``. - See the :manual:`cmake-packages(7)` manual for details on the system - package registry. - -8. Search paths specified by the ``PATHS`` option. These are typically - hard-coded guesses. - -.. |FIND_XXX| replace:: find_package -.. |FIND_ARGS_XXX| replace:: <package> -.. |CMAKE_FIND_ROOT_PATH_MODE_XXX| replace:: - :variable:`CMAKE_FIND_ROOT_PATH_MODE_PACKAGE` - -.. include:: FIND_XXX_ROOT.txt -.. include:: FIND_XXX_ORDER.txt - -Every non-REQUIRED ``find_package`` call can be disabled by setting the -:variable:`CMAKE_DISABLE_FIND_PACKAGE_<PackageName>` variable to ``TRUE``. - -When loading a find module or package configuration file ``find_package`` -defines variables to provide information about the call arguments (and -restores their original state before returning): - -``CMAKE_FIND_PACKAGE_NAME`` - the ``<package>`` name which is searched for -``<package>_FIND_REQUIRED`` - true if ``REQUIRED`` option was given -``<package>_FIND_QUIETLY`` - true if ``QUIET`` option was given -``<package>_FIND_VERSION`` - full requested version string -``<package>_FIND_VERSION_MAJOR`` - major version if requested, else 0 -``<package>_FIND_VERSION_MINOR`` - minor version if requested, else 0 -``<package>_FIND_VERSION_PATCH`` - patch version if requested, else 0 -``<package>_FIND_VERSION_TWEAK`` - tweak version if requested, else 0 -``<package>_FIND_VERSION_COUNT`` - number of version components, 0 to 4 -``<package>_FIND_VERSION_EXACT`` - true if ``EXACT`` option was given -``<package>_FIND_COMPONENTS`` - list of requested components -``<package>_FIND_REQUIRED_<c>`` - true if component ``<c>`` is required, - false if component ``<c>`` is optional - -In Module mode the loaded find module is responsible to honor the -request detailed by these variables; see the find module for details. -In Config mode ``find_package`` handles ``REQUIRED``, ``QUIET``, and -``[version]`` options automatically but leaves it to the package -configuration file to handle components in a way that makes sense -for the package. The package configuration file may set -``<package>_FOUND`` to false to tell ``find_package`` that component -requirements are not satisfied. - -See the :command:`cmake_policy` command documentation for discussion -of the ``NO_POLICY_SCOPE`` option. |