Difference between revisions of "CMake/Tutorials/Package Registry"

From KitwarePublic
Jump to navigationJump to search
(Remove leading space rectangles from preformatted blocks)
(Replace content with link to new CMake community wiki)
 
Line 1: Line 1:
==Introduction==
+
{{CMake/Template/Moved}}
  
CMake 2.8.5 and later provide two central locations to register packages that have been built or installed anywhere on a system:
+
This page has moved [https://gitlab.kitware.com/cmake/community/wikis/doc/tutorials/Package-Registry here].
 
 
* [[#User|User Package Registry]]
 
* [[#System|System Package Registry]]
 
 
 
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 [[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>).
 
 
 
The <code>find_package</code> 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==
 
 
 
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>.
 
A <code><package></code> may appear under registry key
 
 
 
<pre>
 
HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
 
</pre>
 
 
 
as a <code>REG_SZ</code> 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 <code>~/.cmake/packages</code>.
 
A <code><package></code> may appear under the directory
 
 
 
<pre>
 
~/.cmake/packages/<package>
 
</pre>
 
 
 
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 <code>HKEY_LOCAL_MACHINE</code>.
 
A <code><package></code> may appear under registry key
 
 
 
<pre>
 
HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
 
</pre>
 
 
 
as a <code>REG_SZ</code> 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 (<code>export(PACKAGE)</code> 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:
 
 
 
<pre>
 
> 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
 
</pre>
 
or
 
 
 
<pre>
 
$ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
 
/home/me/work/lib/cmake/MyPackage
 
$ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
 
/home/me/work/MyPackage-build
 
</pre>
 
 
 
then the <code>CMakeLists.txt</code> code
 
 
 
<pre>
 
find_package(MyPackage)
 
</pre>
 
 
 
will search the registered locations for package configuration files (<code>MyPackageConfig.cmake</code>).
 
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 (<code>MyPackageConfigVersion.cmake</code>) to tell <code>find_package</code> whether a specific location is suitable for the version requested.
 
 
 
==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 <code>export(PACKAGE)</code> 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 <code>find_package</code> 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 <code>export(PACKAGE)</code> 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.
 
 
 
{{CMake/Template/Footer}}
 

Latest revision as of 10:40, 30 April 2018


The CMake community Wiki has moved to the Kitware GitLab Instance.

This page has moved here.