Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       cmake-packages -	CMake Packages Reference

       Packages	 provide  dependency  information to CMake based buildsystems.
       Packages	are found with the find_package() command.  The	result of  us-
       ing find_package	is either a set	of IMPORTED targets, or	a set of vari-
       ables corresponding to build-relevant information.

       CMake provides direct support for two forms  of	packages,  Config-file
       Packages	 and  Find-module  Packages.   Indirect	support	for pkg-config
       packages	is also	provided via the FindPkgConfig module.	In all	cases,
       the basic form of find_package()	calls is the same:

	  find_package(Qt4 4.7.0 REQUIRED) # CMake provides a Qt4 find-module
	  find_package(Qt5Core 5.1.0 REQUIRED) # Qt provides a Qt5 package config file.
	  find_package(LibXml2 REQUIRED) # Use pkg-config via the LibXml2 find-module

       In  cases  where	 it is known that a package configuration file is pro-
       vided by	upstream, and only that	should be used,	the CONFIG keyword may
       be passed to find_package():

	  find_package(Qt5Core 5.1.0 CONFIG REQUIRED)
	  find_package(Qt5Gui 5.1.0 CONFIG)

       Similarly, the MODULE keyword says to use only a	find-module:

	  find_package(Qt4 4.7.0 MODULE	REQUIRED)

       Specifying  the	type  of package explicitly improves the error message
       shown to	the user if it is not found.

       Both types of packages also support specifying components of a package,
       either after the	REQUIRED keyword:

	  find_package(Qt5 5.1.0 CONFIG	REQUIRED Widgets Xml Sql)

       or as a separate	COMPONENTS list:

	  find_package(Qt5 5.1.0 COMPONENTS Widgets Xml	Sql)

       or as a separate	OPTIONAL_COMPONENTS list:

	  find_package(Qt5 5.1.0 COMPONENTS Widgets

       Handling	 of COMPONENTS and OPTIONAL_COMPONENTS is defined by the pack-

       By setting  the	CMAKE_DISABLE_FIND_PACKAGE_<PackageName>  variable  to
       TRUE,  the PackageName package will not be searched, and	will always be

   Config-file Packages
       A config-file package is	a set of files provided	by upstreams for down-
       streams	to  use.  CMake	 searches in a number of locations for package
       configuration files, as described in the	find_package()	documentation.
       The  most  simple  way for a CMake user to tell cmake(1)	to search in a
       non-standard prefix for a package is to set the CMAKE_PREFIX_PATH cache

       Config-file packages are	provided by upstream vendors as	part of	devel-
       opment packages,	that is, they belong with the  header  files  and  any
       other files provided to assist downstreams in using the package.

       A  set  of  variables which provide package status information are also
       set  automatically  when	 using	a  config-file	package.   The	<Pack-
       age>_FOUND  variable  is	set to true or false, depending	on whether the
       package was found.  The <Package>_DIR cache variable is set to the  lo-
       cation of the package configuration file.

   Find-module Packages
       A  find	module	is a file with a set of	rules for finding the required
       pieces of a dependency, primarily header	files  and  libraries.	 Typi-
       cally,  a  find	module	is  needed when	the upstream is	not built with
       CMake, or is not	CMake-aware enough to otherwise	provide	a package con-
       figuration  file.   Unlike  a  package  configuration  file,  it	is not
       shipped with upstream, but is used by downstream	to find	the  files  by
       guessing	locations of files with	platform-specific hints.

       Unlike  the case	of an upstream-provided	package	configuration file, no
       single point of reference identifies the	package	as being found,	so the
       <Package>_FOUND variable	is not automatically set by the	find_package()
       command.	 It can	still be expected to be	set by convention however  and
       should  be set by the author of the Find-module.	 Similarly there is no
       <Package>_DIR variable, but each	of the artifacts such as library loca-
       tions and header	file locations provide a separate cache	variable.

       See  the	 cmake-developer(7) manual for more information	about creating
       Find-module files.

       A config-file package consists of a Package Configuration File and  op-
       tionally	a Package Version File provided	with the project distribution.

   Package Configuration File
       Consider	a project Foo that installs the	following files:


       It may also provide a CMake package configuration file:


       with content defining IMPORTED targets, or defining variables, such as:

	  # ...
	  # (compute PREFIX relative to	file location)
	  # ...
	  set(Foo_INCLUDE_DIRS ${PREFIX}/include/foo-1.2)
	  set(Foo_LIBRARIES ${PREFIX}/lib/foo-1.2/libfoo.a)

       If another project wishes to use	Foo it need only to locate the FooCon-
       fig.cmake file and load it to get all the information  it  needs	 about
       package	content	 locations.   Since  the package configuration file is
       provided	by the package installation it already knows all the file  lo-

       The  find_package()  command may	be used	to search for the package con-
       figuration file.	 This command constructs a set	of  installation  pre-
       fixes  and  searches under each prefix in several locations.  Given the
       name Foo, it looks  for	a  file	 called	 FooConfig.cmake  or  foo-con-
       fig.cmake.   The	 full  set of locations	is specified in	the find_pack-
       age() command documentation. One	place it looks is:


       where Foo* is a case-insensitive	globbing expression.  In  our  example
       the  globbing  expression will match <prefix>/lib/cmake/foo-1.2 and the
       package configuration file will be found.

       Once found, a package configuration file	is  immediately	 loaded.   It,
       together	 with a	package	version	file, contains all the information the
       project needs to	use the	package.

   Package Version File
       When the	find_package() command finds a candidate package configuration
       file it looks next to it	for a version file. The	version	file is	loaded
       to test whether the package version is an acceptable match for the ver-
       sion  requested.	 If the	version	file claims compatibility the configu-
       ration file is accepted.	 Otherwise it is ignored.

       The name	of the package version file must match	that  of  the  package
       configuration  file  but	has either -version or Version appended	to the
       name before the .cmake extension.  For example, the files:




       are each	pairs of package configuration files and corresponding package
       version files.

       When  the find_package()	command	loads a	version	file it	first sets the
       following variables:

	      The <package> name

	      Full requested version string

	      Major version if requested, else 0

	      Minor version if requested, else 0

	      Patch version if requested, else 0

	      Tweak version if requested, else 0

	      Number of	version	components, 0 to 4

       The version file	must use these variables to check whether it  is  com-
       patible or an exact match for the requested version and set the follow-
       ing variables with results:

	      Full provided version string

	      True if version is exact match

	      True if version is compatible

	      True if unsuitable as any	version

       Version files are loaded	in a nested scope so they are free to set  any
       variables they wish as part of their computation. The find_package com-
       mand wipes out the scope	when the version file has completed and	it has
       checked the output variables. When the version file claims to be	an ac-
       ceptable	match for the requested	version	the find_package command  sets
       the following variables for use by the project:

	      Full provided version string

	      Major version if provided, else 0

	      Minor version if provided, else 0

	      Patch version if provided, else 0

	      Tweak version if provided, else 0

	      Number of	version	components, 0 to 4

       The  variables  report  the  version  of	 the package that was actually
       found.  The <package> part of their name	matches	the argument given  to
       the find_package() command.

       Usually,	 the  upstream	depends	on CMake itself	and can	use some CMake
       facilities for creating the package files. Consider an  upstream	 which
       provides	a single shared	library:



	  set(Upstream_VERSION 3.4.1)


	  add_library(ClimbingStats SHARED climbingstats.cpp)
	  set_property(TARGET ClimbingStats PROPERTY VERSION ${Upstream_VERSION})
	  set_property(TARGET ClimbingStats PROPERTY SOVERSION 3)
	  set_property(TARGET ClimbingStats PROPERTY
	  set_property(TARGET ClimbingStats APPEND PROPERTY

	  install(TARGETS ClimbingStats	EXPORT ClimbingStatsTargets

	    VERSION ${Upstream_VERSION}
	    COMPATIBILITY AnyNewerVersion

	  export(EXPORT	ClimbingStatsTargets
	    FILE "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsTargets.cmake"
	    NAMESPACE Upstream::

	  set(ConfigPackageLocation lib/cmake/ClimbingStats)
	  install(EXPORT ClimbingStatsTargets

       The  CMakePackageConfigHelpers  module  provides	a macro	for creating a
       simple ConfigVersion.cmake file.	 This file sets	 the  version  of  the
       package.	  It  is read by CMake when find_package() is called to	deter-
       mine the	compatibility with the requested version, and to set some ver-
       sion-specific   variables  <Package>_VERSION,  <Package>_VERSION_MAJOR,
       <Package>_VERSION_MINOR etc.  The install(EXPORT) command  is  used  to
       export the targets in the ClimbingStatsTargets export-set, defined pre-
       viously by the install(TARGETS) command.	 This  command	generates  the
       ClimbingStatsTargets.cmake  file	 to contain IMPORTED targets, suitable
       for use by downstreams and arranges to install it  to  lib/cmake/Climb-
       ingStats.    The	  generated   ClimbingStatsConfigVersion.cmake	and  a
       cmake/ClimbingStatsConfig.cmake are installed  to  the  same  location,
       completing the package.

       The  generated  IMPORTED	targets	have appropriate properties set	to de-
       fine their usage	requirements, such  as	INTERFACE_INCLUDE_DIRECTORIES,
       INTERFACE_COMPILE_DEFINITIONS  and  other  relevant built-in INTERFACE_
       properties.  The	INTERFACE variant of user-defined properties listed in
       COMPATIBLE_INTERFACE_STRING  and	 other Compatible Interface Properties
       are also	propagated to the generated IMPORTED targets.	In  the	 above
       case,  ClimbingStats_MAJOR_VERSION is defined as	a string which must be
       compatible among	the dependencies of any	 depender.   By	 setting  this
       custom defined user property in this version and	in the next version of
       ClimbingStats, cmake(1) will issue a diagnostic if there	is an  attempt
       to  use	version	3 together with	version	4.  Packages can choose	to em-
       ploy such a pattern if different	major versions of the package are  de-
       signed to be incompatible.

       A  NAMESPACE with double-colons is specified when exporting the targets
       for installation.  This convention of double-colons gives CMake a  hint
       that the	name is	an IMPORTED target when	it is used by downstreams with
       the target_link_libraries() command.  This way, CMake can issue a diag-
       nostic if the package providing it has not yet been found.

       In  this	case, when using install(TARGETS) the INCLUDES DESTINATION was
       specified.  This	causes the  IMPORTED  targets  to  have	 their	INTER-
       FACE_INCLUDE_DIRECTORIES	 populated  with  the include directory	in the
       CMAKE_INSTALL_PREFIX.  When the IMPORTED	target is used by  downstream,
       it automatically	consumes the entries from that property.

   Creating a Package Configuration File
       In this case, the ClimbingStatsConfig.cmake file	could be as simple as:


       As  this	allows downstreams to use the IMPORTED targets.	 If any	macros
       should be provided by the ClimbingStats package,	they should  be	 in  a
       separate	 file  which  is  installed to the same	location as the	Climb-
       ingStatsConfig.cmake file, and included from there.

       This can	also be	extended to cover dependencies:

	  # ...
	  add_library(ClimbingStats SHARED climbingstats.cpp)

	  find_package(Stats 2.6.4 REQUIRED)
	  target_link_libraries(ClimbingStats PUBLIC Stats::Types)

       As the Stats::Types target is a	PUBLIC	dependency  of	ClimbingStats,
       downstreams   must  also	 find  the  Stats  package  and	 link  to  the
       Stats::Types library.  The Stats	package	should be found	in the	Climb-
       ingStatsConfig.cmake  file  to  ensure this.  The find_dependency macro
       from  the  CMakeFindDependencyMacro  helps  with	 this  by  propagating
       whether	the package is REQUIRED, or QUIET etc.	All REQUIRED dependen-
       cies of a package should	be found in the	Config.cmake file:

	  find_dependency(Stats	2.6.4)


       The find_dependency macro also sets ClimbingStats_FOUND to False	if the
       dependency is not found,	along with a diagnostic	that the ClimbingStats
       package can not be used without the Stats package.

       If COMPONENTS are specified when	the  downstream	 uses  find_package(),
       they are	listed in the <Package>_FIND_COMPONENTS	variable. If a partic-
       ular component is non-optional, then the	<Package>_FIND_REQUIRED_<comp>
       will  be	 true. This can	be tested with logic in	the package configura-
       tion file:

	  find_dependency(Stats	2.6.4)


	  set(_supported_components Plot Table)

	  foreach(_comp	${ClimbingStats_FIND_COMPONENTS})
	    if (NOT ";${_supported_components};" MATCHES _comp)
	      set(ClimbingStats_FOUND False)
	      set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")

       Here, the ClimbingStats_NOT_FOUND_MESSAGE is set	to  a  diagnosis  that
       the  package could not be found because an invalid component was	speci-
       fied.  This message variable can	be set for any case where  the	_FOUND
       variable	is set to False, and will be displayed to the user.

   Creating a Package Configuration File for the Build Tree
       The  export(EXPORT) command creates an IMPORTED targets definition file
       which is	specific to the	build-tree, and	is not relocatable.  This  can
       similarly  be used with a suitable package configuration	file and pack-
       age version file	to define a package for	the build tree	which  may  be
       used  without installation.  Consumers of the build tree	can simply en-
       sure that the CMAKE_PREFIX_PATH contains	the build  directory,  or  set
       the ClimbingStats_DIR to	<build_dir>/ClimbingStats in the cache.

   Creating Relocatable	Packages
       A relocatable package must not reference	absolute paths of files	on the
       machine where the package is built that will not	exist on the  machines
       where the package may be	installed.

       Packages	created	by install(EXPORT) are designed	to be relocatable, us-
       ing paths relative to the location of the package itself.  When	defin-
       ing the interface of a target for EXPORT, keep in mind that the include
       directories should be specified as relative paths which are relative to

	  target_include_directories(tgt INTERFACE
	    # Wrong, not relocatable:

	  target_include_directories(tgt INTERFACE
	    # Ok, relocatable:

       The $<INSTALL_PREFIX> generator expression may be used as a placeholder
       for the install prefix without resulting	in a non-relocatable  package.
       This is necessary if complex generator expressions are used:

	  target_include_directories(tgt INTERFACE
	    # Ok, relocatable:

       This  also  applies  to paths referencing external dependencies.	 It is
       not advisable to	populate any properties	which may contain paths,  such
       paths relevant to dependencies.	For example, this code	may  not  work
       well for	a relocatable package:

	  target_link_libraries(ClimbingStats INTERFACE
	  target_include_directories(ClimbingStats INTERFACE

       The  referenced	variables  may contain the absolute paths to libraries
       and include directories as found	on the machine the  package  was  made
       on.   This would	create a package with hard-coded paths to dependencies
       and not suitable	for relocation.

       Ideally such dependencies should	be used	 through  their	 own  IMPORTED
       targets	that  have  their  own IMPORTED_LOCATION and usage requirement
       properties such as  INTERFACE_INCLUDE_DIRECTORIES  populated  appropri-
       ately.	Those  imported	 targets  may  then  be	 used  with  the  tar-
       get_link_libraries() command for	ClimbingStats:

	  target_link_libraries(ClimbingStats INTERFACE	Foo::Foo Bar::Bar)

       With this approach the package  references  its	external  dependencies
       only  through  the names	of IMPORTED targets.  When a consumer uses the
       installed package, the consumer will run	the appropriate	find_package()
       commands	 (via  the  find_dependency macro described above) to find the
       dependencies and	populate the imported targets with  appropriate	 paths
       on their	own machine.

       Unfortunately  many  modules  shipped with CMake	do not yet provide IM-
       PORTED targets because their development	pre-dated this approach.  This
       may improve incrementally over time.  Workarounds to create relocatable
       packages	using such modules include:

       o When building the package, specify each Foo_LIBRARY  cache  entry  as
	 just  a  library name,	e.g. -DFoo_LIBRARY=foo.	 This tells the	corre-
	 sponding find module to populate the Foo_LIBRARIES with just  foo  to
	 ask  the  linker  to  search for the library instead of hard-coding a

       o Or, after installing the package  content  but	 before	 creating  the
	 package  installation binary for redistribution, manually replace the
	 absolute paths	with placeholders for substitution by the installation
	 tool when the package is installed.

       CMake  provides	two  central  locations	to register packages that have
       been built or installed anywhere	on a system:

       o User Package Registry

       o System	Package	Registry

       The registries are especially useful to help projects find packages  in
       non-standard install locations or directly in their own build trees.  A
       project may populate either the user or system registry (using its  own
       means, see below) to refer to its location.  In either case the package
       should store at the registered location a  Package  Configuration  File
       (<package>Config.cmake)	and  optionally	a Package Version File (<pack-

       The find_package() command searches the two package registries  as  two
       of  the	search steps specified in its documentation.  If it has	suffi-
       cient permissions it also removes stale package registry	 entries  that
       refer  to  directories  that  do	not exist or do	not contain a matching
       package configuration file.

   User	Package	Registry
       The User	Package	Registry is stored in a	per-user  location.   The  ex-
       port(PACKAGE)  command  may be used to register a project build tree in
       the user	package	registry.  CMake currently provides  no	 interface  to
       add  install  trees  to	the user package registry.  Installers must be
       manually	taught to register their packages if desired.

       On Windows the user package registry is stored in the Windows  registry
       under a key in HKEY_CURRENT_USER.

       A <package> may appear under registry key:


       as  a  REG_SZ  value, with arbitrary name, that specifies the directory
       containing the package configuration file.

       On UNIX platforms the user package registry is stored in	the user  home
       directory  under	 ~/.cmake/packages.   A	<package> may appear under the


       as a file, with arbitrary name, whose content specifies	the  directory
       containing the package configuration file.

   System Package Registry
       The System Package Registry is stored in	a system-wide location.	 CMake
       currently provides no interface to add to the system package  registry.
       Installers  must	 be  manually taught to	register their packages	if de-

       On Windows the system package registry is stored	in  the	 Windows  reg-
       istry  under a key in HKEY_LOCAL_MACHINE.  A <package> may appear under
       registry	key:


       as a REG_SZ value, with arbitrary name, that  specifies	the  directory
       containing the package configuration file.

       There is	no system package registry on non-Windows platforms.

   Disabling the Package Registry
       In  some	cases using the	Package	Registries is not desirable. CMake al-
       lows one	to disable them	using the following variables:

	  o CMAKE_EXPORT_NO_PACKAGE_REGISTRY disables the export(PACKAGE) com-

	  o CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY  disables  the User Package
	    Registry in	all the	find_package() calls.

	    Package Registry in	all the	find_package() calls.

   Package Registry Example
       A  simple convention for	naming package registry	entries	is to use con-
       tent hashes.  They are  deterministic  and  unlikely  to	 collide  (ex-
       port(PACKAGE)  uses this	approach).  The	name of	an entry referencing a
       specific	directory is simply the	content	hash of	the directory path it-

       If a project arranges for package registry entries to exist, such as:

	  > reg	query HKCU\Software\Kitware\CMake\Packages\MyPackage
	   45e7d55f13b87179bb12f907c8de6fc4 REG_SZ c:/Users/Me/Work/lib/cmake/MyPackage
	   7b4a9844f681c80ce93190d4e3185db9 REG_SZ c:/Users/Me/Work/MyPackage-build


	  $ cat	~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
	  $ cat	~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07

       then the	CMakeLists.txt code:


       will  search  the  registered locations for package configuration files
       (MyPackageConfig.cmake).	 The search order among	package	 registry  en-
       tries  for  a single package is unspecified and the entry names (hashes
       in this example)	have no	meaning.   Registered  locations  may  contain
       package version files (MyPackageConfigVersion.cmake) to tell find_pack-
       age() whether a specific	location  is  suitable	for  the  version  re-

   Package Registry Ownership
       Package	registry entries are individually owned	by the project instal-
       lations that they reference.  A package installer  is  responsible  for
       adding  its  own	entry and the corresponding uninstaller	is responsible
       for removing it.

       The export(PACKAGE) command populates the user  package	registry  with
       the  location  of a project build tree.	Build trees tend to be deleted
       by developers and have no "uninstall" event that	could trigger  removal
       of their	entries.  In order to keep the registries clean	the find_pack-
       age() command automatically removes stale entries it encounters	if  it
       has  sufficient	permissions.  CMake provides no	interface to remove an
       entry referencing an existing build tree	once export(PACKAGE) has  been
       invoked.	  However,  if	the  project removes its package configuration
       file from the build tree	then the entry referencing the	location  will
       be considered stale.

       2000-2017 Kitware, Inc. and Contributors

3.8.2				 Jul 02, 2017		     CMAKE-PACKAGES(7)


Want to link to this manual page? Use this URL:

home | help