| CMAKE-PRESETS(7) | CMake | CMAKE-PRESETS(7) |
cmake-presets - CMakePresets.json
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.
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:
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.
Each entry of the configurePresets array is a JSON object that may contain the following fields:
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.
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.
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:
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".
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 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.
Each entry of the buildPresets array is a JSON object that may contain the following fields:
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.
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:
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:
NOTE:
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.
Each entry of the testPresets array is a JSON object that may contain the following fields:
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.
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.
human
json-v1
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:
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.
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.
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:
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:
"equals"
"inList"
"matches"
"anyOf"
"allOf"
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:
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.
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.
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}.
This file provides a machine-readable JSON schema for the CMakePresets.json format.
2000-2024 Kitware, Inc. and Contributors
| April 15, 2024 | 3.28.3 |