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. Likewise, setting the
59 CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> to TRUE will make the package
60 REQUIRED.
61 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 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 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 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 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 See the cmake-developer(7) manual for more information about creating
99 Find-module files.
100
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 Package Configuration File
106 Consider a project Foo that installs the following files:
107 <prefix>/include/foo-1.2/foo.h
109 <prefix>/lib/foo-1.2/libfoo.a
110 It may also provide a CMake package configuration file:
112 <prefix>/lib/cmake/foo-1.2/FooConfig.cmake
114 with content defining IMPORTED targets, or defining variables, such as:
116 # ...
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 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 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 <prefix>/lib/cmake/Foo*/
137 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 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 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 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 <prefix>/lib/cmake/foo-1.3/foo-config.cmake
158 <prefix>/lib/cmake/foo-1.3/foo-config-version.cmake
159 and:
161 <prefix>/lib/cmake/bar-4.2/BarConfig.cmake
163 <prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake
164 are each pairs of package configuration files and corresponding package
166 version files.
167 When the find_package() command loads a version file it first sets the
169 following variables:
170 PACKAGE_FIND_NAME
172 The <PackageName>
173 PACKAGE_FIND_VERSION
175 Full requested version string
176 PACKAGE_FIND_VERSION_MAJOR
178 Major version if requested, else 0
179 PACKAGE_FIND_VERSION_MINOR
181 Minor version if requested, else 0
182 PACKAGE_FIND_VERSION_PATCH
184 Patch version if requested, else 0
185 PACKAGE_FIND_VERSION_TWEAK
187 Tweak version if requested, else 0
188 PACKAGE_FIND_VERSION_COUNT
190 Number of version components, 0 to 4
191 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 PACKAGE_VERSION
197 Full provided version string
198 PACKAGE_VERSION_EXACT
200 True if version is exact match
201 PACKAGE_VERSION_COMPATIBLE
203 True if version is compatible
204 PACKAGE_VERSION_UNSUITABLE
206 True if unsuitable as any version
207 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 <PackageName>_VERSION
216 Full provided version string
217 <PackageName>_VERSION_MAJOR
219 Major version if provided, else 0
220 <PackageName>_VERSION_MINOR
222 Minor version if provided, else 0
223 <PackageName>_VERSION_PATCH
225 Patch version if provided, else 0
226 <PackageName>_VERSION_TWEAK
228 Tweak version if provided, else 0
229 <PackageName>_VERSION_COUNT
231 Number of version components, 0 to 4
232 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
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 project(UpstreamLib)
243 set(CMAKE_INCLUDE_CURRENT_DIR ON)
245 set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)
246 set(Upstream_VERSION 3.4.1)
248 include(GenerateExportHeader)
250 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 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 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 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 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 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 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 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 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 Creating a Package Configuration File
353 In this case, the ClimbingStatsConfig.cmake file could be as simple as:
354 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
356 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 This can also be extended to cover dependencies:
363 # ...
365 add_library(ClimbingStats SHARED climbingstats.cpp)
366 generate_export_header(ClimbingStats)
367 find_package(Stats 2.6.4 REQUIRED)
369 target_link_libraries(ClimbingStats PUBLIC Stats::Types)
370 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 include(CMakeFindDependencyMacro)
380 find_dependency(Stats 2.6.4)
381 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
383 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
384 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 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 include(CMakeFindDependencyMacro)
396 find_dependency(Stats 2.6.4)
397 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
399 include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")
400 set(_ClimbingStats_supported_components Plot Table)
402 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 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 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 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 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 target_include_directories(tgt INTERFACE
437 # Wrong, not relocatable:
438 $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
439 )
440 target_include_directories(tgt INTERFACE
442 # Ok, relocatable:
443 $<INSTALL_INTERFACE:include/TgtName>
444 )
445 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 target_include_directories(tgt INTERFACE
451 # Ok, relocatable:
452 $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
453 )
454 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 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 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 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 target_link_libraries(ClimbingStats INTERFACE Foo::Foo Bar::Bar)
480 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 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 • 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 • 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
505 CMake provides two central locations to register packages that have
506 been built or installed anywhere on a system:
507 • User Package Registry
509 • System Package Registry
511 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 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 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 On Windows the user package registry is stored in the Windows registry
534 under a key in HKEY_CURRENT_USER.
535 A <PackageName> may appear under registry key:
537 HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName>
539 as a REG_SZ value, with arbitrary name, that specifies the directory
541 containing the package configuration file.
542 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 ~/.cmake/packages/<PackageName>
548 as a file, with arbitrary name, whose content specifies the directory
550 containing the package configuration file.
551 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 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 HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>
563 as a REG_SZ value, with arbitrary name, that specifies the directory
565 containing the package configuration file.
566 There is no system package registry on non-Windows platforms.
568 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 • 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 • CMAKE_FIND_USE_PACKAGE_REGISTRY disables the User Package Registry in
581 all the find_package() calls when set to FALSE.
582 • 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 • CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY disables the System
589 Package Registry in all the find_package() calls.
590 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 If a project arranges for package registry entries to exist, such as:
599 > 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 or:
606 $ 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 then the CMakeLists.txt code:
613 find_package(MyPackage)
615 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 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 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
6433.25.2 Jan 19, 2023 CMAKE-PACKAGES(7)