diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/find_package.rst | 360 | ||||
| -rw-r--r-- | Help/manual/cmake-developer.7.rst | 4 | ||||
| -rw-r--r-- | Help/manual/cmake-packages.7.rst | 129 | ||||
| -rw-r--r-- | Help/release/dev/Boost_NAMESPACE.rst | 5 |
4 files changed, 307 insertions, 191 deletions
diff --git a/Help/command/find_package.rst b/Help/command/find_package.rst index f09cb41..a2cff0a 100644 --- a/Help/command/find_package.rst +++ b/Help/command/find_package.rst @@ -10,29 +10,29 @@ Load settings for an external project. [OPTIONAL_COMPONENTS components...] [NO_POLICY_SCOPE]) -Finds and loads settings from an external project. <package>_FOUND +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 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 +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). +``COMPONENTS`` option (or after the ``REQUIRED`` option if present). Additional optional components may be listed after -OPTIONAL_COMPONENTS. Available components and their influence on +``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 +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 +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 @@ -44,17 +44,15 @@ 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 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. +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: - -:: +The complete Config mode command signature is:: find_package(<package> [version] [EXACT] [QUIET] [REQUIRED] [[COMPONENTS] [components...]] @@ -77,89 +75,100 @@ The complete Config mode command signature is: 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 +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 +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 +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. +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. +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. +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 +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 +``<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 +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 +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 +``<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 macro -write_basic_package_version_file(), see its documentation for more -details. 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 +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 +``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 +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 +``<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 @@ -170,9 +179,7 @@ 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 - -:: +should simply call:: find_package(<package> [major[.minor]] [EXACT] [REQUIRED|QUIET]) @@ -185,9 +192,7 @@ 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. - -:: +(U), or Apple (A) conventions:: <prefix>/ (W) <prefix>/(cmake|CMake)/ (W) @@ -199,9 +204,7 @@ Each entry is meant for installation trees following Windows (W), UNIX On systems supporting OS X Frameworks and Application Bundles the following directories are searched for frameworks or bundles -containing a configuration file: - -:: +containing a configuration file:: <prefix>/<name>.framework/Resources/ (A) <prefix>/<name>.framework/Resources/CMake/ (A) @@ -210,11 +213,12 @@ containing a configuration file: <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 CMAKE_LIBRARY_ARCHITECTURE is -set. If PATH_SUFFIXES is specified the suffixes are appended to each -(W) or (U) directory entry one-by-one. +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. @@ -225,97 +229,67 @@ 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 cmake variables -CMAKE_FIND_FRAMEWORK and CMAKE_FIND_APPBUNDLE determine the order of -preference as specified below. +``CMAKE_FIND_FRAMEWORK`` and ``CMAKE_FIND_APPBUNDLE`` +determine the order of preference as specified below. The set of installation prefixes is constructed using the following -steps. If NO_DEFAULT_PATH is specified all NO_* options are enabled. +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. +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 - 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:: -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. - <package>_DIR - CMAKE_PREFIX_PATH - CMAKE_FRAMEWORK_PATH - CMAKE_APPBUNDLE_PATH +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:: -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. + PATH -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. +5. Search project build trees recently configured in a :manual:`cmake-gui(1)`. + This can be skipped if ``NO_CMAKE_BUILDS_PATH`` is passed. It is intended + for the case when a user is building multiple dependent projects one + after another. -:: +6. Search paths stored in the CMake :ref:`User Package Registry`. + This can be skipped if ``NO_CMAKE_PACKAGE_REGISTRY`` is passed. + See the :manual:`cmake-packages(7)` manual for details on the user + package registry. - PATH +7. Search cmake variables defined in the Platform files for the + current system. This can be skipped if ``NO_CMAKE_SYSTEM_PATH`` is + passed:: -5. Search project build trees recently configured in a CMake GUI. -This can be skipped if NO_CMAKE_BUILDS_PATH is passed. It is intended -for the case when a user is building multiple dependent projects one -after another. + CMAKE_SYSTEM_PREFIX_PATH + CMAKE_SYSTEM_FRAMEWORK_PATH + CMAKE_SYSTEM_APPBUNDLE_PATH -6. Search paths stored in the CMake user package registry. This can -be skipped if NO_CMAKE_PACKAGE_REGISTRY is passed. On Windows a -<package> may appear under registry key +8. Search paths stored in the CMake :ref:`System Package Registry`. + This can be skipped if ``NO_CMAKE_SYSTEM_PACKAGE_REGISTRY`` is passed. + See the :manual:`cmake-packages(7)` manual for details on the system + package registry. -:: - - HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package> - -as a REG_SZ value, with arbitrary name, that specifies the directory -containing the package configuration file. On UNIX platforms a -<package> may appear under the directory - -:: - - ~/.cmake/packages/<package> - -as a file, with arbitrary name, whose content specifies the directory -containing the package configuration file. See the export(PACKAGE) -command to create user package registry entries for project build -trees. - -7. 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 - -8. Search paths stored in the CMake system package registry. This -can be skipped if NO_CMAKE_SYSTEM_PACKAGE_REGISTRY is passed. On -Windows a <package> may appear under registry key - -:: - - HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package> - -as a REG_SZ value, with arbitrary name, that specifies the directory -containing the package configuration file. There is no system package -registry on non-Windows platforms. - -9. Search paths specified by the PATHS option. These are typically -hard-coded guesses. +9. Search paths specified by the ``PATHS`` option. These are typically + hard-coded guesses. .. |FIND_XXX| replace:: find_package .. |FIND_ARGS_XXX| replace:: <package> @@ -326,37 +300,45 @@ hard-coded guesses. .. 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_<package> to TRUE. See the -documentation for the CMAKE_DISABLE_FIND_PACKAGE_<package> variable -for more information. +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 +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): -:: - - <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 +``<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 cmake_policy() command documentation for discussion of the -NO_POLICY_SCOPE option. +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. diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst index 887047c..376b56c 100644 --- a/Help/manual/cmake-developer.7.rst +++ b/Help/manual/cmake-developer.7.rst @@ -84,7 +84,7 @@ In some implementations, algorithms operating on iterators to a container of const char* dir = /*...*/; std::vector<std::string> vec; // ... - std::binary_find(vec.begin(), vec.end(), dir); // Wrong + std::binary_search(vec.begin(), vec.end(), dir); // Wrong The ``std::string`` may need to be explicitly constructed: @@ -93,7 +93,7 @@ The ``std::string`` may need to be explicitly constructed: const char* dir = /*...*/; std::vector<std::string> vec; // ... - std::binary_find(vec.begin(), vec.end(), std::string(dir)); // Ok + std::binary_search(vec.begin(), vec.end(), std::string(dir)); // Ok std::auto_ptr ------------- diff --git a/Help/manual/cmake-packages.7.rst b/Help/manual/cmake-packages.7.rst index e87eb83..1723826 100644 --- a/Help/manual/cmake-packages.7.rst +++ b/Help/manual/cmake-packages.7.rst @@ -488,3 +488,132 @@ Here, the ``ClimbingStats_NOTFOUND_MESSAGE`` is set to a diagnosis that the pack could not be found because an invalid component was specified. This message variable can be set for any case where the ``_FOUND`` variable is set to ``False``, and will be displayed to the user. + +.. _`Package Registry`: + +Package Registry +================ + +CMake provides two central locations to register packages that have +been built or installed anywhere on a system: + +* `User Package Registry`_ +* `System Package Registry`_ + +The registries are especially useful to help projects find packages in +non-standard install locations or directly in their own build trees. +A project may populate either the user or system registry (using its own +means, see below) to refer to its location. +In either case the package should store at the registered location a +`Package Configuration File`_ (``<package>Config.cmake``) and optionally a +`Package Version File`_ (``<package>ConfigVersion.cmake``). + +The :command:`find_package` command searches the two package registries +as two of the search steps specified in its documentation. If it has +sufficient permissions it also removes stale package registry entries +that refer to directories that do not exist or do not contain a matching +package configuration file. + +.. _`User Package Registry`: + +User Package Registry +--------------------- + +The User Package Registry is stored in a per-user location. +The :command:`export(PACKAGE)` command may be used to register a project +build tree in the user package registry. CMake currently provides no +interface to add install trees to the user package registry. Installers +must be manually taught to register their packages if desired. + +On Windows the user package registry is stored in the Windows registry +under a key in ``HKEY_CURRENT_USER``. + +A ``<package>`` may appear under registry key:: + + HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package> + +as a ``REG_SZ`` value, with arbitrary name, that specifies the directory +containing the package configuration file. + +On UNIX platforms the user package registry is stored in the user home +directory under ``~/.cmake/packages``. A ``<package>`` may appear under +the directory:: + + ~/.cmake/packages/<package> + +as a file, with arbitrary name, whose content specifies the directory +containing the package configuration file. + +.. _`System Package Registry`: + +System Package Registry +----------------------- + +The System Package Registry is stored in a system-wide location. +CMake currently provides no interface to add to the system package registry. +Installers must be manually taught to register their packages if desired. + +On Windows the system package registry is stored in the Windows registry +under a key in ``HKEY_LOCAL_MACHINE``. A ``<package>`` may appear under +registry key:: + + HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package> + +as a ``REG_SZ`` value, with arbitrary name, that specifies the directory +containing the package configuration file. + +There is no system package registry on non-Windows platforms. + +Package Registry Example +------------------------ + +A simple convention for naming package registry entries is to use content +hashes. They are deterministic and unlikely to collide +(:command:`export(PACKAGE)` uses this approach). +The name of an entry referencing a specific directory is simply the content +hash of the directory path itself. + +If a project arranges for package registry entries to exist, such as:: + + > reg query HKCU\Software\Kitware\CMake\Packages\MyPackage + HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage + 45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage + 7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build + +or:: + + $ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd + /home/me/work/lib/cmake/MyPackage + $ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07 + /home/me/work/MyPackage-build + +then the ``CMakeLists.txt`` code: + +.. code-block:: cmake + + find_package(MyPackage) + +will search the registered locations for package configuration files +(``MyPackageConfig.cmake``). The search order among package registry +entries for a single package is unspecified and the entry names +(hashes in this example) have no meaning. Registered locations may +contain package version files (``MyPackageConfigVersion.cmake``) to +tell :command:`find_package` whether a specific location is suitable +for the version requested. + +Package Registry Ownership +-------------------------- + +Package registry entries are individually owned by the project installations +that they reference. A package installer is responsible for adding its own +entry and the corresponding uninstaller is responsible for removing it. + +The :command:`export(PACKAGE)` command populates the user package registry +with the location of a project build tree. Build trees tend to be deleted by +developers and have no "uninstall" event that could trigger removal of their +entries. In order to keep the registries clean the :command:`find_package` +command automatically removes stale entries it encounters if it has sufficient +permissions. CMake provides no interface to remove an entry referencing an +existing build tree once :command:`export(PACKAGE)` has been invoked. +However, if the project removes its package configuration file from the build +tree then the entry referencing the location will be considered stale. diff --git a/Help/release/dev/Boost_NAMESPACE.rst b/Help/release/dev/Boost_NAMESPACE.rst new file mode 100644 index 0000000..434db29 --- /dev/null +++ b/Help/release/dev/Boost_NAMESPACE.rst @@ -0,0 +1,5 @@ +Boost_NAMESPACE +--------------- + +* The :module:`FindBoost` module learned a new ``Boost_NAMESPACE`` + option to change the ``boost`` prefix on library names. |