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
58       be 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  <Package‐
74       Name>_FOUND  variable is set to true or false, depending on whether the
75       package was found.  The <PackageName>_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       <PackageName>_FOUND variable is not automatically set by the find_pack‐
90       age() command.  It can still be expected to be set by  convention  how‐
91       ever  and  should  be  set by the author of the Find-module.  Similarly
92       there is no <PackageName>_DIR variable, but each of the artifacts  such
93       as library locations and header file locations provide a separate cache
94       variable.
95
96       See the cmake-developer(7) manual for more information  about  creating
97       Find-module files.
98

PACKAGE LAYOUT

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

CREATING PACKAGES

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

PACKAGE REGISTRY

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