1CMAKE-PRESETS(7) CMake CMAKE-PRESETS(7)
2
6 cmake-presets - CMakePresets.json
7
9 One problem that CMake users often face is sharing settings with other
10 people for common ways to configure a project. This may be done to sup‐
11 port CI builds, or for users who frequently use the same build. CMake
12 supports two files, CMakePresets.json and CMakeUserPresets.json, that
13 allow users to specify common configure options and share them with
14 others.
15 CMakePresets.json and CMakeUserPresets.json live in the project’s root
17 directory. They both have exactly the same format, and both are
18 optional (though at least one must be present if --preset is speci‐
19 fied.) CMakePresets.json is meant to save project-wide builds, while
20 CMakeUserPresets.json is meant for developers to save their own local
21 builds. CMakePresets.json may be checked into a version control system,
22 and CMakeUserPresets.json should NOT be checked in. For example, if a
23 project is using Git, CMakePresets.json may be tracked, and CMakeUserP‐
24 resets.json should be added to the .gitignore.
25
27 The files are a JSON document with an object as the root:
28 {
30 "version": 1,
31 "cmakeMinimumRequired": {
32 "major": 3,
33 "minor": 19,
34 "patch": 0
35 },
36 "configurePresets": [
37 {
38 "name": "default",
39 "displayName": "Default Config",
40 "description": "Default build using Ninja generator",
41 "generator": "Ninja",
42 "binaryDir": "${sourceDir}/build/default",
43 "cacheVariables": {
44 "FIRST_CACHE_VARIABLE": {
45 "type": "BOOL",
46 "value": "OFF"
47 },
48 "SECOND_CACHE_VARIABLE": "ON"
49 },
50 "environment": {
51 "MY_ENVIRONMENT_VARIABLE": "Test",
52 "PATH": "$env{HOME}/ninja/bin:$penv{PATH}"
53 },
54 "vendor": {
55 "example.com/ExampleIDE/1.0": {
56 "autoFormat": true
57 }
58 }
59 },
60 {
61 "name": "ninja-multi",
62 "inherits": "default",
63 "displayName": "Ninja Multi-Config",
64 "description": "Default build using Ninja Multi-Config generator",
65 "generator": "Ninja Multi-Config"
66 }
67 ],
68 "vendor": {
69 "example.com/ExampleIDE/1.0": {
70 "autoFormat": false
71 }
72 }
73 }
74 The root object recognizes the following fields:
77 version
79 A required integer representing the version of the JSON schema.
80 Currently, the only supported version is 1.
81 cmakeMinimumRequired
83 An optional object representing the minimum version of CMake
84 needed to build this project. This object consists of the fol‐
85 lowing fields:
86 major
88 An optional integer representing the major version.
89 minor
91 An optional integer representing the minor version.
92 patch
94 An optional integer representing the patch version.
95 vendor
97 An optional map containing vendor-specific information. CMake
98 does not interpret the contents of this field except to verify
99 that it is a map if it does exist. However, the keys should be a
100 vendor-specific domain name followed by a /-separated path. For
101 example, the Example IDE 1.0 could use example.com/Exam‐
102 pleIDE/1.0. The value of each field can be anything desired by
103 the vendor, though will typically be a map.
104 configurePresets
106 An optional array of configure preset objects. Each preset may
107 contain the following fields:
108 name
110 A required string representing the machine-friendly name of
111 the preset. This identifier is used in the --preset argu‐
112 ment. There must not be two presets in the union of CMakePre‐
113 sets.json and CMakeUserPresets.json in the same directory
114 with the same name.
115 hidden
117 An optional boolean specifying whether or not a preset should
118 be hidden. If a preset is hidden, it cannot be used in the
119 --preset= argument, will not show up in the CMake GUI, and
120 does not have to have a valid generator or binaryDir, even
121 from inheritance. hidden presets are intended to be used as a
122 base for other presets to inherit via the inherits field.
123 inherits
125 An optional array of strings representing the names of pre‐
126 sets to inherit from. The preset will inherit all of the
127 fields from the inherits presets by default (except name,
128 hidden, inherits, description, and displayName), but can
129 override them as desired. If multiple inherits presets pro‐
130 vide conflicting values for the same field, the earlier pre‐
131 set in the inherits list will be preferred. Presets in
132 CMakePresets.json may not inherit from presets in CMakeUserP‐
133 resets.json.
134 This field can also be a string, which is equivalent to an
136 array containing one string.
137 vendor
139 An optional map containing vendor-specific information. CMake
140 does not interpret the contents of this field except to ver‐
141 ify that it is a map if it does exist. However, it should
142 follow the same conventions as the root-level vendor field.
143 If vendors use their own per-preset vendor field, they should
144 implement inheritance in a sensible manner when appropriate.
145 displayName
147 An optional string with a human-friendly name of the preset.
148 description
150 An optional string with a human-friendly description of the
151 preset.
152 generator
154 An optional string representing the generator to use for the
155 preset. If generator is not specified, it must be inherited
156 from the inherits preset (unless this preset is hidden).
157 Note that for Visual Studio generators, unlike in the command
159 line -G argument, you cannot include the platform name in the
160 generator name. Use the architecture field instead.
161 architecture toolset
163 Optional fields representing the platform and toolset,
164 respectively, for generators that support them. Each may be
165 either a string or an object with the following fields:
166 value
168 An optional string representing the value.
169 strategy
171 An optional string telling CMake how to handle the archi‐
172 tecture or toolset field. Valid values are:
173 "set"
175 Set the respective value. This will result in an error
176 for generators that do not support the respective
177 field.
178 "external"
180 Do not set the value, even if the generator supports
181 it. This is useful if, for example, a preset uses the
182 Ninja generator, and an IDE knows how to set up the
183 Visual C++ environment from the architecture and
184 toolset fields. In that case, CMake will ignore the
185 field, but the IDE can use them to set up the environ‐
186 ment before invoking CMake.
187 binaryDir
189 An optional string representing the path to the output binary
190 directory. This field supports macro expansion. If a rela‐
191 tive path is specified, it is calculated relative to the
192 source directory. If binaryDir is not specified, it must be
193 inherited from the inherits preset (unless this preset is
194 hidden).
195 cmakeExecutable
197 An optional string representing the path to the CMake exe‐
198 cutable to use for this preset. This is reserved for use by
199 IDEs, and is not used by CMake itself. IDEs that use this
200 field should expand any macros in it.
201 cacheVariables
203 An optional map of cache variables. The key is the variable
204 name (which may not be an empty string), and the value is
205 either null, a boolean (which is equivalent to a value of
206 "TRUE" or "FALSE" and a type of BOOL), a string representing
207 the value of the variable (which supports macro expansion),
208 or an object with the following fields:
209 type
211 An optional string representing the type of the variable.
212 value
214 A required string or boolean representing the value of
215 the variable. A boolean is equivalent to "TRUE" or
216 "FALSE". This field supports macro expansion.
217 Cache variables are inherited through the inherits field, and
219 the preset’s variables will be the union of its own
220 cacheVariables and the cacheVariables from all its parents.
221 If multiple presets in this union define the same variable,
222 the standard rules of inherits are applied. Setting a vari‐
223 able to null causes it to not be set, even if a value was
224 inherited from another preset.
225 environment
227 An optional map of environment variables. The key is the
228 variable name (which may not be an empty string), and the
229 value is either null or a string representing the value of
230 the variable. Each variable is set regardless of whether or
231 not a value was given to it by the process’s environment.
232 This field supports macro expansion, and environment vari‐
233 ables in this map may reference each other, and may be listed
234 in any order, as long as such references do not cause a cycle
235 (for example, if ENV_1 is $env{ENV_2}, ENV_2 may not be
236 $env{ENV_1}.)
237 Environment variables are inherited through the inherits
239 field, and the preset’s environment will be the union of its
240 own environment and the environment from all its parents. If
241 multiple presets in this union define the same variable, the
242 standard rules of inherits are applied. Setting a variable to
243 null causes it to not be set, even if a value was inherited
244 from another preset.
245 warnings
247 An optional object specifying the warnings to enable. The
248 object may contain the following fields:
249 dev
251 An optional boolean. Equivalent to passing -Wdev or
252 -Wno-dev on the command line. This may not be set to
253 false if errors.dev is set to true.
254 deprecated
256 An optional boolean. Equivalent to passing -Wdeprecated
257 or -Wno-deprecated on the command line. This may not be
258 set to false if errors.deprecated is set to true.
259 uninitialized
261 An optional boolean. Setting this to true is equivalent
262 to passing --warn-uninitialized on the command line.
263 unusedCli
265 An optional boolean. Setting this to false is equivalent
266 to passing --no-warn-unused-cli on the command line.
267 systemVars
269 An optional boolean. Setting this to true is equivalent
270 to passing --check-system-vars on the command line.
271 errors
273 An optional object specifying the errors to enable. The
274 object may contain the following fields:
275 dev
277 An optional boolean. Equivalent to passing -Werror=dev or
278 -Wno-error=dev on the command line. This may not be set
279 to true if warnings.dev is set to false.
280 deprecated
282 An optional boolean. Equivalent to passing -Werror=depre‐
283 cated or -Wno-error=deprecated on the command line. This
284 may not be set to true if warnings.deprecated is set to
285 false.
286 debug
288 An optional object specifying debug options. The object may
289 contain the following fields:
290 output
292 An optional boolean. Setting this to true is equivalent
293 to passing --debug-output on the command line.
294 tryCompile
296 An optional boolean. Setting this to true is equivalent
297 to passing --debug-trycompile on the command line.
298 find
300 An optional boolean. Setting this to true is equivalent
301 to passing --debug-find on the command line.
302 As mentioned above, some fields support macro expansion. Macros are
304 recognized in the form $<macro-namespace>{<macro-name>}. All macros
305 are evaluated in the context of the preset being used, even if the
306 macro is in a field that was inherited from another preset. For
307 example, if the Base preset sets variable PRESET_NAME to ${preset‐
308 Name}, and the Derived preset inherits from Base, PRESET_NAME will
309 be set to Derived.
310 It is an error to not put a closing brace at the end of a macro
312 name. For example, ${sourceDir is invalid. A dollar sign ($) fol‐
313 lowed by anything other than a left curly brace ({) with a possible
314 namespace is interpreted as a literal dollar sign.
315 Recognized macros include:
317 ${sourceDir}
319 Path to the project source directory.
320 ${sourceParentDir}
322 Path to the project source directory’s parent directory.
323 ${sourceDirName}
325 The last filename component of ${sourceDir}. For example, if
326 ${sourceDir} is /path/to/source, this would be source.
327 ${presetName}
329 Name specified in the preset’s name field.
330 ${generator}
332 Generator specified in the preset’s generator field.
333 ${dollar}
335 A literal dollar sign ($).
336 $env{<variable-name>}
338 Environment variable with name <variable-name>. The variable
339 name may not be an empty string. If the variable is defined in
340 the environment field, that value is used instead of the value
341 from the parent environment. If the environment variable is not
342 defined, this evaluates as an empty string.
343 Note that while Windows environment variable names are
345 case-insensitive, variable names within a preset are still
346 case-sensitive. This may lead to unexpected results when using
347 inconsistent casing. For best results, keep the casing of envi‐
348 ronment variable names consistent.
349 $penv{<variable-name>}
351 Similar to $env{<variable-name>}, except that the value only
352 comes from the parent environment, and never from the environ‐
353 ment field. This allows you to prepend or append values to
354 existing environment variables. For example, setting PATH to
355 /path/to/ninja/bin:$penv{PATH} will prepend /path/to/ninja/bin
356 to the PATH environment variable. This is needed because
357 $env{<variable-name>} does not allow circular references.
358 $vendor{<macro-name>}
360 An extension point for vendors to insert their own macros. CMake
361 will not be able to use presets which have a $ven‐
362 dor{<macro-name>} macro, and effectively ignores such presets.
363 However, it will still be able to use other presets from the
364 same file.
365 CMake does not make any attempt to interpret $ven‐
367 dor{<macro-name>} macros. However, to avoid name collisions, IDE
368 vendors should prefix <macro-name> with a very short (preferably
369 <= 4 characters) vendor identifier prefix, followed by a ., fol‐
370 lowed by the macro name. For example, the Example IDE could have
371 $vendor{xide.ideInstallDir}.
372
374 This file provides a machine-readable JSON schema for the CMakePre‐
375 sets.json format.
376
378 2000-2021 Kitware, Inc. and Contributors
3793.19.7 Mar 15, 2021 CMAKE-PRESETS(7)