Go to main content

man pages section 7: Standards, Environments, Macros, Character Sets, and Miscellany

Exit Print View

Updated: Wednesday, July 27, 2022

cmake-packages (7)


cmake-packages - CMake Packages Reference


Please see following description for synopsis


CMAKE-PACKAGES(7)                    CMake                   CMAKE-PACKAGES(7)

       cmake-packages - CMake Packages Reference

       Packages  provide  dependency  information to CMake based buildsystems.
       Packages are found with the  find_package()  command.   The  result  of
       using  find_package()  is either a set of IMPORTED targets, or a set of
       variables 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
                                 OPTIONAL_COMPONENTS Xml Sql

       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 NOTFOUND.

   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  <Package-
       Name>_FOUND  variable is set to true or false, depending on whether the
       package was found.  The <PackageName>_DIR cache variable is set to  the
       location 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
       <PackageName>_FOUND variable is not automatically set by the find_pack-
       age() command.  It can still be expected to be set by  convention  how-
       ever  and  should  be  set by the author of the Find-module.  Similarly
       there is no <PackageName>_DIR variable, but each of the artifacts  such
       as library locations and header file locations provide a separate cache

       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
       optionally a Package Version File provided with the  project  distribu-

   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

       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 <PackageName>

              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
       acceptable 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 <PackageName> 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
            INTERFACE_ClimbingStats_MAJOR_VERSION 3)
          set_property(TARGET ClimbingStats APPEND PROPERTY

          install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets
            INCLUDES DESTINATION include

            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   <PackageName>_VERSION,   <PackageName>_VER-
       SION_MAJOR, <PackageName>_VERSION_MINOR etc.  The install(EXPORT)  com-
       mand  is  used  to  export  the  targets  in  the  ClimbingStatsTargets
       export-set, defined previously 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/ClimbingStats.  The generated ClimbingStatsCon-
       figVersion.cmake and a cmake/ClimbingStatsConfig.cmake are installed to
       the same location, completing the package.

       The  generated  IMPORTED  targets  have  appropriate  properties set to
       define 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
       employ such a pattern if different major versions of  the  package  are
       designed 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 <PackageName>_FIND_COMPONENTS variable. If a
       particular   component   is   non-optional,    then    the    <Package-
       Name>_FIND_REQUIRED_<comp>  will be true. This can be tested with logic
       in the package configuration 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
       ensure 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,
       using paths relative to the  location  of  the  package  itself.   When
       defining  the  interface  of a target for EXPORT, keep in mind that the
       include directories should be specified as  relative  paths  which  are
       relative to the CMAKE_INSTALL_PREFIX:

          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
            ${Foo_LIBRARIES} ${Bar_LIBRARIES}
          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
       IMPORTED targets because their  development  pre-dated  this  approach.
       This  may improve incrementally over time.  Workarounds to create relo-
       catable 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
       (<PackageName>Config.cmake)  and  optionally  a  Package  Version  File

       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
       export(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 <PackageName> 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 <PackageName> may appear under
       the directory:


       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

       On Windows the system package registry is stored in  the  Windows  reg-
       istry  under  a  key in HKEY_LOCAL_MACHINE.  A <PackageName> 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
       allows one to disable them using the following variables:

       o The export(PACKAGE) command does not populate the user  package  reg-
         istry when CMP0090 is set to NEW unless the CMAKE_EXPORT_PACKAGE_REG-
         ISTRY variable explicitly enables it.  When CMP0090 is not set to NEW
         then  export(PACKAGE)  populates the user package registry unless the
         CMAKE_EXPORT_NO_PACKAGE_REGISTRY variable explicitly disables it.

       o CMAKE_FIND_USE_PACKAGE_REGISTRY disables the User Package Registry in
         all the find_package() calls when set to FALSE.

       o Deprecated  CMAKE_FIND_PACKAGE_NO_PACKAGE_REGISTRY  disables the User
         Package Registry in all the find_package() calls when  set  to  TRUE.
         This  variable  is  ignored  when CMAKE_FIND_USE_PACKAGE_REGISTRY has
         been set.

         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
       (export(PACKAGE) uses this approach).  The name of an entry referencing
       a specific directory is simply the content hash of the  directory  path

       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
       entries 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

   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-2021 Kitware, Inc. and Contributors

       See attributes(7) for descriptions of the following attributes:

       |Availability   | developer/build/cmake |
       |Stability      | Uncommitted           |

       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source                was                downloaded                from

       Further information about this software can be found on the open source
       community website at http://www.cmake.org/.

3.21.0                           Jun 27, 2022                CMAKE-PACKAGES(7)