|
|
| (2 intermediate revisions by one other user not shown) |
| 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
| |
| | |
| HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
| |
| | |
| 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
| |
| | |
| ~/.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 <code>HKEY_LOCAL_MACHINE</code>.
| |
| A <code><package></code> may appear under registry key
| |
| | |
| HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
| |
| | |
| 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:
| |
| | |
| > 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 <code>CMakeLists.txt</code> code
| |
| | |
| find_package(MyPackage)
| |
| | |
| 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}}
| |
