code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>cmake-packages(7) — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="cmake-policies(7)" href="cmake-policies.7.html" />
    <link rel="prev" title="CPackWIX" href="../module/CPackWIX.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-packages(7)

cmake-packages(7)¶

Contents

cmake-packages(7)

Introduction

Using Packages

Config-file Packages

Find-module Packages

Package Layout

Package Configuration File

Package Version File

Creating Packages

Creating a Package Configuration File

Creating a Package Configuration File for the Build Tree

Creating Relocatable Packages

Package Registry

User Package Registry

System Package Registry

Disabling the Package Registry

Package Registry Example

Package Registry Ownership

Introduction¶

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.

Using Packages¶

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 provided 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
package.

By setting the CMAKE_DISABLE_FIND_PACKAGE_<PackageName> variable to
TRUE, the <PackageName> package will not be searched, and will always
be NOTFOUND. Likewise, setting the
CMAKE_REQUIRE_FIND_PACKAGE_<PackageName> to TRUE will make the
package REQUIRED.

Config-file Packages¶

A config-file package is a set of files provided by upstreams for downstreams
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 variable.

Config-file packages are provided by upstream vendors as part of development
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 <PackageName>_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.  Typically, a find module
is needed when the upstream is not built with CMake, or is not CMake-aware
enough to otherwise provide a package configuration 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_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 <PackageName>_DIR variable,
but each of the artifacts such as library locations and header file locations
provide a separate cache variable.

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

Package Layout¶

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

Package Configuration File¶

Consider a project Foo that installs the following files:

<prefix>/include/foo-1.2/foo.h
<prefix>/lib/foo-1.2/libfoo.a

It may also provide a CMake package configuration file:

<prefix>/lib/cmake/foo-1.2/FooConfig.cmake

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 FooConfig.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 locations.

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

<prefix>/lib/cmake/Foo*/

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 version requested.
If the version file claims compatibility the configuration 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:

<prefix>/lib/cmake/foo-1.3/foo-config.cmake
<prefix>/lib/cmake/foo-1.3/foo-config-version.cmake

and:

<prefix>/lib/cmake/bar-4.2/BarConfig.cmake
<prefix>/lib/cmake/bar-4.2/BarConfigVersion.cmake

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:

PACKAGE_FIND_NAME

The <PackageName>

PACKAGE_FIND_VERSION

Full requested version string

PACKAGE_FIND_VERSION_MAJOR

Major version if requested, else 0

PACKAGE_FIND_VERSION_MINOR

Minor version if requested, else 0

PACKAGE_FIND_VERSION_PATCH

Patch version if requested, else 0

PACKAGE_FIND_VERSION_TWEAK

Tweak version if requested, else 0

PACKAGE_FIND_VERSION_COUNT

Number of version components, 0 to 4

The version file must use these variables to check whether it is compatible or
an exact match for the requested version and set the following variables with
results:

PACKAGE_VERSION

Full provided version string

PACKAGE_VERSION_EXACT

True if version is exact match

PACKAGE_VERSION_COMPATIBLE

True if version is compatible

PACKAGE_VERSION_UNSUITABLE

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 command 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:

<PackageName>_VERSION

Full provided version string

<PackageName>_VERSION_MAJOR

Major version if provided, else 0

<PackageName>_VERSION_MINOR

Minor version if provided, else 0

<PackageName>_VERSION_PATCH

Patch version if provided, else 0

<PackageName>_VERSION_TWEAK

Tweak version if provided, else 0

<PackageName>_VERSION_COUNT

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.

Creating Packages¶

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:

project(UpstreamLib)

set(CMAKE_INCLUDE_CURRENT_DIR ON)
set(CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE ON)

set(Upstream_VERSION 3.4.1)

include(GenerateExportHeader)

add_library(ClimbingStats SHARED climbingstats.cpp)
generate_export_header(ClimbingStats)
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
  COMPATIBLE_INTERFACE_STRING ClimbingStats_MAJOR_VERSION
)

install(TARGETS ClimbingStats EXPORT ClimbingStatsTargets
  LIBRARY DESTINATION lib
  ARCHIVE DESTINATION lib
  RUNTIME DESTINATION bin
  INCLUDES DESTINATION include
)
install(
  FILES
    climbingstats.h
    "${CMAKE_CURRENT_BINARY_DIR}/climbingstats_export.h"
  DESTINATION
    include
  COMPONENT
    Devel
)

include(CMakePackageConfigHelpers)
write_basic_package_version_file(
  "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
  VERSION ${Upstream_VERSION}
  COMPATIBILITY AnyNewerVersion
)

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

set(ConfigPackageLocation lib/cmake/ClimbingStats)
install(EXPORT ClimbingStatsTargets
  FILE
    ClimbingStatsTargets.cmake
  NAMESPACE
    Upstream::
  DESTINATION
    ${ConfigPackageLocation}
)
install(
  FILES
    cmake/ClimbingStatsConfig.cmake
    "${CMAKE_CURRENT_BINARY_DIR}/ClimbingStats/ClimbingStatsConfigVersion.cmake"
  DESTINATION
    ${ConfigPackageLocation}
  COMPONENT
    Devel
)

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
determine the compatibility with the requested version, and to set some
version-specific variables <PackageName>_VERSION, <PackageName>_VERSION_MAJOR,
<PackageName>_VERSION_MINOR etc.  The install(EXPORT) command 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 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 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 diagnostic 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
INTERFACE_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:

include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")

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
ClimbingStatsConfig.cmake file, and included from there.

This can also be extended to cover dependencies:

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

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 ClimbingStatsConfig.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
dependencies of a package should be found in the Config.cmake file:

include(CMakeFindDependencyMacro)
find_dependency(Stats 2.6.4)

include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")

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 <PackageName>_FIND_REQUIRED_<comp> will
be true. This can be tested with logic in the package configuration file:

include(CMakeFindDependencyMacro)
find_dependency(Stats 2.6.4)

include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsTargets.cmake")
include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStatsMacros.cmake")

set(_ClimbingStats_supported_components Plot Table)

foreach(_comp ${ClimbingStats_FIND_COMPONENTS})
  if (NOT ";${_ClimbingStats_supported_components};" MATCHES ";${_comp};")
    set(ClimbingStats_FOUND False)
    set(ClimbingStats_NOT_FOUND_MESSAGE "Unsupported component: ${_comp}")
  endif()
  include("${CMAKE_CURRENT_LIST_DIR}/ClimbingStats${_comp}Targets.cmake")
endforeach()

Here, the ClimbingStats_NOT_FOUND_MESSAGE is set to a diagnosis that the package
could not be found because an invalid component was specified.  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
package 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:
  $<INSTALL_INTERFACE:${CMAKE_INSTALL_PREFIX}/include/TgtName>
)

target_include_directories(tgt INTERFACE
  # Ok, relocatable:
  $<INSTALL_INTERFACE:include/TgtName>
)

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:
  $<INSTALL_INTERFACE:$<$<CONFIG:Debug>:$<INSTALL_PREFIX>/include/TgtName>>
)

This also applies to paths referencing external dependencies.
It is not advisable to populate any properties which may contain
paths, such as INTERFACE_INCLUDE_DIRECTORIES and
INTERFACE_LINK_LIBRARIES, with 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
  "$<INSTALL_INTERFACE:${Foo_INCLUDE_DIRS};${Bar_INCLUDE_DIRS}>"
  )

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
appropriately.  Those imported targets may then be used with
the target_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 relocatable packages
using such modules include:

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

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.

Package Registry¶

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

User Package Registry

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 (<PackageName>ConfigVersion.cmake).

The find_package() command searches the two package registries
as two of the search steps specified in its documentation.  If it has
sufficient 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:

HKEY_CURRENT_USER\Software\Kitware\CMake\Packages\<PackageName>

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:

~/.cmake/packages/<PackageName>

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

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

HKEY_LOCAL_MACHINE\Software\Kitware\CMake\Packages\<PackageName>

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:

The export(PACKAGE) command does not populate the user
package registry when CMP0090 is set to NEW unless the
CMAKE_EXPORT_PACKAGE_REGISTRY 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.

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

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.

CMAKE_FIND_PACKAGE_NO_SYSTEM_PACKAGE_REGISTRY disables
the System Package Registry in all the find_package() calls.

Package Registry Example¶

A simple convention for naming package registry entries is to use content
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 itself.

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

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

or:

$ cat ~/.cmake/packages/MyPackage/7d1fb77e07ce59a81bed093bbee945bd
/home/me/work/lib/cmake/MyPackage
$ cat ~/.cmake/packages/MyPackage/f92c1db873a1937f3100706657c63e07
/home/me/work/MyPackage-build

then the CMakeLists.txt code:

find_package(MyPackage)

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_package() whether a specific location is suitable
for the version requested.

Package Registry Ownership¶

Package registry entries are individually owned by the project installations
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_package()
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.

Table of Contents

cmake-packages(7)

Introduction

Using Packages

Config-file Packages

Find-module Packages

Package Layout

Package Configuration File

Package Version File

Creating Packages

Creating a Package Configuration File

Creating a Package Configuration File for the Build Tree

Creating Relocatable Packages

Package Registry

User Package Registry

System Package Registry

Disabling the Package Registry

Package Registry Example

Package Registry Ownership

Previous topic

CPackWIX

Next topic

cmake-policies(7)

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-packages(7)

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>cmake-policies(7) — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="CMP0161" href="../policy/CMP0161.html" />
    <link rel="prev" title="cmake-packages(7)" href="cmake-packages.7.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-policies(7)

cmake-policies(7)¶

Contents

cmake-policies(7)

Introduction

Policies Introduced by CMake 3.29

Policies Introduced by CMake 3.28

Policies Introduced by CMake 3.27

Policies Introduced by CMake 3.26

Policies Introduced by CMake 3.25

Policies Introduced by CMake 3.24

Policies Introduced by CMake 3.23

Policies Introduced by CMake 3.22

Policies Introduced by CMake 3.21

Policies Introduced by CMake 3.20

Policies Introduced by CMake 3.19

Policies Introduced by CMake 3.18

Policies Introduced by CMake 3.17

Policies Introduced by CMake 3.16

Policies Introduced by CMake 3.15

Policies Introduced by CMake 3.14

Policies Introduced by CMake 3.13

Policies Introduced by CMake 3.12

Policies Introduced by CMake 3.11

Policies Introduced by CMake 3.10

Policies Introduced by CMake 3.9

Policies Introduced by CMake 3.8

Policies Introduced by CMake 3.7

Policies Introduced by CMake 3.4

Policies Introduced by CMake 3.3

Policies Introduced by CMake 3.2

Policies Introduced by CMake 3.1

Policies Introduced by CMake 3.0

Policies Introduced by CMake 2.8

Policies Introduced by CMake 2.6

Introduction¶

Policies in CMake are used to preserve backward compatible behavior
across multiple releases.  When a new policy is introduced, newer CMake
versions will begin to warn about the backward compatible behavior.  It
is possible to disable the warning by explicitly requesting the OLD, or
backward compatible behavior using the cmake_policy() command.
It is also possible to request NEW, or non-backward compatible behavior
for a policy, also avoiding the warning.  Each policy can also be set to
either NEW or OLD behavior explicitly on the command line with the
CMAKE_POLICY_DEFAULT_CMP<NNNN> variable.

A policy is a deprecation mechanism and not a reliable feature toggle.
A policy should almost never be set to OLD, except to silence warnings
in an otherwise frozen or stable codebase, or temporarily as part of a
larger migration path. The OLD behavior of each policy is undesirable
and will be replaced with an error condition in a future release.

The cmake_minimum_required() command does more than report an
error if a too-old version of CMake is used to build a project.  It
also sets all policies introduced in that CMake version or earlier to
NEW behavior.  To manage policies without increasing the minimum required
CMake version, the if(POLICY) command may be used:

if(POLICY CMP0990)
  cmake_policy(SET CMP0990 NEW)
endif()

This has the effect of using the NEW behavior with newer CMake releases which
users may be using and not issuing a compatibility warning.

The setting of a policy is confined in some cases to not propagate to the
parent scope.  For example, if the files read by the include() command
or the find_package() command contain a use of cmake_policy(),
that policy setting will not affect the caller by default.  Both commands accept
an optional NO_POLICY_SCOPE keyword to control this behavior.

The CMAKE_MINIMUM_REQUIRED_VERSION variable may also be used
to determine whether to report an error on use of deprecated macros or
functions.

Policies Introduced by CMake 3.29¶

CMP0161: CPACK_PRODUCTBUILD_DOMAINS defaults to true.

CMP0160: More read-only target properties now error when trying to set them.

CMP0159: file(STRINGS) with REGEX updates CMAKE_MATCH_<n>.

CMP0158: add_test() honors CMAKE_CROSSCOMPILING_EMULATOR only when cross-compiling.

CMP0157: Swift compilation mode is selected by an abstraction.

CMP0156: De-duplicate libraries on link lines based on linker capabilities.

Policies Introduced by CMake 3.28¶

CMP0155: C++ sources in targets with at least C++20 are scanned for imports when supported.

CMP0154: Generated files are private by default in targets using file sets.

CMP0153: The exec_program command should not be called.

CMP0152: file(REAL_PATH) resolves symlinks before collapsing ../ components.

Policies Introduced by CMake 3.27¶

CMP0151: AUTOMOC include directory is a system include directory by default.

CMP0150: ExternalProject_Add and FetchContent_Declare treat relative git repository paths as being relative to parent project's remote.

CMP0149: Visual Studio generators select latest Windows SDK by default.

CMP0148: The FindPythonInterp and FindPythonLibs modules are removed.

CMP0147: Visual Studio generators build custom commands in parallel.

CMP0146: The FindCUDA module is removed.

CMP0145: The Dart and FindDart modules are removed.

CMP0144: find_package uses upper-case PACKAGENAME_ROOT variables.

Policies Introduced by CMake 3.26¶

CMP0143: USE_FOLDERS global property is treated as ON by default.

Policies Introduced by CMake 3.25¶

CMP0142: The Xcode generator does not append per-config suffixes to library search paths.

CMP0141: MSVC debug information format flags are selected by an abstraction.

CMP0140: The return() command checks its arguments.

Policies Introduced by CMake 3.24¶

CMP0139: The if() command supports path comparisons using PATH_EQUAL operator.

CMP0138: CheckIPOSupported uses flags from calling project.

CMP0137: try_compile() passes platform variables in project mode.

CMP0136: Watcom runtime library flags are selected by an abstraction.

CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method.

CMP0134: Fallback to "HOST" Windows registry view when "TARGET" view is not usable.

CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator.

CMP0132: Do not set compiler environment variables on first run.

CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression.

CMP0130: while() diagnoses condition evaluation errors.

Policies Introduced by CMake 3.23¶

CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU.

Policies Introduced by CMake 3.22¶

CMP0128: Selection of language standard and extension flags improved.

CMP0127: cmake_dependent_option() supports full Condition Syntax.

Policies Introduced by CMake 3.21¶

CMP0126: set(CACHE) does not remove a normal variable of the same name.

CMP0125: find_(path|file|library|program) have consistent behavior for cache variables.

CMP0124: foreach() loop variables are only available in the loop scope.

CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly.

CMP0122: UseSWIG use standard library name conventions for csharp language.

CMP0121: The list command detects invalid indices.

Policies Introduced by CMake 3.20¶

CMP0120: The WriteCompilerDetectionHeader module is removed.

CMP0119: LANGUAGE source file property explicitly compiles as language.

CMP0118: The GENERATED source file property is now visible in all directories.

CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default.

CMP0116: Ninja generators transform DEPFILEs from add_custom_command().

CMP0115: Source file extensions must be explicit.

Policies Introduced by CMake 3.19¶

CMP0114: ExternalProject step targets fully adopt their steps.

CMP0113: Makefile generators do not repeat custom commands from target dependencies.

CMP0112: Target file component generator expressions do not add target dependencies.

CMP0111: An imported target missing its location property fails during generation.

CMP0110: add_test() supports arbitrary characters in test names.

CMP0109: find_program() requires permission to execute but not to read.

Policies Introduced by CMake 3.18¶

CMP0108: A target cannot link to itself through an alias.

CMP0107: An ALIAS target cannot overwrite another target.

CMP0106: The Documentation module is removed.

CMP0105: Device link step uses the link options.

CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed.

CMP0103: Multiple export() with same FILE without APPEND is not allowed.

Policies Introduced by CMake 3.17¶

CMP0102: mark_as_advanced() does nothing if a cache entry does not exist.

CMP0101: target_compile_options honors BEFORE keyword in all scopes.

CMP0100: Let AUTOMOC and AUTOUIC process .hh header files.

CMP0099: Link properties are transitive over private dependency on static libraries.

CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing.

Policies Introduced by CMake 3.16¶

CMP0097: ExternalProject_Add with GIT_SUBMODULES "" initializes no submodules.

CMP0096: project() preserves leading zeros in version components.

CMP0095: RPATH entries are properly escaped in the intermediary CMake install script.

Policies Introduced by CMake 3.15¶

CMP0094: FindPython3, FindPython2 and FindPython use LOCATION for lookup strategy.

CMP0093: FindBoost reports Boost_VERSION in x.y.z format.

CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default.

CMP0091: MSVC runtime library flags are selected by an abstraction.

CMP0090: export(PACKAGE) does not populate package registry by default.

CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang.

Policies Introduced by CMake 3.14¶

CMP0088: FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing.

CMP0087: install(SCRIPT | CODE) supports generator expressions.

CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag.

CMP0085: IN_LIST generator expression handles empty list items.

CMP0084: The FindQt module does not exist for find_package().

CMP0083: Add PIE options when linking executable.

CMP0082: Install rules from add_subdirectory() are interleaved with those in caller.

Policies Introduced by CMake 3.13¶

CMP0081: Relative paths not allowed in LINK_DIRECTORIES target property.

CMP0080: BundleUtilities cannot be included at configure time.

CMP0079: target_link_libraries allows use with targets in other directories.

CMP0078: UseSWIG generates standard target names.

CMP0077: option() honors normal variables.

CMP0076: target_sources() command converts relative paths to absolute.

Policies Introduced by CMake 3.12¶

CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES.

CMP0074: find_package uses PackageName_ROOT variables.

CMP0073: Do not produce legacy _LIB_DEPENDS cache entries.

Policies Introduced by CMake 3.11¶

CMP0072: FindOpenGL prefers GLVND by default when available.

Policies Introduced by CMake 3.10¶

CMP0071: Let AUTOMOC and AUTOUIC process GENERATED files.

CMP0070: Define file(GENERATE) behavior for relative paths.

Policies Introduced by CMake 3.9¶

CMP0069: INTERPROCEDURAL_OPTIMIZATION is enforced when enabled.

CMP0068: RPATH settings on macOS do not affect install_name.

Policies Introduced by CMake 3.8¶

CMP0067: Honor language standard in try_compile() source-file signature.

Policies Introduced by CMake 3.7¶

CMP0066: Honor per-config flags in try_compile() source-file signature.

Policies Introduced by CMake 3.4¶

CMP0065: Do not add flags to export symbols from executables without the ENABLE_EXPORTS target property.

CMP0064: Support new TEST if() operator.

Policies Introduced by CMake 3.3¶

CMP0063: Honor visibility properties for all target types.

CMP0062: Disallow install() of export() result.

CMP0061: CTest does not by default tell make to ignore errors (-i).

CMP0060: Link libraries by full path even in implicit directories.

CMP0059: Do not treat DEFINITIONS as a built-in directory property.

CMP0058: Ninja requires custom command byproducts to be explicit.

CMP0057: Support new IN_LIST if() operator.

Policies Introduced by CMake 3.2¶

CMP0056: Honor link flags in try_compile() source-file signature.

CMP0055: Strict checking for break() command.

Policies Introduced by CMake 3.1¶

CMP0054: Only interpret if() arguments as variables or keywords when unquoted.

CMP0053: Simplify variable reference and escape sequence evaluation.

CMP0052: Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES.

CMP0051: List TARGET_OBJECTS in SOURCES target property.

Policies Introduced by CMake 3.0¶

CMP0050: Disallow add_custom_command SOURCE signatures.

CMP0049: Do not expand variables in target source entries.

CMP0048: project() command manages VERSION variables.

CMP0047: Use QCC compiler id for the qcc drivers on QNX.

CMP0046: Error on non-existent dependency in add_dependencies.

CMP0045: Error on non-existent target in get_target_property.

CMP0044: Case sensitive Lang_COMPILER_ID generator expressions.

CMP0043: Ignore COMPILE_DEFINITIONS_Config properties.

CMP0042: MACOSX_RPATH is enabled by default.

CMP0041: Error on relative include with generator expression.

CMP0040: The target in the TARGET signature of add_custom_command() must exist.

CMP0039: Utility targets may not have link dependencies.

CMP0038: Targets may not link directly to themselves.

CMP0037: Target names should not be reserved and should match a validity pattern.

CMP0036: The build_name command should not be called.

CMP0035: The variable_requires command should not be called.

CMP0034: The utility_source command should not be called.

CMP0033: The export_library_dependencies command should not be called.

CMP0032: The output_required_files command should not be called.

CMP0031: The load_command command should not be called.

CMP0030: The use_mangled_mesa command should not be called.

CMP0029: The subdir_depends command should not be called.

CMP0028: Double colon in target name means ALIAS or IMPORTED target.

CMP0027: Conditionally linked imported targets with missing include directories.

CMP0026: Disallow use of the LOCATION target property.

CMP0025: Compiler id for Apple Clang is now AppleClang.

CMP0024: Disallow include export result.

Policies Introduced by CMake 2.8¶

CMP0023: Plain and keyword target_link_libraries signatures cannot be mixed.

CMP0022: INTERFACE_LINK_LIBRARIES defines the link interface.

CMP0021: Fatal error on relative paths in INCLUDE_DIRECTORIES target property.

CMP0020: Automatically link Qt executables to qtmain target on Windows.

CMP0019: Do not re-expand variables in include and link information.

CMP0018: Ignore CMAKE_SHARED_LIBRARY_Lang_FLAGS variable.

CMP0017: Prefer files from the CMake module directory when including from there.

CMP0016: target_link_libraries() reports error if its only argument is not a target.

CMP0015: link_directories() treats paths relative to the source dir.

CMP0014: Input directories must have CMakeLists.txt.

CMP0013: Duplicate binary directories are not allowed.

CMP0012: if() recognizes numbers and boolean constants.

Policies Introduced by CMake 2.6¶

CMP0011: Included scripts do automatic cmake_policy PUSH and POP.

CMP0010: Bad variable reference syntax is an error.

CMP0009: FILE GLOB_RECURSE calls should not follow symlinks by default.

CMP0008: Libraries linked by full-path must have a valid library file name.

CMP0007: list command no longer ignores empty elements.

CMP0006: Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION.

CMP0005: Preprocessor definition values are now escaped automatically.

CMP0004: Libraries linked may not have leading or trailing whitespace.

CMP0003: Libraries linked via full path no longer produce linker search paths.

CMP0002: Logical target names must be globally unique.

CMP0001: CMAKE_BACKWARDS_COMPATIBILITY should no longer be used.

CMP0000: A minimum required CMake version must be specified.

Table of Contents

cmake-policies(7)

Introduction

Policies Introduced by CMake 3.29

Policies Introduced by CMake 3.28

Policies Introduced by CMake 3.27

Policies Introduced by CMake 3.26

Policies Introduced by CMake 3.25

Policies Introduced by CMake 3.24

Policies Introduced by CMake 3.23

Policies Introduced by CMake 3.22

Policies Introduced by CMake 3.21

Policies Introduced by CMake 3.20

Policies Introduced by CMake 3.19

Policies Introduced by CMake 3.18

Policies Introduced by CMake 3.17

Policies Introduced by CMake 3.16

Policies Introduced by CMake 3.15

Policies Introduced by CMake 3.14

Policies Introduced by CMake 3.13

Policies Introduced by CMake 3.12

Policies Introduced by CMake 3.11

Policies Introduced by CMake 3.10

Policies Introduced by CMake 3.9

Policies Introduced by CMake 3.8

Policies Introduced by CMake 3.7

Policies Introduced by CMake 3.4

Policies Introduced by CMake 3.3

Policies Introduced by CMake 3.2

Policies Introduced by CMake 3.1

Policies Introduced by CMake 3.0

Policies Introduced by CMake 2.8

Policies Introduced by CMake 2.6

Previous topic

cmake-packages(7)

Next topic

CMP0161

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-policies(7)

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.

repo_name: lazytadpole/codenamesilverfish

license: mit


code:
<!DOCTYPE html>

    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

  <title>cmake-presets(7) — CMake 3.29.0-rc3 Documentation</title>

    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/cmake.css" />

    <link rel="icon" href="../_static/cmake-favicon.ico"/>
    <link rel="index" title="Index" href="../genindex.html" />
    <link rel="search" title="Search" href="../search.html" />
    <link rel="next" title="cmake-properties(7)" href="cmake-properties.7.html" />
    <link rel="prev" title="CMP0000" href="../policy/CMP0000.html" />

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-presets(7)

cmake-presets(7)¶

Contents

cmake-presets(7)

Introduction

Format

Includes

Configure Preset

Build Preset

Test Preset

Package Preset

Workflow Preset

Condition

Macro Expansion

Schema

Introduction¶

New in version 3.19.

One problem that CMake users often face is sharing settings with other people
for common ways to configure a project. This may be done to support CI builds,
or for users who frequently use the same build. CMake supports two main files,
CMakePresets.json and CMakeUserPresets.json, that allow users to
specify common configure options and share them with others. CMake also
supports files included with the include field.

CMakePresets.json and CMakeUserPresets.json live in the project's root
directory. They both have exactly the same format, and both are optional
(though at least one must be present if --preset
is specified).  CMakePresets.json is meant to specify project-wide build
details, while CMakeUserPresets.json is meant for developers to specify
their own local build details.

CMakePresets.json may be checked into a version control system, and
CMakeUserPresets.json should NOT be checked in. For example, if a
project is using Git, CMakePresets.json may be tracked, and
CMakeUserPresets.json should be added to the .gitignore.

Format¶

The files are a JSON document with an object as the root:

{
  "version": 6,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 23,
    "patch": 0
  },
  "include": [
    "otherThings.json",
    "moreThings.json"
  ],
  "configurePresets": [
    {
      "name": "default",
      "displayName": "Default Config",
      "description": "Default build using Ninja generator",
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/build/default",
      "cacheVariables": {
        "FIRST_CACHE_VARIABLE": {
          "type": "BOOL",
          "value": "OFF"
        },
        "SECOND_CACHE_VARIABLE": "ON"
      },
      "environment": {
        "MY_ENVIRONMENT_VARIABLE": "Test",
        "PATH": "$env{HOME}/ninja/bin:$penv{PATH}"
      },
      "vendor": {
        "example.com/ExampleIDE/1.0": {
          "autoFormat": true
        }
      }
    },
    {
      "name": "ninja-multi",
      "inherits": "default",
      "displayName": "Ninja Multi-Config",
      "description": "Default build using Ninja Multi-Config generator",
      "generator": "Ninja Multi-Config"
    },
    {
      "name": "windows-only",
      "inherits": "default",
      "displayName": "Windows-only configuration",
      "description": "This build is only available on Windows",
      "condition": {
        "type": "equals",
        "lhs": "${hostSystemName}",
        "rhs": "Windows"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "default",
      "configurePreset": "default"
    }
  ],
  "testPresets": [
    {
      "name": "default",
      "configurePreset": "default",
      "output": {"outputOnFailure": true},
      "execution": {"noTestsAction": "error", "stopOnFailure": true}
    }
  ],
  "packagePresets": [
    {
      "name": "default",
      "configurePreset": "default",
      "generators": [
        "TGZ"
      ]
    }
  ],
  "workflowPresets": [
    {
      "name": "default",
      "steps": [
        {
          "type": "configure",
          "name": "default"
        },
        {
          "type": "build",
          "name": "default"
        },
        {
          "type": "test",
          "name": "default"
        },
        {
          "type": "package",
          "name": "default"
        }
      ]
    }
  ],
  "vendor": {
    "example.com/ExampleIDE/1.0": {
      "autoFormat": false
    }
  }
}

The root object recognizes the following fields:

$schema

An optional string that provides a URI to the JSON schema that describes the
structure of this JSON document. This field is used for validation and
autocompletion in editors that support JSON schema. It doesn't affect the
behavior of the document itself. If this field is not specified, the JSON
document will still be valid, but tools that use JSON schema for validation
and autocompletion may not function correctly.
This is allowed in preset files specifying version 8 or above.

version

A required integer representing the version of the JSON schema.
The supported versions are:

1

New in version 3.19.

2

New in version 3.20.

3

New in version 3.21.

4

New in version 3.23.

5

New in version 3.24.

6

New in version 3.25.

7

New in version 3.27.

8

New in version 3.28.

cmakeMinimumRequired

An optional object representing the minimum version of CMake needed to
build this project. This object consists of the following fields:

major

An optional integer representing the major version.

minor

An optional integer representing the minor version.

patch

An optional integer representing the patch version.

include

An optional array of strings representing files to include. If the filenames
are not absolute, they are considered relative to the current file.
This is allowed in preset files specifying version 4 or above.
See Includes for discussion of the constraints on included files.

vendor

An optional map containing vendor-specific information. CMake does not
interpret the contents of this field except to verify that it is a map if
it does exist. However, the keys should be a vendor-specific domain name
followed by a /-separated path. For example, the Example IDE 1.0 could
use example.com/ExampleIDE/1.0. The value of each field can be anything
desired by the vendor, though will typically be a map.

configurePresets

An optional array of Configure Preset objects.
This is allowed in preset files specifying version 1 or above.

buildPresets

An optional array of Build Preset objects.
This is allowed in preset files specifying version 2 or above.

testPresets

An optional array of Test Preset objects.
This is allowed in preset files specifying version 2 or above.

packagePresets

An optional array of Package Preset objects.
This is allowed in preset files specifying version 6 or above.

workflowPresets

An optional array of Workflow Preset objects.
This is allowed in preset files specifying version 6 or above.

Includes¶

CMakePresets.json and CMakeUserPresets.json can include other files
with the include field in file version 4 and later. Files included
by these files can also include other files. If CMakePresets.json and
CMakeUserPresets.json are both present, CMakeUserPresets.json
implicitly includes CMakePresets.json, even with no include field,
in all versions of the format.

If a preset file contains presets that inherit from presets in another file,
the file must include the other file either directly or indirectly.
Include cycles are not allowed among files. If a.json includes
b.json, b.json cannot include a.json. However, a file may be
included multiple times from the same file or from different files.

Files directly or indirectly included from CMakePresets.json should be
guaranteed to be provided by the project. CMakeUserPresets.json may
include files from anywhere.

Starting from version 7, the include field supports
macro expansion, but only $penv{} macro expansion.

Configure Preset¶

Each entry of the configurePresets array is a JSON object
that may contain the following fields:

name

A required string representing the machine-friendly name of the preset.
This identifier is used in the cmake --preset option.
There must not be two configure presets in the union of CMakePresets.json
and CMakeUserPresets.json in the same directory with the same name.
However, a configure preset may have the same name as a build, test,
package, or workflow preset.

hidden

An optional boolean specifying whether or not a preset should be hidden.
If a preset is hidden, it cannot be used in the --preset= argument,
will not show up in the CMake GUI, and does not
have to have a valid generator or binaryDir, even from
inheritance. hidden presets are intended to be used as a base for
other presets to inherit via the inherits field.

inherits

An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.

The preset will inherit all of the fields from the inherits
presets by default (except name, hidden, inherits,
description, and displayName), but can override them as
desired. If multiple inherits presets provide conflicting values for
the same field, the earlier preset in the inherits array will be
preferred.

A preset can only inherit from another preset that is defined in the
same file or in one of the files it includes (directly or indirectly).
Presets in CMakePresets.json may not inherit from presets in
CMakeUserPresets.json.

condition

An optional Condition object. This is allowed in preset files specifying
version 3 or above.

vendor

An optional map containing vendor-specific information. CMake does not
interpret the contents of this field except to verify that it is a map
if it does exist. However, it should follow the same conventions as the
root-level vendor field. If vendors use their own per-preset
vendor field, they should implement inheritance in a sensible manner
when appropriate.

displayName

An optional string with a human-friendly name of the preset.

description

An optional string with a human-friendly description of the preset.

generator

An optional string representing the generator to use for the preset. If
generator is not specified, it must be inherited from the
inherits preset (unless this preset is hidden). In version 3
or above, this field may be omitted to fall back to regular generator
discovery procedure.

Note that for Visual Studio generators, unlike in the command line
-G argument, you cannot include the platform name
in the generator name. Use the architecture field instead.

architecture, toolset

Optional fields representing the platform and toolset, respectively, for
generators that support them.

See cmake -A option for possible values for architecture
and cmake -T for toolset.

Each may be either a string or an object with the following fields:

value

An optional string representing the value.

strategy

An optional string telling CMake how to handle the architecture or
toolset field. Valid values are:

"set"

Set the respective value. This will result in an error for generators
that do not support the respective field.

"external"

Do not set the value, even if the generator supports it. This is
useful if, for example, a preset uses the Ninja generator, and an IDE
knows how to set up the Visual C++ environment from the
architecture and toolset fields. In that case, CMake will
ignore the field, but the IDE can use them to set up the environment
before invoking CMake.

If no strategy field is given, or if the field uses the string form
rather than the object form, the behavior is the same as "set".

toolchainFile

An optional string representing the path to the toolchain file.
This field supports macro expansion. If a relative path is specified,
it is calculated relative to the build directory, and if not found,
relative to the source directory. This field takes precedence over any
CMAKE_TOOLCHAIN_FILE value. It is allowed in preset files
specifying version 3 or above.

binaryDir

An optional string representing the path to the output binary directory.
This field supports macro expansion. If a relative path is specified,
it is calculated relative to the source directory. If binaryDir is not
specified, it must be inherited from the inherits preset (unless this
preset is hidden). In version 3 or above, this field may be
omitted.

installDir

An optional string representing the path to the installation directory.
This field supports macro expansion. If a relative path is specified,
it is calculated relative to the source directory. This is allowed in
preset files specifying version 3 or above.

cmakeExecutable

An optional string representing the path to the CMake executable to use
for this preset. This is reserved for use by IDEs, and is not used by
CMake itself. IDEs that use this field should expand any macros in it.

cacheVariables

An optional map of cache variables. The key is the variable name (which
may not be an empty string), and the value is either null, a boolean
(which is equivalent to a value of "TRUE" or "FALSE" and a type
of BOOL), a string representing the value of the variable (which
supports macro expansion), or an object with the following fields:

type

An optional string representing the type of the variable.

value

A required string or boolean representing the value of the variable.
A boolean is equivalent to "TRUE" or "FALSE". This field
supports macro expansion.

Cache variables are inherited through the inherits field, and the
preset's variables will be the union of its own cacheVariables and
the cacheVariables from all its parents. If multiple presets in this
union define the same variable, the standard rules of inherits are
applied. Setting a variable to null causes it to not be set, even if
a value was inherited from another preset.

environment

An optional map of environment variables. The key is the variable name
(which may not be an empty string), and the value is either null or
a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example,
if ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)

Environment variables are inherited through the inherits field, and
the preset's environment will be the union of its own environment and
the environment from all its parents. If multiple presets in this
union define the same variable, the standard rules of inherits are
applied. Setting a variable to null causes it to not be set, even if
a value was inherited from another preset.

warnings

An optional object specifying the warnings to enable. The object may
contain the following fields:

dev

An optional boolean. Equivalent to passing -Wdev
or -Wno-dev on the command line. This may not
be set to false if errors.dev is set to true.

deprecated

An optional boolean. Equivalent to passing
-Wdeprecated or
-Wno-deprecated on the command line.
This may not be set to false if errors.deprecated is set to
true.

uninitialized

An optional boolean. Setting this to true is equivalent to passing
--warn-uninitialized on the command
line.

unusedCli

An optional boolean. Setting this to false is equivalent to passing
--no-warn-unused-cli on the command
line.

systemVars

An optional boolean. Setting this to true is equivalent to passing
--check-system-vars on the command
line.

errors

An optional object specifying the errors to enable. The object may
contain the following fields:

dev

An optional boolean. Equivalent to passing -Werror=dev
or -Wno-error=dev on the command line.
This may not be set to true if warnings.dev is set to false.

deprecated

An optional boolean. Equivalent to passing
-Werror=deprecated or
-Wno-error=deprecated on the command line.
This may not be set to true if warnings.deprecated is set to
false.

debug

An optional object specifying debug options. The object may contain the
following fields:

output

An optional boolean. Setting this to true is equivalent to passing
--debug-output on the command line.

tryCompile

An optional boolean. Setting this to true is equivalent to passing
--debug-trycompile on the command
line.

find

An optional boolean. Setting this to true is equivalent to passing
--debug-find on the command line.

trace

An optional object specifying trace options. This is allowed in preset
files specifying version 7. The object may contain the following fields:

mode

An optional string that specifies the trace mode. Valid values are:

on

Causes a trace of all calls made and from where to be printed.
Equivalent to passing --trace on the command
line.

off

A trace of all calls will not be printed.

expand

Causes a trace with variables expanded of all calls made and from where
to be printed. Equivalent to passing --trace-expand
on the command line.

format

An optional string that specifies the format output of the trace.
Valid values are:

human

Prints each trace line in a human-readable format.
This is the default format.  Equivalent to passing
--trace-format=human
on the command line.

json-v1

Prints each line as a separate JSON document.  Equivalent to passing
--trace-format=json-v1
on the command line.

source

An optional array of strings representing the paths of source files to
be traced.  This field can also be a string, which is equivalent to an
array containing one string.  Equivalent to passing
--trace-source on the command line.

redirect

An optional string specifying a path to a trace output file.  Equivalent
to passing --trace-redirect
on the command line.

Build Preset¶

Each entry of the buildPresets array is a JSON object
that may contain the following fields:

name

A required string representing the machine-friendly name of the preset.
This identifier is used in the
cmake --build --preset option.
There must not be two build presets in the union of CMakePresets.json
and CMakeUserPresets.json in the same directory with the same name.
However, a build preset may have the same name as a configure, test,
package, or workflow preset.

hidden

An optional boolean specifying whether or not a preset should be hidden.
If a preset is hidden, it cannot be used in the
--preset argument
and does not have to have a valid configurePreset, even from
inheritance. hidden presets are intended to be used as a base for
other presets to inherit via the inherits field.

inherits

An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.

The preset will inherit all of the fields from the
inherits presets by default (except name, hidden,
inherits, description, and displayName), but can override
them as desired. If multiple inherits presets provide conflicting
values for the same field, the earlier preset in the inherits array
will be preferred.

A preset can only inherit from another preset that is defined in the
same file or in one of the files it includes (directly or indirectly).
Presets in CMakePresets.json may not inherit from presets in
CMakeUserPresets.json.

condition

An optional Condition object. This is allowed in preset files specifying
version 3 or above.

vendor

An optional map containing vendor-specific information. CMake does not
interpret the contents of this field except to verify that it is a map
if it does exist. However, it should follow the same conventions as the
root-level vendor field. If vendors use their own per-preset
vendor field, they should implement inheritance in a sensible manner
when appropriate.

displayName

An optional string with a human-friendly name of the preset.

description

An optional string with a human-friendly description of the preset.

environment

An optional map of environment variables. The key is the variable name
(which may not be an empty string), and the value is either null or
a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if
ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)

Environment variables are inherited through the inherits field, and
the preset's environment will be the union of its own environment
and the environment from all its parents. If multiple presets in
this union define the same variable, the standard rules of inherits
are applied. Setting a variable to null causes it to not be set,
even if a value was inherited from another preset.

Note

For a CMake project using ExternalProject with a configuration preset
having environment variables needed in the ExternalProject, use a build
preset that inherits that configuration preset or the ExternalProject
will not have the environment variables set in the configuration preset.
Example: suppose the host defaults to one compiler (say Clang)
and the user wishes to use another compiler (say GCC). Set configuration
preset environment variables CC and CXX and use a build preset
that inherits that configuration preset. Otherwise the ExternalProject
may use a different (system default) compiler than the top-level CMake
project.

configurePreset

An optional string specifying the name of a configure preset to
associate with this build preset. If configurePreset is not
specified, it must be inherited from the inherits preset (unless this
preset is hidden). The build directory is inferred from the configure
preset, so the build will take place in the same binaryDir that the
configuration did.

inheritConfigureEnvironment

An optional boolean that defaults to true. If true, the environment
variables from the associated configure preset are inherited after all
inherited build preset environments, but before environment variables
explicitly specified in this build preset.

jobs

An optional integer. Equivalent to passing
--parallel or -j on the command line.

targets

An optional string or array of strings. Equivalent to passing
--target or -t on the command line.
Vendors may ignore the targets property or hide build presets that
explicitly specify targets. This field supports macro expansion.

configuration

An optional string. Equivalent to passing
--config on the command line.

cleanFirst

An optional bool. If true, equivalent to passing
--clean-first on the command line.

resolvePackageReferences

An optional string that specifies the package resolve mode. This is
allowed in preset files specifying version 4 or above.

Package references are used to define dependencies to packages from
external package managers. Currently only NuGet in combination with the
Visual Studio generator is supported. If there are no targets that define
package references, this option does nothing. Valid values are:

on

Causes package references to be resolved before attempting a build.

off

Package references will not be resolved. Note that this may cause
errors in some build environments, such as .NET SDK style projects.

only

Only resolve package references, but do not perform a build.

Note

The command line parameter
--resolve-package-references
will take priority over this setting. If the command line parameter is not
provided and this setting is not specified, an environment-specific cache
variable will be evaluated to decide, if package restoration should be
performed.

When using the Visual Studio generator, package references are defined
using the VS_PACKAGE_REFERENCES property. Package references
are restored using NuGet. It can be disabled by setting the
CMAKE_VS_NUGET_PACKAGE_RESTORE variable to OFF. This can also be
done from within a configure preset.

verbose

An optional bool. If true, equivalent to passing
--verbose on the command line.

nativeToolOptions

An optional array of strings. Equivalent to passing options after --
on the command line. The array values support macro expansion.

Test Preset¶

Each entry of the testPresets array is a JSON object
that may contain the following fields:

name

A required string representing the machine-friendly name of the preset.
This identifier is used in the ctest --preset option.
There must not be two test presets in the union of CMakePresets.json
and CMakeUserPresets.json in the same directory with the same name.
However, a test preset may have the same name as a configure, build,
package, or workflow preset.

hidden

An optional boolean specifying whether or not a preset should be hidden.
If a preset is hidden, it cannot be used in the
--preset argument
and does not have to have a valid configurePreset, even from
inheritance. hidden presets are intended to be used as a base for
other presets to inherit via the inherits field.

inherits

An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.

The preset will inherit all of the fields from the
inherits presets by default (except name, hidden,
inherits, description, and displayName), but can override
them as desired. If multiple inherits presets provide conflicting
values for the same field, the earlier preset in the inherits array
will be preferred.

A preset can only inherit from another preset that is defined in the
same file or in one of the files it includes (directly or indirectly).
Presets in CMakePresets.json may not inherit from presets in
CMakeUserPresets.json.

condition

An optional Condition object. This is allowed in preset files specifying
version 3 or above.

vendor

An optional map containing vendor-specific information. CMake does not
interpret the contents of this field except to verify that it is a map
if it does exist. However, it should follow the same conventions as the
root-level vendor field. If vendors use their own per-preset
vendor field, they should implement inheritance in a sensible manner
when appropriate.

displayName

An optional string with a human-friendly name of the preset.

description

An optional string with a human-friendly description of the preset.

environment

An optional map of environment variables. The key is the variable name
(which may not be an empty string), and the value is either null or
a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if
ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)

Environment variables are inherited through the inherits field, and
the preset's environment will be the union of its own environment
and the environment from all its parents. If multiple presets in
this union define the same variable, the standard rules of inherits
are applied. Setting a variable to null causes it to not be set,
even if a value was inherited from another preset.

configurePreset

An optional string specifying the name of a configure preset to
associate with this test preset. If configurePreset is not
specified, it must be inherited from the inherits preset (unless this
preset is hidden). The build directory is inferred from the configure
preset, so tests will run in the same binaryDir that the
configuration did and build did.

inheritConfigureEnvironment

An optional boolean that defaults to true. If true, the environment
variables from the associated configure preset are inherited after all
inherited test preset environments, but before environment variables
explicitly specified in this test preset.

configuration

An optional string. Equivalent to passing
--build-config on the command line.

overwriteConfigurationFile

An optional array of configuration options to overwrite options
specified in the CTest configuration file. Equivalent to passing
--overwrite for each value in the array.
The array values support macro expansion.

output

An optional object specifying output options. The object may contain the
following fields.

shortProgress

An optional bool. If true, equivalent to passing
--progress on the command line.

verbosity

An optional string specifying verbosity level. Must be one of the
following:

default

Equivalent to passing no verbosity flags on the command line.

verbose

Equivalent to passing --verbose on
the command line.

extra

Equivalent to passing --extra-verbose
on the command line.

debug

An optional bool. If true, equivalent to passing
--debug on the command line.

outputOnFailure

An optional bool. If true, equivalent to passing
--output-on-failure on the command
line.

quiet

An optional bool. If true, equivalent to passing
--quiet on the command line.

outputLogFile

An optional string specifying a path to a log file. Equivalent to
passing --output-log on the command line.
This field supports macro expansion.

outputJUnitFile

An optional string specifying a path to a JUnit file. Equivalent to
passing --output-junit on the command line.
This field supports macro expansion. This is allowed in preset files
specifying version 6 or above.

labelSummary

An optional bool. If false, equivalent to passing
--no-label-summary on the command
line.

subprojectSummary

An optional bool. If false, equivalent to passing
--no-subproject-summary
on the command line.

maxPassedTestOutputSize

An optional integer specifying the maximum output for passed tests in
bytes. Equivalent to passing
--test-output-size-passed
on the command line.

maxFailedTestOutputSize

An optional integer specifying the maximum output for failed tests in
bytes. Equivalent to passing
--test-output-size-failed
on the command line.

testOutputTruncation

An optional string specifying the test output truncation mode. Equivalent
to passing
--test-output-truncation on
the command line. This is allowed in preset files specifying version
5 or above.

maxTestNameWidth

An optional integer specifying the maximum width of a test name to
output. Equivalent to passing --max-width
on the command line.

filter

An optional object specifying how to filter the tests to run. The object
may contain the following fields.

include

An optional object specifying which tests to include. The object may
contain the following fields.

name

An optional string specifying a regex for test names. Equivalent to
passing --tests-regex on the command
line. This field supports macro expansion. CMake regex syntax is
described under string(REGEX).

label

An optional string specifying a regex for test labels. Equivalent to
passing --label-regex on the command
line. This field supports macro expansion.

useUnion

An optional bool. Equivalent to passing --union
on the command line.

index

An optional object specifying tests to include by test index. The
object may contain the following fields. Can also be an optional
string specifying a file with the command line syntax for
--tests-information.
If specified as a string, this field supports macro expansion.

start

An optional integer specifying a test index to start testing at.

end

An optional integer specifying a test index to stop testing at.

stride

An optional integer specifying the increment.

specificTests

An optional array of integers specifying specific test indices to
run.

exclude

An optional object specifying which tests to exclude. The object may
contain the following fields.

name

An optional string specifying a regex for test names. Equivalent to
passing --exclude-regex on the
command line. This field supports macro expansion.

label

An optional string specifying a regex for test labels. Equivalent to
passing --label-exclude on the
command line. This field supports macro expansion.

fixtures

An optional object specifying which fixtures to exclude from adding
tests. The object may contain the following fields.

any

An optional string specifying a regex for text fixtures to exclude
from adding any tests. Equivalent to
--fixture-exclude-any on
the command line. This field supports macro expansion.

setup

An optional string specifying a regex for text fixtures to exclude
from adding setup tests. Equivalent to
--fixture-exclude-setup
on the command line. This field supports macro expansion.

cleanup

An optional string specifying a regex for text fixtures to exclude
from adding cleanup tests. Equivalent to
--fixture-exclude-cleanup
on the command line. This field supports macro expansion.

execution

An optional object specifying options for test execution. The object may
contain the following fields.

stopOnFailure

An optional bool. If true, equivalent to passing
--stop-on-failure on the command
line.

enableFailover

An optional bool. If true, equivalent to passing -F
on the command line.

jobs

An optional integer. Equivalent to passing
--parallel on the command line.

resourceSpecFile

An optional string. Equivalent to passing
--resource-spec-file on
the command line. This field supports macro expansion.

testLoad

An optional integer. Equivalent to passing
--test-load on the command line.

showOnly

An optional string. Equivalent to passing
--show-only on the
command line. The string must be one of the following values:

human

json-v1

repeat

An optional object specifying how to repeat tests. Equivalent to
passing --repeat on the command line.
The object must have the following fields.

mode

A required string. Must be one of the following values:

until-fail

until-pass

after-timeout

count

A required integer.

interactiveDebugging

An optional bool. If true, equivalent to passing
--interactive-debug-mode 1
on the command line. If false, equivalent to passing
--interactive-debug-mode 0
on the command line.

scheduleRandom

An optional bool. If true, equivalent to passing
--schedule-random on the command
line.

timeout

An optional integer. Equivalent to passing
--timeout on the command line.

noTestsAction

An optional string specifying the behavior if no tests are found. Must
be one of the following values:

default

Equivalent to not passing any value on the command line.

error

Equivalent to passing --no-tests=error
on the command line.

ignore

Equivalent to passing --no-tests=ignore
on the command line.

Package Preset¶

Package presets may be used in schema version 6 or above. Each entry of
the packagePresets array is a JSON object that may contain the following
fields:

name

A required string representing the machine-friendly name of the preset.
This identifier is used in the cpack --preset option.
There must not be two package presets in the union of CMakePresets.json
and CMakeUserPresets.json in the same directory with the same name.
However, a package preset may have the same name as a configure, build,
test, or workflow preset.

hidden

An optional boolean specifying whether or not a preset should be hidden.
If a preset is hidden, it cannot be used in the
--preset argument
and does not have to have a valid configurePreset, even from
inheritance. hidden presets are intended to be used as a base for
other presets to inherit via the inherits field.

inherits

An optional array of strings representing the names of presets to inherit
from. This field can also be a string, which is equivalent to an array
containing one string.

The preset will inherit all of the fields from the
inherits presets by default (except name, hidden,
inherits, description, and displayName), but can override
them as desired. If multiple inherits presets provide conflicting
values for the same field, the earlier preset in the inherits array
will be preferred.

A preset can only inherit from another preset that is defined in the
same file or in one of the files it includes (directly or indirectly).
Presets in CMakePresets.json may not inherit from presets in
CMakeUserPresets.json.

condition

An optional Condition object.

vendor

An optional map containing vendor-specific information. CMake does not
interpret the contents of this field except to verify that it is a map
if it does exist. However, it should follow the same conventions as the
root-level vendor field. If vendors use their own per-preset
vendor field, they should implement inheritance in a sensible manner
when appropriate.

displayName

An optional string with a human-friendly name of the preset.

description

An optional string with a human-friendly description of the preset.

environment

An optional map of environment variables. The key is the variable name
(which may not be an empty string), and the value is either null or
a string representing the value of the variable. Each variable is set
regardless of whether or not a value was given to it by the process's
environment. This field supports macro expansion, and environment
variables in this map may reference each other, and may be listed in any
order, as long as such references do not cause a cycle (for example, if
ENV_1 is $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)

Environment variables are inherited through the inherits field, and
the preset's environment will be the union of its own environment
and the environment from all its parents. If multiple presets in
this union define the same variable, the standard rules of inherits
are applied. Setting a variable to null causes it to not be set,
even if a value was inherited from another preset.

configurePreset

An optional string specifying the name of a configure preset to
associate with this package preset. If configurePreset is not
specified, it must be inherited from the inherits preset (unless this
preset is hidden). The build directory is inferred from the configure
preset, so packaging will run in the same binaryDir that the
configuration did and build did.

inheritConfigureEnvironment

An optional boolean that defaults to true. If true, the environment
variables from the associated configure preset are inherited after all
inherited package preset environments, but before environment variables
explicitly specified in this package preset.

generators

An optional array of strings representing generators for CPack to use.

configurations

An optional array of strings representing build configurations for CPack to
package.

variables

An optional map of variables to pass to CPack, equivalent to
-D arguments. Each key is the name of a variable, and
the value is the string to assign to that variable.

configFile

An optional string representing the config file for CPack to use.

output

An optional object specifying output options. Valid keys are:

debug

An optional boolean specifying whether or not to print debug information.
A value of true is equivalent to passing
--debug on the command line.

verbose

An optional boolean specifying whether or not to print verbosely. A value
of true is equivalent to passing --verbose
on the command line.

packageName

An optional string representing the package name.

packageVersion

An optional string representing the package version.

packageDirectory

An optional string representing the directory in which to place the package.

vendorName

An optional string representing the vendor name.

Workflow Preset¶

Workflow presets may be used in schema version 6 or above. Each entry of
the workflowPresets array is a JSON object that may contain the following
fields:

name

A required string representing the machine-friendly name of the preset.
This identifier is used in the
cmake --workflow --preset option. There must not be
two workflow presets in the union of CMakePresets.json and
CMakeUserPresets.json in the same directory with the same name. However,
a workflow preset may have the same name as a configure, build, test, or
package preset.

vendor

An optional map containing vendor-specific information. CMake does not
interpret the contents of this field except to verify that it is a map
if it does exist. However, it should follow the same conventions as the
root-level vendor field.

displayName

An optional string with a human-friendly name of the preset.

description

An optional string with a human-friendly description of the preset.

steps

A required array of objects describing the steps of the workflow. The first
step must be a configure preset, and all subsequent steps must be non-
configure presets whose configurePreset field matches the starting
configure preset. Each object may contain the following fields:

type

A required string. The first step must be configure. Subsequent steps
must be either build, test, or package.

name

A required string representing the name of the configure, build, test, or
package preset to run as this workflow step.

Condition¶

The condition field of a preset, allowed in preset files specifying version
3 or above, is used to determine whether or not the preset is enabled. For
example, this can be used to disable a preset on platforms other than Windows.
condition may be either a boolean, null, or an object. If it is a
boolean, the boolean indicates whether the preset is enabled or disabled. If it
is null, the preset is enabled, but the null condition is not inherited
by any presets that may inherit from the preset. Sub-conditions (for example in
a not, anyOf, or allOf condition) may not be null. If it is an
object, it has the following fields:

type

A required string with one of the following values:

"const"

Indicates that the condition is constant. This is equivalent to using a
boolean in place of the object. The condition object will have the
following additional fields:

value

A required boolean which provides a constant value for the condition's
evaluation.

"equals"

"notEquals"

Indicates that the condition compares two strings to see if they are equal
(or not equal). The condition object will have the following additional
fields:

lhs

First string to compare. This field supports macro expansion.

rhs

Second string to compare. This field supports macro expansion.

"inList"

"notInList"

Indicates that the condition searches for a string in a list of strings.
The condition object will have the following additional fields:

string

A required string to search for. This field supports macro expansion.

list

A required array of strings to search. This field supports macro
expansion, and uses short-circuit evaluation.

"matches"

"notMatches"

Indicates that the condition searches for a regular expression in a string.
The condition object will have the following additional fields:

string

A required string to search. This field supports macro expansion.

regex

A required regular expression to search for. This field supports macro
expansion.

"anyOf"

"allOf"

Indicates that the condition is an aggregation of zero or more nested
conditions. The condition object will have the following additional fields:

conditions

A required array of condition objects. These conditions use short-circuit
evaluation.

"not"

Indicates that the condition is an inversion of another condition. The
condition object will have the following additional fields:

condition

A required condition object.

Macro Expansion¶

As mentioned above, some fields support macro expansion. Macros are
recognized in the form $<macro-namespace>{<macro-name>}. All macros are
evaluated in the context of the preset being used, even if the macro is in a
field that was inherited from another preset. For example, if the Base
preset sets variable PRESET_NAME to ${presetName}, and the
Derived preset inherits from Base, PRESET_NAME will be set to
Derived.

It is an error to not put a closing brace at the end of a macro name. For
example, ${sourceDir is invalid. A dollar sign ($) followed by
anything other than a left curly brace ({) with a possible namespace is
interpreted as a literal dollar sign.

Recognized macros include:

${sourceDir}

Path to the project source directory (i.e. the same as
CMAKE_SOURCE_DIR).

${sourceParentDir}

Path to the project source directory's parent directory.

${sourceDirName}

The last filename component of ${sourceDir}. For example, if
${sourceDir} is /path/to/source, this would be source.

${presetName}

Name specified in the preset's name field.

${generator}

Generator specified in the preset's generator field. For build and
test presets, this will evaluate to the generator specified by
configurePreset.

${hostSystemName}

The name of the host operating system. Contains the same value as
CMAKE_HOST_SYSTEM_NAME. This is allowed in preset files
specifying version 3 or above.

${fileDir}

Path to the directory containing the preset file which contains the macro.
This is allowed in preset files specifying version 4 or above.

${dollar}

A literal dollar sign ($).

${pathListSep}

Native character for separating lists of paths, such as : or ;.

For example, by setting PATH to
/path/to/ninja/bin${pathListSep}$env{PATH}, ${pathListSep} will
expand to the underlying operating system's character used for
concatenation in PATH.

This is allowed in preset files specifying version 5 or above.

$env{<variable-name>}

Environment variable with name <variable-name>. The variable name may
not be an empty string. If the variable is defined in the environment
field, that value is used instead of the value from the parent environment.
If the environment variable is not defined, this evaluates as an empty
string.

Note that while Windows environment variable names are case-insensitive,
variable names within a preset are still case-sensitive. This may lead to
unexpected results when using inconsistent casing. For best results, keep
the casing of environment variable names consistent.

$penv{<variable-name>}

Similar to $env{<variable-name>}, except that the value only comes from
the parent environment, and never from the environment field. This
allows you to prepend or append values to existing environment variables.
For example, setting PATH to /path/to/ninja/bin:$penv{PATH} will
prepend /path/to/ninja/bin to the PATH environment variable. This
is needed because $env{<variable-name>} does not allow circular
references.

$vendor{<macro-name>}

An extension point for vendors to insert their own macros. CMake will not
be able to use presets which have a $vendor{<macro-name>} macro, and
effectively ignores such presets. However, it will still be able to use
other presets from the same file.

CMake does not make any attempt to interpret $vendor{<macro-name>}
macros. However, to avoid name collisions, IDE vendors should prefix
<macro-name> with a very short (preferably <= 4 characters) vendor
identifier prefix, followed by a ., followed by the macro name. For
example, the Example IDE could have $vendor{xide.ideInstallDir}.

Schema¶

This file provides a machine-readable
JSON schema for the CMakePresets.json format.

Table of Contents

cmake-presets(7)

Introduction

Format

Includes

Configure Preset

Build Preset

Test Preset

Package Preset

Workflow Preset

Condition

Macro Expansion

Schema

Previous topic

CMP0000

Next topic

cmake-properties(7)

This Page

Show Source

Quick search

    <form class="search" action="../search.html" method="get">
      <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
      <input type="submit" value="Go" />
    </form>

Navigation

          index

          next |

          previous |

    CMake »

    3.29.0-rc3 Documentation »

cmake-presets(7)

        © Copyright 2000-2024 Kitware, Inc. and Contributors.
      Created using Sphinx 6.2.1.