CMake/Tutorials/Package Registry: Difference between revisions
No edit summary |
|||
| Line 1: | Line 1: | ||
==Introduction== | ==Introduction== | ||
CMake | CMake 2.8.5 and later provide two central locations to register packages that have been built or installed anywhere on a system: | ||
* [[#User|User Package Registry]] | * [[#User|User Package Registry]] | ||
| Line 7: | Line 7: | ||
The registries are especially useful to help project find packages in non-standard install locations or directly in their own build trees. | The registries are especially useful to help project find packages in non-standard install locations or directly in their own build trees. | ||
A project | 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 [[CMake/Tutorials/Packaging#Package_Configuration_Files|package configuration file]] (<code><package>Config.cmake</code>) and optionally a [[CMake/Tutorials/Packaging#Package_Version_Files|package version file]] (<code><package>ConfigVersion.cmake</code>). | In either case the package should store at the registered location a [[CMake/Tutorials/Packaging#Package_Configuration_Files|package configuration file]] (<code><package>Config.cmake</code>) and optionally a [[CMake/Tutorials/Packaging#Package_Version_Files|package version file]] (<code><package>ConfigVersion.cmake</code>). | ||
| Line 17: | Line 16: | ||
The ''User Package Registry'' is stored in a per-user location. | The ''User Package Registry'' is stored in a per-user location. | ||
The <code>export(PACKAGE)</code> 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 <code>HKEY_CURRENT_USER</code>. | On Windows the user package registry is stored in the Windows registry under a key in <code>HKEY_CURRENT_USER</code>. | ||
| Line 35: | Line 37: | ||
The ''System Package Registry'' is stored in a system-wide location. | 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 <code>HKEY_LOCAL_MACHINE</code>. | On Windows the system package registry is stored in the Windows registry under a key in <code>HKEY_LOCAL_MACHINE</code>. | ||
Revision as of 14:27, 15 February 2012
Introduction
CMake 2.8.5 and later provide two central locations to register packages that have been built or installed anywhere on a system:
The registries are especially useful to help project 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 find_package command searches the package registries as 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
The User Package Registry is stored in a per-user location.
The 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
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.
Example
A simple convention for naming package registry entries is to use content hashes.
They are deterministic and unlikely to collide (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 a package registry entry 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
or
$ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd /home/me/work/lib/cmake/MyPackage
then the CMakeLists.txt code
find_package(MyPackage)
will search the registered location.
