1CMAKE-PACKAGES(7)                    CMake                   CMAKE-PACKAGES(7)
2
3
4

NAME

6       cmake-packages - CMake Packages Reference
7

INTRODUCTION

9       Packages  provide  dependency  information to CMake based buildsystems.
10       Packages are found with the  find_package()  command.   The  result  of
11       using  find_package  is  either  a set of IMPORTED targets, or a set of
12       variables corresponding to build-relevant information.
13

USING PACKAGES

15       CMake provides direct support for two forms  of  packages,  Config-file
16       Packages  and  Find-module  Packages.   Indirect support for pkg-config
17       packages is also provided via the FindPkgConfig module.  In all  cases,
18       the basic form of find_package() calls is the same:
19
20          find_package(Qt4 4.7.0 REQUIRED) # CMake provides a Qt4 find-module
21          find_package(Qt5Core 5.1.0 REQUIRED) # Qt provides a Qt5 package config file.
22          find_package(LibXml2 REQUIRED) # Use pkg-config via the LibXml2 find-module
23
24       In  cases  where  it is known that a package configuration file is pro‐
25       vided by upstream, and only that should be used, the CONFIG keyword may
26       be passed to find_package():
27
28          find_package(Qt5Core 5.1.0 CONFIG REQUIRED)
29          find_package(Qt5Gui 5.1.0 CONFIG)
30
31       Similarly, the MODULE keyword says to use only a find-module:
32
33          find_package(Qt4 4.7.0 MODULE REQUIRED)
34
35       Specifying  the  type  of package explicitly improves the error message
36       shown to the user if it is not found.
37
38       Both types of packages also support specifying components of a package,
39       either after the REQUIRED keyword:
40
41          find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql)
42
43       or as a separate COMPONENTS list:
44
45          find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql)
46
47       or as a separate OPTIONAL_COMPONENTS list:
48
49          find_package(Qt5 5.1.0 COMPONENTS Widgets
50                                 OPTIONAL_COMPONENTS Xml Sql
51          )
52
53       Handling  of COMPONENTS and OPTIONAL_COMPONENTS is defined by the pack‐
54       age.
55
56       By setting  the  CMAKE_DISABLE_FIND_PACKAGE_<PackageName>  variable  to
57       TRUE,  the PackageName package will not be searched, and will always be
58       NOTFOUND.
59
60   Config-file Packages
61       A config-file package is a set of files provided by upstreams for down‐
62       streams  to  use.  CMake  searches in a number of locations for package
63       configuration files, as described in the find_package()  documentation.
64       The  most  simple  way for a CMake user to tell cmake(1) to search in a
65       non-standard prefix for a package is to set the CMAKE_PREFIX_PATH cache
66       variable.
67
68       Config-file packages are provided by upstream vendors as part of devel‐
69       opment packages, that is, they belong with the  header  files  and  any
70       other files provided to assist downstreams in using the package.
71
72       A  set  of  variables which provide package status information are also
73       set  automatically  when  using  a  config-file  package.   The  <Pack‐
74       age>_FOUND  variable  is set to true or false, depending on whether the
75       package was found.  The <Package>_DIR cache  variable  is  set  to  the
76       location of the package configuration file.
77
78   Find-module Packages
79       A  find  module  is a file with a set of rules for finding the required
80       pieces of a dependency, primarily header files  and  libraries.   Typi‐
81       cally,  a  find  module  is  needed when the upstream is not built with
82       CMake, or is not CMake-aware enough to otherwise provide a package con‐
83       figuration  file.   Unlike  a  package  configuration  file,  it is not
84       shipped with upstream, but is used by downstream to find the  files  by
85       guessing locations of files with platform-specific hints.
86
87       Unlike  the case of an upstream-provided package configuration file, no
88       single point of reference identifies the package as being found, so the
89       <Package>_FOUND variable is not automatically set by the find_package()
90       command.  It can still be expected to be set by convention however  and
91       should  be set by the author of the Find-module.  Similarly there is no
92       <Package>_DIR variable, but each of the artifacts such as library loca‐
93       tions and header file locations provide a separate cache variable.
94
95       See  the  cmake-developer(7) manual for more information about creating
96       Find-module files.
97

PACKAGE LAYOUT

99       A config-file package consists of  a  Package  Configuration  File  and
100       optionally  a  Package Version File provided with the project distribu‐
101       tion.
102
103   Package Configuration File
104       Consider a project Foo that installs the following files:
105
106          <prefix>/include/foo-1.2/foo.h
107          <prefix>/lib/foo-1.2/libfoo.a
108
109       It may also provide a CMake package configuration file:
110
111          <prefix>/lib/cmake/foo-1.2/FooConfig.cmake
112
113       with content defining IMPORTED targets, or defining variables, such as:
114
115          # ...
116          # (compute PREFIX relative to file location)
117          # ...
118          set(Foo_INCLUDE_DIRS ${PREFIX}/include/foo-1.2)
119          set(Foo_LIBRARIES ${PREFIX}/lib/foo-1.2/libfoo.a)
120
121       If another project wishes to use Foo it need only to locate the FooCon‐
122       fig.cmake  file  and  load it to get all the information it needs about
123       package content locations.  Since the  package  configuration  file  is
124       provided  by  the  package  installation  it already knows all the file
125       locations.
126
127       The find_package() command may be used to search for the  package  con‐
128       figuration  file.   This  command constructs a set of installation pre‐
129       fixes and searches under each prefix in several locations.   Given  the
130       name  Foo,  it  looks  for  a  file  called FooConfig.cmake or foo-con‐
131       fig.cmake.  The full set of locations is specified  in  the  find_pack‐
132       age() command documentation. One place it looks is:
133
134          <prefix>/lib/cmake/Foo*/
135
136       where  Foo*  is a case-insensitive globbing expression.  In our example
137       the globbing expression will match <prefix>/lib/cmake/foo-1.2  and  the
138       package configuration file will be found.
139
140       Once  found,  a  package configuration file is immediately loaded.  It,
141       together with a package version file, contains all the information  the
142       project needs to use the package.
143
144   Package Version File
145       When the find_package() command finds a candidate package configuration
146       file it looks next to it for a version file. The version file is loaded
147       to test whether the package version is an acceptable match for the ver‐
148       sion requested.  If the version file claims compatibility the  configu‐
149       ration file is accepted.  Otherwise it is ignored.
150
151       The  name  of  the  package version file must match that of the package
152       configuration file but has either -version or Version appended  to  the
153       name before the .cmake extension.  For example, the files:
154
155          <prefix>/lib/cmake/foo-1.3/foo-config.cmake
156          <prefix>/lib/cmake/foo-1.3/foo-config-version.cmake
157
158       and:
159
160          <prefix>/lib/cmake/bar-4.2/BarConfig.cmake
161          <prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake
162
163       are each pairs of package configuration files and corresponding package
164       version files.
165
166       When the find_package() command loads a version file it first sets  the
167       following variables:
168
169       PACKAGE_FIND_NAME
170              The <package> name
171
172       PACKAGE_FIND_VERSION
173              Full requested version string
174
175       PACKAGE_FIND_VERSION_MAJOR
176              Major version if requested, else 0
177
178       PACKAGE_FIND_VERSION_MINOR
179              Minor version if requested, else 0
180
181       PACKAGE_FIND_VERSION_PATCH
182              Patch version if requested, else 0
183
184       PACKAGE_FIND_VERSION_TWEAK
185              Tweak version if requested, else 0
186
187       PACKAGE_FIND_VERSION_COUNT
188              Number of version components, 0 to 4
189
190       The  version  file must use these variables to check whether it is com‐
191       patible or an exact match for the requested version and set the follow‐
192       ing variables with results:
193
194       PACKAGE_VERSION
195              Full provided version string
196
197       PACKAGE_VERSION_EXACT
198              True if version is exact match
199
200       PACKAGE_VERSION_COMPATIBLE
201              True if version is compatible
202
203       PACKAGE_VERSION_UNSUITABLE
204              True if unsuitable as any version
205
206       Version  files are loaded in a nested scope so they are free to set any
207       variables they wish as part of their computation. The find_package com‐
208       mand wipes out the scope when the version file has completed and it has
209       checked the output variables. When the version file  claims  to  be  an
210       acceptable  match  for  the  requested version the find_package command
211       sets the following variables for use by the project:
212
213       <package>_VERSION
214              Full provided version string
215
216       <package>_VERSION_MAJOR
217              Major version if provided, else 0
218
219       <package>_VERSION_MINOR
220              Minor version if provided, else 0
221
222       <package>_VERSION_PATCH
223              Patch version if provided, else 0
224
225       <package>_VERSION_TWEAK
226              Tweak version if provided, else 0
227
228       <package>_VERSION_COUNT
229              Number of version components, 0 to 4
230
231       The variables report the version  of  the  package  that  was  actually
232       found.   The <package> part of their name matches the argument given to
233       the find_package() command.
234

CREATING PACKAGES

236       Usually, the upstream depends on CMake itself and can  use  some  CMake
237       facilities  for  creating the package files. Consider an upstream which
238       provides a single shared library:
239
240          project(UpstreamLib)
241
242          set(CMAKE_INCLUDE_CURRENT_DIR ON)
243          set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)
244
245          set(Upstream_VERSION 3.4.1)
246
247          include(GenerateExportHeader)
248
249          add_library(ClimbingStats SHARED climbingstats.cpp)
250          generate_export_header(ClimbingStats)
251          set_property(TARGET ClimbingStats PROPERTY VERSION ${Upstream_VERSION})
252          set_property(TARGET ClimbingStats PROPERTY SOVERSION 3)
253          set_property(TARGET ClimbingStats PROPERTY
254            INTERFACE_ClimbingStats_MAJOR_VERSION 3)
255          set_property(TARGET ClimbingStats APPEND PROPERTY
256            COMPATIBLE_INTERFACE_STRING ClimbingStats_MAJOR_VERSION
257          )
258
259          install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets
260            LIBRARY DESTINATION lib
261            ARCHIVE DESTINATION lib
262            RUNTIME DESTINATION bin
263            INCLUDES DESTINATION include
264          )
265          install(
266            FILES
267              climbingstats.h
268              "${CMAKE_CURRENT_BINARY_DIR}/climbingstats_export.h"
269            DESTINATION
270              include
271            COMPONENT
272              Devel
273          )
274
275          include(CMakePackageConfigHelpers)
276          write_basic_package_version_file(
277            "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
278            VERSION ${Upstream_VERSION}
279            COMPATIBILITY AnyNewerVersion
280          )
281
282          export(EXPORT ClimbingStatsTargets
283            FILE "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsTargets.cmake"
284            NAMESPACE Upstream::
285          )
286          configure_file(cmake/ClimbingStatsConfig.cmake
287            "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfig.cmake"
288            COPYONLY
289          )
290
291          set(ConfigPackageLocation lib/cmake/ClimbingStats)
292          install(EXPORT ClimbingStatsTargets
293            FILE
294              ClimbingStatsTargets.cmake
295            NAMESPACE
296              Upstream::
297            DESTINATION
298              ${ConfigPackageLocation}
299          )
300          install(
301            FILES
302              cmake/ClimbingStatsConfig.cmake
303              "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
304            DESTINATION
305              ${ConfigPackageLocation}
306            COMPONENT
307              Devel
308          )
309
310       The CMakePackageConfigHelpers module provides a macro  for  creating  a
311       simple  ConfigVersion.cmake  file.   This  file sets the version of the
312       package.  It is read by CMake when find_package() is called  to  deter‐
313       mine the compatibility with the requested version, and to set some ver‐
314       sion-specific  variables  <Package>_VERSION,   <Package>_VERSION_MAJOR,
315       <Package>_VERSION_MINOR  etc.   The  install(EXPORT) command is used to
316       export the targets in the ClimbingStatsTargets export-set, defined pre‐
317       viously  by  the  install(TARGETS)  command. This command generates the
318       ClimbingStatsTargets.cmake file to contain IMPORTED  targets,  suitable
319       for  use  by downstreams and arranges to install it to lib/cmake/Climb‐
320       ingStats.   The  generated   ClimbingStatsConfigVersion.cmake   and   a
321       cmake/ClimbingStatsConfig.cmake  are  installed  to  the same location,
322       completing the package.
323
324       The generated IMPORTED  targets  have  appropriate  properties  set  to
325       define their usage requirements, such as INTERFACE_INCLUDE_DIRECTORIES,
326       INTERFACE_COMPILE_DEFINITIONS and other  relevant  built-in  INTERFACE_
327       properties.  The INTERFACE variant of user-defined properties listed in
328       COMPATIBLE_INTERFACE_STRING and other Compatible  Interface  Properties
329       are  also  propagated  to the generated IMPORTED targets.  In the above
330       case, ClimbingStats_MAJOR_VERSION is defined as a string which must  be
331       compatible  among  the  dependencies  of any depender.  By setting this
332       custom defined user property in this version and in the next version of
333       ClimbingStats,  cmake(1) will issue a diagnostic if there is an attempt
334       to use version 3 together with  version  4.   Packages  can  choose  to
335       employ  such  a  pattern if different major versions of the package are
336       designed to be incompatible.
337
338       A NAMESPACE with double-colons is specified when exporting the  targets
339       for  installation.  This convention of double-colons gives CMake a hint
340       that the name is an IMPORTED target when it is used by downstreams with
341       the target_link_libraries() command.  This way, CMake can issue a diag‐
342       nostic if the package providing it has not yet been found.
343
344       In this case, when using install(TARGETS) the INCLUDES DESTINATION  was
345       specified.   This  causes  the  IMPORTED  targets  to have their INTER‐
346       FACE_INCLUDE_DIRECTORIES populated with the include  directory  in  the
347       CMAKE_INSTALL_PREFIX.   When the IMPORTED target is used by downstream,
348       it automatically consumes the entries from that property.
349
350   Creating a Package Configuration File
351       In this case, the ClimbingStatsConfig.cmake file could be as simple as:
352
353          include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
354
355       As this allows downstreams to use the IMPORTED targets.  If any  macros
356       should  be  provided  by the ClimbingStats package, they should be in a
357       separate file which is installed to the same  location  as  the  Climb‐
358       ingStatsConfig.cmake file, and included from there.
359
360       This can also be extended to cover dependencies:
361
362          # ...
363          add_library(ClimbingStats SHARED climbingstats.cpp)
364          generate_export_header(ClimbingStats)
365
366          find_package(Stats 2.6.4 REQUIRED)
367          target_link_libraries(ClimbingStats PUBLIC Stats::Types)
368
369       As  the  Stats::Types  target  is a PUBLIC dependency of ClimbingStats,
370       downstreams  must  also  find  the  Stats  package  and  link  to   the
371       Stats::Types  library.  The Stats package should be found in the Climb‐
372       ingStatsConfig.cmake file to ensure this.   The  find_dependency  macro
373       from  the  CMakeFindDependencyMacro  helps  with  this  by  propagating
374       whether the package is REQUIRED, or QUIET etc.  All REQUIRED  dependen‐
375       cies of a package should be found in the Config.cmake file:
376
377          include(CMakeFindDependencyMacro)
378          find_dependency(Stats 2.6.4)
379
380          include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
381          include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
382
383       The find_dependency macro also sets ClimbingStats_FOUND to False if the
384       dependency is not found, along with a diagnostic that the ClimbingStats
385       package can not be used without the Stats package.
386
387       If  COMPONENTS  are  specified when the downstream uses find_package(),
388       they are listed in the <Package>_FIND_COMPONENTS variable. If a partic‐
389       ular component is non-optional, then the <Package>_FIND_REQUIRED_<comp>
390       will be true. This can be tested with logic in the  package  configura‐
391       tion file:
392
393          include(CMakeFindDependencyMacro)
394          find_dependency(Stats 2.6.4)
395
396          include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
397          include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
398
399          set(_supported_components Plot Table)
400
401          foreach(_comp ${ClimbingStats_FIND_COMPONENTS})
402            if (NOT ";${_supported_components};" MATCHES _comp)
403              set(ClimbingStats_FOUND False)
404              set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
405            endif()
406            include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake")
407          endforeach()
408
409       Here,  the  ClimbingStats_NOT_FOUND_MESSAGE  is set to a diagnosis that
410       the package could not be found because an invalid component was  speci‐
411       fied.   This  message variable can be set for any case where the _FOUND
412       variable is set to False, and will be displayed to the user.
413
414   Creating a Package Configuration File for the Build Tree
415       The export(EXPORT) command creates an IMPORTED targets definition  file
416       which  is specific to the build-tree, and is not relocatable.  This can
417       similarly be used with a suitable package configuration file and  pack‐
418       age  version  file  to define a package for the build tree which may be
419       used without installation.  Consumers of  the  build  tree  can  simply
420       ensure  that the CMAKE_PREFIX_PATH contains the build directory, or set
421       the ClimbingStats_DIR to <build_dir>/ClimbingStats in the cache.
422
423   Creating Relocatable Packages
424       A relocatable package must not reference absolute paths of files on the
425       machine  where the package is built that will not exist on the machines
426       where the package may be installed.
427
428       Packages created by install(EXPORT) are  designed  to  be  relocatable,
429       using  paths  relative  to  the  location  of the package itself.  When
430       defining the interface of a target for EXPORT, keep in  mind  that  the
431       include  directories  should  be  specified as relative paths which are
432       relative to the CMAKE_INSTALL_PREFIX:
433
434          target_include_directories(tgt INTERFACE
435            # Wrong, not relocatable:
436            $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
437          )
438
439          target_include_directories(tgt INTERFACE
440            # Ok, relocatable:
441            $<INSTALL_INTERFACE:include/TgtName>
442          )
443
444       The $<INSTALL_PREFIX> generator expression may be used as a placeholder
445       for  the install prefix without resulting in a non-relocatable package.
446       This is necessary if complex generator expressions are used:
447
448          target_include_directories(tgt INTERFACE
449            # Ok, relocatable:
450            $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
451          )
452
453       This also applies to paths referencing external  dependencies.   It  is
454       not  advisable to populate any properties which may contain paths, such
455       as  INTERFACE_INCLUDE_DIRECTORIES  and  INTERFACE_LINK_LIBRARIES,  with
456       paths  relevant  to  dependencies.  For example, this code may not work
457       well for a relocatable package:
458
459          target_link_libraries(ClimbingStats INTERFACE
460            ${Foo_LIBRARIES} ${Bar_LIBRARIES}
461            )
462          target_include_directories(ClimbingStats INTERFACE
463            "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
464            )
465
466       The referenced variables may contain the absolute  paths  to  libraries
467       and  include  directories  as found on the machine the package was made
468       on.  This would create a package with hard-coded paths to  dependencies
469       and not suitable for relocation.
470
471       Ideally  such  dependencies  should  be used through their own IMPORTED
472       targets that have their own  IMPORTED_LOCATION  and  usage  requirement
473       properties  such  as  INTERFACE_INCLUDE_DIRECTORIES populated appropri‐
474       ately.   Those  imported  targets  may  then  be  used  with  the  tar‐
475       get_link_libraries() command for ClimbingStats:
476
477          target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)
478
479       With  this  approach  the  package references its external dependencies
480       only through the names of IMPORTED targets.  When a consumer  uses  the
481       installed package, the consumer will run the appropriate find_package()
482       commands (via the find_dependency macro described above)  to  find  the
483       dependencies  and  populate the imported targets with appropriate paths
484       on their own machine.
485
486       Unfortunately many modules  shipped  with  CMake  do  not  yet  provide
487       IMPORTED  targets  because  their  development pre-dated this approach.
488       This may improve incrementally over time.  Workarounds to create  relo‐
489       catable packages using such modules include:
490
491       · When  building  the  package, specify each Foo_LIBRARY cache entry as
492         just a library name, e.g. -DFoo_LIBRARY=foo.  This tells  the  corre‐
493         sponding  find  module to populate the Foo_LIBRARIES with just foo to
494         ask the linker to search for the library  instead  of  hard-coding  a
495         path.
496
497       · Or,  after  installing  the  package  content but before creating the
498         package installation binary for redistribution, manually replace  the
499         absolute paths with placeholders for substitution by the installation
500         tool when the package is installed.
501

PACKAGE REGISTRY

503       CMake provides two central locations to  register  packages  that  have
504       been built or installed anywhere on a system:
505
506       · User Package Registry
507
508       · System Package Registry
509
510       The  registries are especially useful to help projects find packages in
511       non-standard install locations or directly in their own build trees.  A
512       project  may populate either the user or system registry (using its own
513       means, see below) to refer to its location.  In either case the package
514       should  store  at  the registered location a Package Configuration File
515       (<package>Config.cmake) and optionally a Package Version  File  (<pack‐
516       age>ConfigVersion.cmake).
517
518       The  find_package()  command searches the two package registries as two
519       of the search steps specified in its documentation.  If it  has  suffi‐
520       cient  permissions  it also removes stale package registry entries that
521       refer to directories that do not exist or do  not  contain  a  matching
522       package configuration file.
523
524   User Package Registry
525       The  User  Package  Registry  is  stored  in  a per-user location.  The
526       export(PACKAGE) command may be used to register a project build tree in
527       the  user  package  registry.  CMake currently provides no interface to
528       add install trees to the user package  registry.   Installers  must  be
529       manually taught to register their packages if desired.
530
531       On  Windows the user package registry is stored in the Windows registry
532       under a key in HKEY_CURRENT_USER.
533
534       A <package> may appear under registry key:
535
536          HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<package>
537
538       as a REG_SZ value, with arbitrary name, that  specifies  the  directory
539       containing the package configuration file.
540
541       On  UNIX platforms the user package registry is stored in the user home
542       directory under ~/.cmake/packages.  A <package> may  appear  under  the
543       directory:
544
545          ~/.cmake/packages/<package>
546
547       as  a  file, with arbitrary name, whose content specifies the directory
548       containing the package configuration file.
549
550   System Package Registry
551       The System Package Registry is stored in a system-wide location.  CMake
552       currently  provides no interface to add to the system package registry.
553       Installers must be  manually  taught  to  register  their  packages  if
554       desired.
555
556       On  Windows  the  system package registry is stored in the Windows reg‐
557       istry under a key in HKEY_LOCAL_MACHINE.  A <package> may appear  under
558       registry key:
559
560          HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<package>
561
562       as  a  REG_SZ  value, with arbitrary name, that specifies the directory
563       containing the package configuration file.
564
565       There is no system package registry on non-Windows platforms.
566
567   Disabling the Package Registry
568       In some cases using the Package  Registries  is  not  desirable.  CMake
569       allows one to disable them using the following variables:
570
571          · CMAKE_EXPORT_NO_PACKAGE_REGISTRY disables the export(PACKAGE) com‐
572            mand.
573
574          · CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY disables the  User  Package
575            Registry in all the find_package() calls.
576
577          · CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY  disables the System
578            Package Registry in all the find_package() calls.
579
580   Package Registry Example
581       A simple convention for naming package registry entries is to use  con‐
582       tent   hashes.    They   are  deterministic  and  unlikely  to  collide
583       (export(PACKAGE) uses this approach).  The name of an entry referencing
584       a  specific  directory is simply the content hash of the directory path
585       itself.
586
587       If a project arranges for package registry entries to exist, such as:
588
589          > reg query HKCU\Software\Kitware\CMake\Packages\MyPackage
590          HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage
591           45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage
592           7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build
593
594       or:
595
596          $ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
597          /home/me/work/lib/cmake/MyPackage
598          $ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
599          /home/me/work/MyPackage-build
600
601       then the CMakeLists.txt code:
602
603          find_package(MyPackage)
604
605       will search the registered locations for  package  configuration  files
606       (MyPackageConfig.cmake).   The  search  order  among  package  registry
607       entries for a single package is unspecified and the entry names (hashes
608       in  this  example)  have  no meaning.  Registered locations may contain
609       package version files (MyPackageConfigVersion.cmake) to tell find_pack‐
610       age()   whether  a  specific  location  is  suitable  for  the  version
611       requested.
612
613   Package Registry Ownership
614       Package registry entries are individually owned by the project  instal‐
615       lations  that  they  reference.  A package installer is responsible for
616       adding its own entry and the corresponding uninstaller  is  responsible
617       for removing it.
618
619       The  export(PACKAGE)  command  populates the user package registry with
620       the location of a project build tree.  Build trees tend to  be  deleted
621       by  developers and have no “uninstall” event that could trigger removal
622       of their entries.  In order to keep the registries clean the find_pack‐
623       age()  command  automatically removes stale entries it encounters if it
624       has sufficient permissions.  CMake provides no interface to  remove  an
625       entry  referencing an existing build tree once export(PACKAGE) has been
626       invoked.  However, if the project  removes  its  package  configuration
627       file  from  the build tree then the entry referencing the location will
628       be considered stale.
629
631       2000-2018 Kitware, Inc. and Contributors
632
633
634
635
6363.11.4                           May 13, 2019                CMAKE-PACKAGES(7)
Impressum