1CMAKE-PACKAGES(7) CMake CMAKE-PACKAGES(7)
2
6 cmake-packages - CMake Packages Reference
7
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
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 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 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 find_package(Qt5Core 5.1.0 CONFIG REQUIRED)
29 find_package(Qt5Gui 5.1.0 CONFIG)
30 Similarly, the MODULE keyword says to use only a find-module:
32 find_package(Qt4 4.7.0 MODULE REQUIRED)
34 Specifying the type of package explicitly improves the error message
36 shown to the user if it is not found.
37 Both types of packages also support specifying components of a package,
39 either after the REQUIRED keyword:
40 find_package(Qt5 5.1.0 CONFIG REQUIRED Widgets Xml Sql)
42 or as a separate COMPONENTS list:
44 find_package(Qt5 5.1.0 COMPONENTS Widgets Xml Sql)
46 or as a separate OPTIONAL_COMPONENTS list:
48 find_package(Qt5 5.1.0 COMPONENTS Widgets
50 OPTIONAL_COMPONENTS Xml Sql
51 )
52 Handling of COMPONENTS and OPTIONAL_COMPONENTS is defined by the pack‐
54 age.
55 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 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 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 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 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 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 See the cmake-developer(7) manual for more information about creating
97 Find-module files.
98
100 A config-file package consists of a Package Configuration File and op‐
101 tionally a Package Version File provided with the project distribution.
102 Package Configuration File
104 Consider a project Foo that installs the following files:
105 <prefix>/include/foo-1.2/foo.h
107 <prefix>/lib/foo-1.2/libfoo.a
108 It may also provide a CMake package configuration file:
110 <prefix>/lib/cmake/foo-1.2/FooConfig.cmake
112 with content defining IMPORTED targets, or defining variables, such as:
114 # ...
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 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 lo‐
125 cations.
126 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 <prefix>/lib/cmake/Foo*/
135 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 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 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 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 <prefix>/lib/cmake/foo-1.3/foo-config.cmake
156 <prefix>/lib/cmake/foo-1.3/foo-config-version.cmake
157 and:
159 <prefix>/lib/cmake/bar-4.2/BarConfig.cmake
161 <prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake
162 are each pairs of package configuration files and corresponding package
164 version files.
165 When the find_package() command loads a version file it first sets the
167 following variables:
168 PACKAGE_FIND_NAME
170 The <PackageName>
171 PACKAGE_FIND_VERSION
173 Full requested version string
174 PACKAGE_FIND_VERSION_MAJOR
176 Major version if requested, else 0
177 PACKAGE_FIND_VERSION_MINOR
179 Minor version if requested, else 0
180 PACKAGE_FIND_VERSION_PATCH
182 Patch version if requested, else 0
183 PACKAGE_FIND_VERSION_TWEAK
185 Tweak version if requested, else 0
186 PACKAGE_FIND_VERSION_COUNT
188 Number of version components, 0 to 4
189 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 PACKAGE_VERSION
195 Full provided version string
196 PACKAGE_VERSION_EXACT
198 True if version is exact match
199 PACKAGE_VERSION_COMPATIBLE
201 True if version is compatible
202 PACKAGE_VERSION_UNSUITABLE
204 True if unsuitable as any version
205 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 ac‐
210 ceptable match for the requested version the find_package command sets
211 the following variables for use by the project:
212 <PackageName>_VERSION
214 Full provided version string
215 <PackageName>_VERSION_MAJOR
217 Major version if provided, else 0
218 <PackageName>_VERSION_MINOR
220 Minor version if provided, else 0
221 <PackageName>_VERSION_PATCH
223 Patch version if provided, else 0
224 <PackageName>_VERSION_TWEAK
226 Tweak version if provided, else 0
227 <PackageName>_VERSION_COUNT
229 Number of version components, 0 to 4
230 The variables report the version of the package that was actually
232 found. The <PackageName> part of their name matches the argument given
233 to the find_package() command.
234
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 project(UpstreamLib)
241 set(CMAKE_INCLUDE_CURRENT_DIR ON)
243 set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)
244 set(Upstream_VERSION 3.4.1)
246 include(GenerateExportHeader)
248 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 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 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 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 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 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 <PackageName>_VERSION, <PackageName>_VER‐
315 SION_MAJOR, <PackageName>_VERSION_MINOR etc. The install(EXPORT) com‐
316 mand is used to export the targets in the ClimbingStatsTargets ex‐
317 port-set, defined previously by the install(TARGETS) command. This com‐
318 mand generates the ClimbingStatsTargets.cmake file to contain IMPORTED
319 targets, suitable for use by downstreams and arranges to install it to
320 lib/cmake/ClimbingStats. The generated ClimbingStatsConfigVer‐
321 sion.cmake and a cmake/ClimbingStatsConfig.cmake are installed to the
322 same location, completing the package.
323 The generated IMPORTED targets have appropriate properties set to de‐
325 fine 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 em‐
335 ploy such a pattern if different major versions of the package are de‐
336 signed to be incompatible.
337 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 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 Creating a Package Configuration File
351 In this case, the ClimbingStatsConfig.cmake file could be as simple as:
352 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
354 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 This can also be extended to cover dependencies:
361 # ...
363 add_library(ClimbingStats SHARED climbingstats.cpp)
364 generate_export_header(ClimbingStats)
365 find_package(Stats 2.6.4 REQUIRED)
367 target_link_libraries(ClimbingStats PUBLIC Stats::Types)
368 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 include(CMakeFindDependencyMacro)
378 find_dependency(Stats 2.6.4)
379 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
381 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
382 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 If COMPONENTS are specified when the downstream uses find_package(),
388 they are listed in the <PackageName>_FIND_COMPONENTS variable. If a
389 particular component is non-optional, then the <PackageName>_FIND_RE‐
390 QUIRED_<comp> will be true. This can be tested with logic in the pack‐
391 age configuration file:
392 include(CMakeFindDependencyMacro)
394 find_dependency(Stats 2.6.4)
395 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
397 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
398 set(_supported_components Plot Table)
400 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 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 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 en‐
420 sure that the CMAKE_PREFIX_PATH contains the build directory, or set
421 the ClimbingStats_DIR to <build_dir>/ClimbingStats in the cache.
422 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 Packages created by install(EXPORT) are designed to be relocatable, us‐
429 ing paths relative to the location of the package itself. When defin‐
430 ing the interface of a target for EXPORT, keep in mind that the include
431 directories should be specified as relative paths which are relative to
432 the CMAKE_INSTALL_PREFIX:
433 target_include_directories(tgt INTERFACE
435 # Wrong, not relocatable:
436 $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
437 )
438 target_include_directories(tgt INTERFACE
440 # Ok, relocatable:
441 $<INSTALL_INTERFACE:include/TgtName>
442 )
443 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 target_include_directories(tgt INTERFACE
449 # Ok, relocatable:
450 $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
451 )
452 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 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 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 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 target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)
478 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 Unfortunately many modules shipped with CMake do not yet provide IM‐
487 PORTED targets because their development pre-dated this approach. This
488 may improve incrementally over time. Workarounds to create relocatable
489 packages using such modules include:
490 • 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 • 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
503 CMake provides two central locations to register packages that have
504 been built or installed anywhere on a system:
505 • User Package Registry
507 • System Package Registry
509 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 (<PackageName>Config.cmake) and optionally a Package Version File
516 (<PackageName>ConfigVersion.cmake).
517 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 User Package Registry
525 The User Package Registry is stored in a per-user location. The ex‐
526 port(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 On Windows the user package registry is stored in the Windows registry
532 under a key in HKEY_CURRENT_USER.
533 A <PackageName> may appear under registry key:
535 HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName>
537 as a REG_SZ value, with arbitrary name, that specifies the directory
539 containing the package configuration file.
540 On UNIX platforms the user package registry is stored in the user home
542 directory under ~/.cmake/packages. A <PackageName> may appear under
543 the directory:
544 ~/.cmake/packages/<PackageName>
546 as a file, with arbitrary name, whose content specifies the directory
548 containing the package configuration file.
549 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 de‐
554 sired.
555 On Windows the system package registry is stored in the Windows reg‐
557 istry under a key in HKEY_LOCAL_MACHINE. A <PackageName> may appear
558 under registry key:
559 HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>
561 as a REG_SZ value, with arbitrary name, that specifies the directory
563 containing the package configuration file.
564 There is no system package registry on non-Windows platforms.
566 Disabling the Package Registry
568 In some cases using the Package Registries is not desirable. CMake al‐
569 lows one to disable them using the following variables:
570 • The export(PACKAGE) command does not populate the user package reg‐
572 istry when CMP0090 is set to NEW unless the CMAKE_EXPORT_PACKAGE_REG‐
573 ISTRY variable explicitly enables it. When CMP0090 is not set to NEW
574 then export(PACKAGE) populates the user package registry unless the
575 CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable explicitly disables it.
576 • CMAKE_FIND_USE_PACKAGE_REGISTRY disables the User Package Registry in
578 all the find_package() calls when set to FALSE.
579 • Deprecated CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY disables the User
581 Package Registry in all the find_package() calls when set to TRUE.
582 This variable is ignored when CMAKE_FIND_USE_PACKAGE_REGISTRY has
583 been set.
584 • CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY disables the System
586 Package Registry in all the find_package() calls.
587 Package Registry Example
589 A simple convention for naming package registry entries is to use con‐
590 tent hashes. They are deterministic and unlikely to collide (ex‐
591 port(PACKAGE) uses this approach). The name of an entry referencing a
592 specific directory is simply the content hash of the directory path it‐
593 self.
594 If a project arranges for package registry entries to exist, such as:
596 > reg query HKCU\Software\Kitware\CMake\Packages\MyPackage
598 HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\MyPackage
599 45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage
600 7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build
601 or:
603 $ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
605 /home/me/work/lib/cmake/MyPackage
606 $ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
607 /home/me/work/MyPackage-build
608 then the CMakeLists.txt code:
610 find_package(MyPackage)
612 will search the registered locations for package configuration files
614 (MyPackageConfig.cmake). The search order among package registry en‐
615 tries for a single package is unspecified and the entry names (hashes
616 in this example) have no meaning. Registered locations may contain
617 package version files (MyPackageConfigVersion.cmake) to tell find_pack‐
618 age() whether a specific location is suitable for the version re‐
619 quested.
620 Package Registry Ownership
622 Package registry entries are individually owned by the project instal‐
623 lations that they reference. A package installer is responsible for
624 adding its own entry and the corresponding uninstaller is responsible
625 for removing it.
626 The export(PACKAGE) command populates the user package registry with
628 the location of a project build tree. Build trees tend to be deleted
629 by developers and have no "uninstall" event that could trigger removal
630 of their entries. In order to keep the registries clean the find_pack‐
631 age() command automatically removes stale entries it encounters if it
632 has sufficient permissions. CMake provides no interface to remove an
633 entry referencing an existing build tree once export(PACKAGE) has been
634 invoked. However, if the project removes its package configuration
635 file from the build tree then the entry referencing the location will
636 be considered stale.
637
639 2000-2021 Kitware, Inc. and Contributors
6403.20.3 May 30, 2021 CMAKE-PACKAGES(7)