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  us‐
11       ing  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.          Likewise,          setting           the
59       CMAKE_REQUIRE_FIND_PACKAGE_<PackageName>  to TRUE will make the package
60       REQUIRED.
61
62   Config-file Packages
63       A config-file package is a set of files provided by upstreams for down‐
64       streams  to  use.  CMake  searches in a number of locations for package
65       configuration files, as described in the find_package()  documentation.
66       The  most  simple  way for a CMake user to tell cmake(1) to search in a
67       non-standard prefix for a package is to set the CMAKE_PREFIX_PATH cache
68       variable.
69
70       Config-file packages are provided by upstream vendors as part of devel‐
71       opment packages, that is, they belong with the  header  files  and  any
72       other files provided to assist downstreams in using the package.
73
74       A  set  of  variables which provide package status information are also
75       set automatically when using  a  config-file  package.   The  <Package‐
76       Name>_FOUND  variable is set to true or false, depending on whether the
77       package was found.  The <PackageName>_DIR cache variable is set to  the
78       location of the package configuration file.
79
80   Find-module Packages
81       A  find  module  is a file with a set of rules for finding the required
82       pieces of a dependency, primarily header files  and  libraries.   Typi‐
83       cally,  a  find  module  is  needed when the upstream is not built with
84       CMake, or is not CMake-aware enough to otherwise provide a package con‐
85       figuration  file.   Unlike  a  package  configuration  file,  it is not
86       shipped with upstream, but is used by downstream to find the  files  by
87       guessing locations of files with platform-specific hints.
88
89       Unlike  the case of an upstream-provided package configuration file, no
90       single point of reference identifies the package as being found, so the
91       <PackageName>_FOUND   variable   is   not   automatically  set  by  the
92       find_package() command.  It can still be expected to be set by  conven‐
93       tion however and should be set by the author of the Find-module.  Simi‐
94       larly there is no <PackageName>_DIR variable, but each of the artifacts
95       such  as library locations and header file locations provide a separate
96       cache variable.
97
98       See the cmake-developer(7) manual for more information  about  creating
99       Find-module files.
100

PACKAGE LAYOUT

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

CREATING PACKAGES

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

PACKAGE REGISTRY

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