1CMAKE-PRESETS(7) CMake CMAKE-PRESETS(7)
2
6 cmake-presets - CMakePresets.json
7
9 New in version 3.19.
10 One problem that CMake users often face is sharing settings with other
13 people for common ways to configure a project. This may be done to sup‐
14 port CI builds, or for users who frequently use the same build. CMake
15 supports two main files, CMakePresets.json and CMakeUserPresets.json,
16 that allow users to specify common configure options and share them
17 with others. CMake also supports files included with the include field.
18 CMakePresets.json and CMakeUserPresets.json live in the project's root
20 directory. They both have exactly the same format, and both are op‐
21 tional (though at least one must be present if --preset is specified).
22 CMakePresets.json is meant to specify project-wide build details, while
23 CMakeUserPresets.json is meant for developers to specify their own lo‐
24 cal build details.
25 CMakePresets.json may be checked into a version control system, and
27 CMakeUserPresets.json should NOT be checked in. For example, if a
28 project is using Git, CMakePresets.json may be tracked, and CMakeUserP‐
29 resets.json should be added to the .gitignore.
30
32 The files are a JSON document with an object as the root:
33 {
35 "version": 6,
36 "cmakeMinimumRequired": {
37 "major": 3,
38 "minor": 23,
39 "patch": 0
40 },
41 "include": [
42 "otherThings.json",
43 "moreThings.json"
44 ],
45 "configurePresets": [
46 {
47 "name": "default",
48 "displayName": "Default Config",
49 "description": "Default build using Ninja generator",
50 "generator": "Ninja",
51 "binaryDir": "${sourceDir}/build/default",
52 "cacheVariables": {
53 "FIRST_CACHE_VARIABLE": {
54 "type": "BOOL",
55 "value": "OFF"
56 },
57 "SECOND_CACHE_VARIABLE": "ON"
58 },
59 "environment": {
60 "MY_ENVIRONMENT_VARIABLE": "Test",
61 "PATH": "$env{HOME}/ninja/bin:$penv{PATH}"
62 },
63 "vendor": {
64 "example.com/ExampleIDE/1.0": {
65 "autoFormat": true
66 }
67 }
68 },
69 {
70 "name": "ninja-multi",
71 "inherits": "default",
72 "displayName": "Ninja Multi-Config",
73 "description": "Default build using Ninja Multi-Config generator",
74 "generator": "Ninja Multi-Config"
75 },
76 {
77 "name": "windows-only",
78 "inherits": "default",
79 "displayName": "Windows-only configuration",
80 "description": "This build is only available on Windows",
81 "condition": {
82 "type": "equals",
83 "lhs": "${hostSystemName}",
84 "rhs": "Windows"
85 }
86 }
87 ],
88 "buildPresets": [
89 {
90 "name": "default",
91 "configurePreset": "default"
92 }
93 ],
94 "testPresets": [
95 {
96 "name": "default",
97 "configurePreset": "default",
98 "output": {"outputOnFailure": true},
99 "execution": {"noTestsAction": "error", "stopOnFailure": true}
100 }
101 ],
102 "packagePresets": [
103 {
104 "name": "default",
105 "configurePreset": "default",
106 "generators": [
107 "TGZ"
108 ]
109 }
110 ],
111 "workflowPresets": [
112 {
113 "name": "default",
114 "steps": [
115 {
116 "type": "configure",
117 "name": "default"
118 },
119 {
120 "type": "build",
121 "name": "default"
122 },
123 {
124 "type": "test",
125 "name": "default"
126 },
127 {
128 "type": "package",
129 "name": "default"
130 }
131 ]
132 }
133 ],
134 "vendor": {
135 "example.com/ExampleIDE/1.0": {
136 "autoFormat": false
137 }
138 }
139 }
140 The root object recognizes the following fields:
143 version
145 A required integer representing the version of the JSON schema.
146 The supported versions are:
147 1 New in version 3.19.
149 2 New in version 3.20.
152 3 New in version 3.21.
155 4 New in version 3.23.
158 5 New in version 3.24.
161 6 New in version 3.25.
164 cmakeMinimumRequired
167 An optional object representing the minimum version of CMake
168 needed to build this project. This object consists of the fol‐
169 lowing fields:
170 major An optional integer representing the major version.
172 minor An optional integer representing the minor version.
174 patch An optional integer representing the patch version.
176 include
178 An optional array of strings representing files to include. If
179 the filenames are not absolute, they are considered relative to
180 the current file. This is allowed in preset files specifying
181 version 4 or above. See Includes for discussion of the con‐
182 straints on included files.
183 vendor An optional map containing vendor-specific information. CMake
185 does not interpret the contents of this field except to verify
186 that it is a map if it does exist. However, the keys should be a
187 vendor-specific domain name followed by a /-separated path. For
188 example, the Example IDE 1.0 could use example.com/Exam‐
189 pleIDE/1.0. The value of each field can be anything desired by
190 the vendor, though will typically be a map.
191 configurePresets
193 An optional array of Configure Preset objects. This is allowed
194 in preset files specifying version 1 or above.
195 buildPresets
197 An optional array of Build Preset objects. This is allowed in
198 preset files specifying version 2 or above.
199 testPresets
201 An optional array of Test Preset objects. This is allowed in
202 preset files specifying version 2 or above.
203 packagePresets
205 An optional array of Package Preset objects. This is allowed in
206 preset files specifying version 6 or above.
207 workflowPresets
209 An optional array of Workflow Preset objects. This is allowed
210 in preset files specifying version 6 or above.
211 Includes
213 CMakePresets.json and CMakeUserPresets.json can include other files
214 with the include field in file version 4 and later. Files included by
215 these files can also include other files. If CMakePresets.json and
216 CMakeUserPresets.json are both present, CMakeUserPresets.json implic‐
217 itly includes CMakePresets.json, even with no include field, in all
218 versions of the format.
219 If a preset file contains presets that inherit from presets in another
221 file, the file must include the other file either directly or indi‐
222 rectly. Include cycles are not allowed among files. If a.json includes
223 b.json, b.json cannot include a.json. However, a file may be included
224 multiple times from the same file or from different files.
225 Files directly or indirectly included from CMakePresets.json should be
227 guaranteed to be provided by the project. CMakeUserPresets.json may in‐
228 clude files from anywhere.
229 Configure Preset
231 Each entry of the configurePresets array is a JSON object that may con‐
232 tain the following fields:
233 name A required string representing the machine-friendly name of the
235 preset. This identifier is used in the cmake --preset option.
236 There must not be two configure presets in the union of CMakeP‐
237 resets.json and CMakeUserPresets.json in the same directory with
238 the same name. However, a configure preset may have the same
239 name as a build, test, package, or workflow preset.
240 hidden An optional boolean specifying whether or not a preset should be
242 hidden. If a preset is hidden, it cannot be used in the --pre‐
243 set= argument, will not show up in the CMake GUI, and does not
244 have to have a valid generator or binaryDir, even from inheri‐
245 tance. hidden presets are intended to be used as a base for
246 other presets to inherit via the inherits field.
247 inherits
249 An optional array of strings representing the names of presets
250 to inherit from. This field can also be a string, which is
251 equivalent to an array containing one string.
252 The preset will inherit all of the fields from the inherits pre‐
254 sets by default (except name, hidden, inherits, description, and
255 displayName), but can override them as desired. If multiple in‐
256 herits presets provide conflicting values for the same field,
257 the earlier preset in the inherits array will be preferred.
258 A preset can only inherit from another preset that is defined in
260 the same file or in one of the files it includes (directly or
261 indirectly). Presets in CMakePresets.json may not inherit from
262 presets in CMakeUserPresets.json.
263 condition
265 An optional Condition object. This is allowed in preset files
266 specifying version 3 or above.
267 vendor An optional map containing vendor-specific information. CMake
269 does not interpret the contents of this field except to verify
270 that it is a map if it does exist. However, it should follow the
271 same conventions as the root-level vendor field. If vendors use
272 their own per-preset vendor field, they should implement inheri‐
273 tance in a sensible manner when appropriate.
274 displayName
276 An optional string with a human-friendly name of the preset.
277 description
279 An optional string with a human-friendly description of the pre‐
280 set.
281 generator
283 An optional string representing the generator to use for the
284 preset. If generator is not specified, it must be inherited from
285 the inherits preset (unless this preset is hidden). In version 3
286 or above, this field may be omitted to fall back to regular gen‐
287 erator discovery procedure.
288 Note that for Visual Studio generators, unlike in the command
290 line -G argument, you cannot include the platform name in the
291 generator name. Use the architecture field instead.
292 architecture, toolset
294 Optional fields representing the platform and toolset, respec‐
295 tively, for generators that support them.
296 See cmake -A option for possible values for architecture and
298 cmake -T for toolset.
299 Each may be either a string or an object with the following
301 fields:
302 value An optional string representing the value.
304 strategy
306 An optional string telling CMake how to handle the archi‐
307 tecture or toolset field. Valid values are:
308 "set" Set the respective value. This will result in an
310 error for generators that do not support the re‐
311 spective field.
312 "external"
314 Do not set the value, even if the generator sup‐
315 ports it. This is useful if, for example, a preset
316 uses the Ninja generator, and an IDE knows how to
317 set up the Visual C++ environment from the archi‐
318 tecture and toolset fields. In that case, CMake
319 will ignore the field, but the IDE can use them to
320 set up the environment before invoking CMake.
321 If no strategy field is given, or if the field uses the
323 string form rather than the object form, the behavior is
324 the same as "set".
325 toolchainFile
327 An optional string representing the path to the toolchain file.
328 This field supports macro expansion. If a relative path is spec‐
329 ified, it is calculated relative to the build directory, and if
330 not found, relative to the source directory. This field takes
331 precedence over any CMAKE_TOOLCHAIN_FILE value. It is allowed in
332 preset files specifying version 3 or above.
333 binaryDir
335 An optional string representing the path to the output binary
336 directory. This field supports macro expansion. If a relative
337 path is specified, it is calculated relative to the source di‐
338 rectory. If binaryDir is not specified, it must be inherited
339 from the inherits preset (unless this preset is hidden). In ver‐
340 sion 3 or above, this field may be omitted.
341 installDir
343 An optional string representing the path to the installation di‐
344 rectory. This field supports macro expansion. If a relative
345 path is specified, it is calculated relative to the source di‐
346 rectory. This is allowed in preset files specifying version 3 or
347 above.
348 cmakeExecutable
350 An optional string representing the path to the CMake executable
351 to use for this preset. This is reserved for use by IDEs, and is
352 not used by CMake itself. IDEs that use this field should expand
353 any macros in it.
354 cacheVariables
356 An optional map of cache variables. The key is the variable name
357 (which may not be an empty string), and the value is either
358 null, a boolean (which is equivalent to a value of "TRUE" or
359 "FALSE" and a type of BOOL), a string representing the value of
360 the variable (which supports macro expansion), or an object with
361 the following fields:
362 type An optional string representing the type of the variable.
364 value A required string or boolean representing the value of
366 the variable. A boolean is equivalent to "TRUE" or
367 "FALSE". This field supports macro expansion.
368 Cache variables are inherited through the inherits field, and
370 the preset's variables will be the union of its own cacheVari‐
371 ables and the cacheVariables from all its parents. If multiple
372 presets in this union define the same variable, the standard
373 rules of inherits are applied. Setting a variable to null causes
374 it to not be set, even if a value was inherited from another
375 preset.
376 environment
378 An optional map of environment variables. The key is the vari‐
379 able name (which may not be an empty string), and the value is
380 either null or a string representing the value of the variable.
381 Each variable is set regardless of whether or not a value was
382 given to it by the process's environment. This field supports
383 macro expansion, and environment variables in this map may ref‐
384 erence each other, and may be listed in any order, as long as
385 such references do not cause a cycle (for example, if ENV_1 is
386 $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)
387 Environment variables are inherited through the inherits field,
389 and the preset's environment will be the union of its own envi‐
390 ronment and the environment from all its parents. If multiple
391 presets in this union define the same variable, the standard
392 rules of inherits are applied. Setting a variable to null causes
393 it to not be set, even if a value was inherited from another
394 preset.
395 warnings
397 An optional object specifying the warnings to enable. The object
398 may contain the following fields:
399 dev An optional boolean. Equivalent to passing -Wdev or
401 -Wno-dev on the command line. This may not be set to
402 false if errors.dev is set to true.
403 deprecated
405 An optional boolean. Equivalent to passing -Wdeprecated
406 or -Wno-deprecated on the command line. This may not be
407 set to false if errors.deprecated is set to true.
408 uninitialized
410 An optional boolean. Setting this to true is equivalent
411 to passing --warn-uninitialized on the command line.
412 unusedCli
414 An optional boolean. Setting this to false is equivalent
415 to passing --no-warn-unused-cli on the command line.
416 systemVars
418 An optional boolean. Setting this to true is equivalent
419 to passing --check-system-vars on the command line.
420 errors An optional object specifying the errors to enable. The object
422 may contain the following fields:
423 dev An optional boolean. Equivalent to passing -Werror=dev or
425 -Wno-error=dev on the command line. This may not be set
426 to true if warnings.dev is set to false.
427 deprecated
429 An optional boolean. Equivalent to passing
430 -Werror=deprecated or -Wno-error=deprecated on the com‐
431 mand line. This may not be set to true if warnings.dep‐
432 recated is set to false.
433 debug An optional object specifying debug options. The object may con‐
435 tain the following fields:
436 output An optional boolean. Setting this to true is equivalent
438 to passing --debug-output on the command line.
439 tryCompile
441 An optional boolean. Setting this to true is equivalent
442 to passing --debug-trycompile on the command line.
443 find An optional boolean. Setting this to true is equivalent
445 to passing --debug-find on the command line.
446 Build Preset
448 Each entry of the buildPresets array is a JSON object that may contain
449 the following fields:
450 name A required string representing the machine-friendly name of the
452 preset. This identifier is used in the cmake --build --preset
453 option. There must not be two build presets in the union of
454 CMakePresets.json and CMakeUserPresets.json in the same direc‐
455 tory with the same name. However, a build preset may have the
456 same name as a configure, test, package, or workflow preset.
457 hidden An optional boolean specifying whether or not a preset should be
459 hidden. If a preset is hidden, it cannot be used in the
460 --preset argument and does not have to have a valid configureP‐
461 reset, even from inheritance. hidden presets are intended to be
462 used as a base for other presets to inherit via the inherits
463 field.
464 inherits
466 An optional array of strings representing the names of presets
467 to inherit from. This field can also be a string, which is
468 equivalent to an array containing one string.
469 The preset will inherit all of the fields from the inherits pre‐
471 sets by default (except name, hidden, inherits, description, and
472 displayName), but can override them as desired. If multiple in‐
473 herits presets provide conflicting values for the same field,
474 the earlier preset in the inherits array will be preferred.
475 A preset can only inherit from another preset that is defined in
477 the same file or in one of the files it includes (directly or
478 indirectly). Presets in CMakePresets.json may not inherit from
479 presets in CMakeUserPresets.json.
480 condition
482 An optional Condition object. This is allowed in preset files
483 specifying version 3 or above.
484 vendor An optional map containing vendor-specific information. CMake
486 does not interpret the contents of this field except to verify
487 that it is a map if it does exist. However, it should follow the
488 same conventions as the root-level vendor field. If vendors use
489 their own per-preset vendor field, they should implement inheri‐
490 tance in a sensible manner when appropriate.
491 displayName
493 An optional string with a human-friendly name of the preset.
494 description
496 An optional string with a human-friendly description of the pre‐
497 set.
498 environment
500 An optional map of environment variables. The key is the vari‐
501 able name (which may not be an empty string), and the value is
502 either null or a string representing the value of the variable.
503 Each variable is set regardless of whether or not a value was
504 given to it by the process's environment. This field supports
505 macro expansion, and environment variables in this map may ref‐
506 erence each other, and may be listed in any order, as long as
507 such references do not cause a cycle (for example, if ENV_1 is
508 $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)
509 Environment variables are inherited through the inherits field,
511 and the preset's environment will be the union of its own envi‐
512 ronment and the environment from all its parents. If multiple
513 presets in this union define the same variable, the standard
514 rules of inherits are applied. Setting a variable to null causes
515 it to not be set, even if a value was inherited from another
516 preset.
517 NOTE:
519 For a CMake project using ExternalProject with a configura‐
520 tion preset having environment variables needed in the Exter‐
521 nalProject, use a build preset that inherits that configura‐
522 tion preset or the ExternalProject will not have the environ‐
523 ment variables set in the configuration preset. Example:
524 suppose the host defaults to one compiler (say Clang) and the
525 user wishes to use another compiler (say GCC). Set configura‐
526 tion preset environment variables CC and CXX and use a build
527 preset that inherits that configuration preset. Otherwise the
528 ExternalProject may use a different (system default) compiler
529 than the top-level CMake project.
530 configurePreset
532 An optional string specifying the name of a configure preset to
533 associate with this build preset. If configurePreset is not
534 specified, it must be inherited from the inherits preset (unless
535 this preset is hidden). The build directory is inferred from the
536 configure preset, so the build will take place in the same bina‐
537 ryDir that the configuration did.
538 inheritConfigureEnvironment
540 An optional boolean that defaults to true. If true, the environ‐
541 ment variables from the associated configure preset are inher‐
542 ited after all inherited build preset environments, but before
543 environment variables explicitly specified in this build preset.
544 jobs An optional integer. Equivalent to passing --parallel or -j on
546 the command line.
547 targets
549 An optional string or array of strings. Equivalent to passing
550 --target or -t on the command line. Vendors may ignore the tar‐
551 gets property or hide build presets that explicitly specify tar‐
552 gets. This field supports macro expansion.
553 configuration
555 An optional string. Equivalent to passing --config on the com‐
556 mand line.
557 cleanFirst
559 An optional bool. If true, equivalent to passing --clean-first
560 on the command line.
561 resolvePackageReferences
563 An optional string that specifies the package resolve mode. This
564 is allowed in preset files specifying version 4 or above.
565 Package references are used to define dependencies to packages
567 from external package managers. Currently only NuGet in combina‐
568 tion with the Visual Studio generator is supported. If there are
569 no targets that define package references, this option does
570 nothing. Valid values are:
571 on Causes package references to be resolved before attempt‐
573 ing a build.
574 off Package references will not be resolved. Note that this
576 may cause errors in some build environments, such as .NET
577 SDK style projects.
578 only Only resolve package references, but do not perform a
580 build.
581 NOTE:
583 The command line parameter --resolve-package-references will
584 take priority over this setting. If the command line parame‐
585 ter is not provided and this setting is not specified, an en‐
586 vironment-specific cache variable will be evaluated to de‐
587 cide, if package restoration should be performed.
588 When using the Visual Studio generator, package references
590 are defined using the VS_PACKAGE_REFERENCES property. Package
591 references are restored using NuGet. It can be disabled by
592 setting the CMAKE_VS_NUGET_PACKAGE_RESTORE variable to OFF.
593 This can also be done from within a configure preset.
594 verbose
596 An optional bool. If true, equivalent to passing --verbose on
597 the command line.
598 nativeToolOptions
600 An optional array of strings. Equivalent to passing options af‐
601 ter -- on the command line. The array values support macro ex‐
602 pansion.
603 Test Preset
605 Each entry of the testPresets array is a JSON object that may contain
606 the following fields:
607 name A required string representing the machine-friendly name of the
609 preset. This identifier is used in the ctest --preset option.
610 There must not be two test presets in the union of CMakePre‐
611 sets.json and CMakeUserPresets.json in the same directory with
612 the same name. However, a test preset may have the same name as
613 a configure, build, package, or workflow preset.
614 hidden An optional boolean specifying whether or not a preset should be
616 hidden. If a preset is hidden, it cannot be used in the
617 --preset argument and does not have to have a valid configureP‐
618 reset, even from inheritance. hidden presets are intended to be
619 used as a base for other presets to inherit via the inherits
620 field.
621 inherits
623 An optional array of strings representing the names of presets
624 to inherit from. This field can also be a string, which is
625 equivalent to an array containing one string.
626 The preset will inherit all of the fields from the inherits pre‐
628 sets by default (except name, hidden, inherits, description, and
629 displayName), but can override them as desired. If multiple in‐
630 herits presets provide conflicting values for the same field,
631 the earlier preset in the inherits array will be preferred.
632 A preset can only inherit from another preset that is defined in
634 the same file or in one of the files it includes (directly or
635 indirectly). Presets in CMakePresets.json may not inherit from
636 presets in CMakeUserPresets.json.
637 condition
639 An optional Condition object. This is allowed in preset files
640 specifying version 3 or above.
641 vendor An optional map containing vendor-specific information. CMake
643 does not interpret the contents of this field except to verify
644 that it is a map if it does exist. However, it should follow the
645 same conventions as the root-level vendor field. If vendors use
646 their own per-preset vendor field, they should implement inheri‐
647 tance in a sensible manner when appropriate.
648 displayName
650 An optional string with a human-friendly name of the preset.
651 description
653 An optional string with a human-friendly description of the pre‐
654 set.
655 environment
657 An optional map of environment variables. The key is the vari‐
658 able name (which may not be an empty string), and the value is
659 either null or a string representing the value of the variable.
660 Each variable is set regardless of whether or not a value was
661 given to it by the process's environment. This field supports
662 macro expansion, and environment variables in this map may ref‐
663 erence each other, and may be listed in any order, as long as
664 such references do not cause a cycle (for example, if ENV_1 is
665 $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)
666 Environment variables are inherited through the inherits field,
668 and the preset's environment will be the union of its own envi‐
669 ronment and the environment from all its parents. If multiple
670 presets in this union define the same variable, the standard
671 rules of inherits are applied. Setting a variable to null causes
672 it to not be set, even if a value was inherited from another
673 preset.
674 configurePreset
676 An optional string specifying the name of a configure preset to
677 associate with this test preset. If configurePreset is not spec‐
678 ified, it must be inherited from the inherits preset (unless
679 this preset is hidden). The build directory is inferred from the
680 configure preset, so tests will run in the same binaryDir that
681 the configuration did and build did.
682 inheritConfigureEnvironment
684 An optional boolean that defaults to true. If true, the environ‐
685 ment variables from the associated configure preset are inher‐
686 ited after all inherited test preset environments, but before
687 environment variables explicitly specified in this test preset.
688 configuration
690 An optional string. Equivalent to passing --build-config on the
691 command line.
692 overwriteConfigurationFile
694 An optional array of configuration options to overwrite options
695 specified in the CTest configuration file. Equivalent to passing
696 --overwrite for each value in the array. The array values sup‐
697 port macro expansion.
698 output An optional object specifying output options. The object may
700 contain the following fields.
701 shortProgress
703 An optional bool. If true, equivalent to passing
704 --progress on the command line.
705 verbosity
707 An optional string specifying verbosity level. Must be
708 one of the following:
709 default
711 Equivalent to passing no verbosity flags on the
712 command line.
713 verbose
715 Equivalent to passing --verbose on the command
716 line.
717 extra Equivalent to passing --extra-verbose on the com‐
719 mand line.
720 debug An optional bool. If true, equivalent to passing --debug
722 on the command line.
723 outputOnFailure
725 An optional bool. If true, equivalent to passing
726 --output-on-failure on the command line.
727 quiet An optional bool. If true, equivalent to passing --quiet
729 on the command line.
730 outputLogFile
732 An optional string specifying a path to a log file.
733 Equivalent to passing --output-log on the command line.
734 This field supports macro expansion.
735 outputJUnitFile
737 An optional string specifying a path to a JUnit file.
738 Equivalent to passing --output-junit on the command line.
739 This field supports macro expansion. This is allowed in
740 preset files specifying version 6 or above.
741 labelSummary
743 An optional bool. If false, equivalent to passing
744 --no-label-summary on the command line.
745 subprojectSummary
747 An optional bool. If false, equivalent to passing
748 --no-subproject-summary on the command line.
749 maxPassedTestOutputSize
751 An optional integer specifying the maximum output for
752 passed tests in bytes. Equivalent to passing
753 --test-output-size-passed on the command line.
754 maxFailedTestOutputSize
756 An optional integer specifying the maximum output for
757 failed tests in bytes. Equivalent to passing
758 --test-output-size-failed on the command line.
759 testOutputTruncation
761 An optional string specifying the test output truncation
762 mode. Equivalent to passing --test-output-truncation on
763 the command line. This is allowed in preset files speci‐
764 fying version 5 or above.
765 maxTestNameWidth
767 An optional integer specifying the maximum width of a
768 test name to output. Equivalent to passing --max-width on
769 the command line.
770 filter An optional object specifying how to filter the tests to run.
772 The object may contain the following fields.
773 include
775 An optional object specifying which tests to include. The
776 object may contain the following fields.
777 name An optional string specifying a regex for test
779 names. Equivalent to passing --tests-regex on the
780 command line. This field supports macro expansion.
781 CMake regex syntax is described under
782 string(REGEX).
783 label An optional string specifying a regex for test la‐
785 bels. Equivalent to passing --label-regex on the
786 command line. This field supports macro expansion.
787 useUnion
789 An optional bool. Equivalent to passing --union on
790 the command line.
791 index An optional object specifying tests to include by
793 test index. The object may contain the following
794 fields. Can also be an optional string specifying
795 a file with the command line syntax for
796 --tests-information. If specified as a string,
797 this field supports macro expansion.
798 start An optional integer specifying a test index
800 to start testing at.
801 end An optional integer specifying a test index
803 to stop testing at.
804 stride An optional integer specifying the incre‐
806 ment.
807 specificTests
809 An optional array of integers specifying
810 specific test indices to run.
811 exclude
813 An optional object specifying which tests to exclude. The
814 object may contain the following fields.
815 name An optional string specifying a regex for test
817 names. Equivalent to passing --exclude-regex on
818 the command line. This field supports macro expan‐
819 sion.
820 label An optional string specifying a regex for test la‐
822 bels. Equivalent to passing --label-exclude on the
823 command line. This field supports macro expansion.
824 fixtures
826 An optional object specifying which fixtures to
827 exclude from adding tests. The object may contain
828 the following fields.
829 any An optional string specifying a regex for
831 text fixtures to exclude from adding any
832 tests. Equivalent to --fixture-exclude-any
833 on the command line. This field supports
834 macro expansion.
835 setup An optional string specifying a regex for
837 text fixtures to exclude from adding setup
838 tests. Equivalent to
839 --fixture-exclude-setup on the command
840 line. This field supports macro expansion.
841 cleanup
843 An optional string specifying a regex for
844 text fixtures to exclude from adding
845 cleanup tests. Equivalent to
846 --fixture-exclude-cleanup on the command
847 line. This field supports macro expansion.
848 execution
850 An optional object specifying options for test execution. The
851 object may contain the following fields.
852 stopOnFailure
854 An optional bool. If true, equivalent to passing
855 --stop-on-failure on the command line.
856 enableFailover
858 An optional bool. If true, equivalent to passing -F on
859 the command line.
860 jobs An optional integer. Equivalent to passing --parallel on
862 the command line.
863 resourceSpecFile
865 An optional string. Equivalent to passing
866 --resource-spec-file on the command line. This field sup‐
867 ports macro expansion.
868 testLoad
870 An optional integer. Equivalent to passing --test-load on
871 the command line.
872 showOnly
874 An optional string. Equivalent to passing --show-only on
875 the command line. The string must be one of the following
876 values:
877 human
879 json-v1
881 repeat An optional object specifying how to repeat tests. Equiv‐
883 alent to passing --repeat on the command line. The ob‐
884 ject must have the following fields.
885 mode A required string. Must be one of the following
887 values:
888 until-fail
890 until-pass
892 after-timeout
894 count A required integer.
896 interactiveDebugging
898 An optional bool. If true, equivalent to passing
899 --interactive-debug-mode 1 on the command line. If false,
900 equivalent to passing --interactive-debug-mode 0 on the
901 command line.
902 scheduleRandom
904 An optional bool. If true, equivalent to passing
905 --schedule-random on the command line.
906 timeout
908 An optional integer. Equivalent to passing --timeout on
909 the command line.
910 noTestsAction
912 An optional string specifying the behavior if no tests
913 are found. Must be one of the following values:
914 default
916 Equivalent to not passing any value on the command
917 line.
918 error Equivalent to passing --no-tests=error on the com‐
920 mand line.
921 ignore Equivalent to passing --no-tests=ignore on the
923 command line.
924 Package Preset
926 Package presets may be used in schema version 6 or above. Each entry of
927 the packagePresets array is a JSON object that may contain the follow‐
928 ing fields:
929 name A required string representing the machine-friendly name of the
931 preset. This identifier is used in the cpack --preset option.
932 There must not be two package presets in the union of CMakePre‐
933 sets.json and CMakeUserPresets.json in the same directory with
934 the same name. However, a package preset may have the same name
935 as a configure, build, test, or workflow preset.
936 hidden An optional boolean specifying whether or not a preset should be
938 hidden. If a preset is hidden, it cannot be used in the
939 --preset argument and does not have to have a valid configureP‐
940 reset, even from inheritance. hidden presets are intended to be
941 used as a base for other presets to inherit via the inherits
942 field.
943 inherits
945 An optional array of strings representing the names of presets
946 to inherit from. This field can also be a string, which is
947 equivalent to an array containing one string.
948 The preset will inherit all of the fields from the inherits pre‐
950 sets by default (except name, hidden, inherits, description, and
951 displayName), but can override them as desired. If multiple in‐
952 herits presets provide conflicting values for the same field,
953 the earlier preset in the inherits array will be preferred.
954 A preset can only inherit from another preset that is defined in
956 the same file or in one of the files it includes (directly or
957 indirectly). Presets in CMakePresets.json may not inherit from
958 presets in CMakeUserPresets.json.
959 condition
961 An optional Condition object.
962 vendor An optional map containing vendor-specific information. CMake
964 does not interpret the contents of this field except to verify
965 that it is a map if it does exist. However, it should follow the
966 same conventions as the root-level vendor field. If vendors use
967 their own per-preset vendor field, they should implement inheri‐
968 tance in a sensible manner when appropriate.
969 displayName
971 An optional string with a human-friendly name of the preset.
972 description
974 An optional string with a human-friendly description of the pre‐
975 set.
976 environment
978 An optional map of environment variables. The key is the vari‐
979 able name (which may not be an empty string), and the value is
980 either null or a string representing the value of the variable.
981 Each variable is set regardless of whether or not a value was
982 given to it by the process's environment. This field supports
983 macro expansion, and environment variables in this map may ref‐
984 erence each other, and may be listed in any order, as long as
985 such references do not cause a cycle (for example, if ENV_1 is
986 $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)
987 Environment variables are inherited through the inherits field,
989 and the preset's environment will be the union of its own envi‐
990 ronment and the environment from all its parents. If multiple
991 presets in this union define the same variable, the standard
992 rules of inherits are applied. Setting a variable to null causes
993 it to not be set, even if a value was inherited from another
994 preset.
995 configurePreset
997 An optional string specifying the name of a configure preset to
998 associate with this package preset. If configurePreset is not
999 specified, it must be inherited from the inherits preset (unless
1000 this preset is hidden). The build directory is inferred from the
1001 configure preset, so packaging will run in the same binaryDir
1002 that the configuration did and build did.
1003 inheritConfigureEnvironment
1005 An optional boolean that defaults to true. If true, the environ‐
1006 ment variables from the associated configure preset are inher‐
1007 ited after all inherited package preset environments, but before
1008 environment variables explicitly specified in this package pre‐
1009 set.
1010 generators
1012 An optional array of strings representing generators for CPack
1013 to use.
1014 configurations
1016 An optional array of strings representing build configurations
1017 for CPack to package.
1018 variables
1020 An optional map of variables to pass to CPack, equivalent to -D
1021 arguments. Each key is the name of a variable, and the value is
1022 the string to assign to that variable.
1023 configFile
1025 An optional string representing the config file for CPack to
1026 use.
1027 output An optional object specifying output options. Valid keys are:
1029 debug An optional boolean specifying whether or not to print
1031 debug information. A value of true is equivalent to
1032 passing --debug on the command line.
1033 verbose
1035 An optional boolean specifying whether or not to print
1036 verbosely. A value of true is equivalent to passing
1037 --verbose on the command line.
1038 packageName
1040 An optional string representing the package name.
1041 packageVersion
1043 An optional string representing the package version.
1044 packageDirectory
1046 An optional string representing the directory in which to place
1047 the package.
1048 vendorName
1050 An optional string representing the vendor name.
1051 Workflow Preset
1053 Workflow presets may be used in schema version 6 or above. Each entry
1054 of the workflowPresets array is a JSON object that may contain the fol‐
1055 lowing fields:
1056 name A required string representing the machine-friendly name of the
1058 preset. This identifier is used in the cmake --workflow --pre‐
1059 set option. There must not be two workflow presets in the union
1060 of CMakePresets.json and CMakeUserPresets.json in the same di‐
1061 rectory with the same name. However, a workflow preset may have
1062 the same name as a configure, build, test, or package preset.
1063 displayName
1065 An optional string with a human-friendly name of the preset.
1066 description
1068 An optional string with a human-friendly description of the pre‐
1069 set.
1070 steps A required array of objects describing the steps of the work‐
1072 flow. The first step must be a configure preset, and all subse‐
1073 quent steps must be non- configure presets whose configurePreset
1074 field matches the starting configure preset. Each object may
1075 contain the following fields:
1076 type A required string. The first step must be configure. Sub‐
1078 sequent steps must be either build, test, or package.
1079 name A required string representing the name of the configure,
1081 build, test, or package preset to run as this workflow
1082 step.
1083 Condition
1085 The condition field of a preset, allowed in preset files specifying
1086 version 3 or above, is used to determine whether or not the preset is
1087 enabled. For example, this can be used to disable a preset on platforms
1088 other than Windows. condition may be either a boolean, null, or an ob‐
1089 ject. If it is a boolean, the boolean indicates whether the preset is
1090 enabled or disabled. If it is null, the preset is enabled, but the null
1091 condition is not inherited by any presets that may inherit from the
1092 preset. Sub-conditions (for example in a not, anyOf, or allOf condi‐
1093 tion) may not be null. If it is an object, it has the following fields:
1094 type A required string with one of the following values:
1096 "const"
1098 Indicates that the condition is constant. This is equiva‐
1099 lent to using a boolean in place of the object. The con‐
1100 dition object will have the following additional fields:
1101 value A required boolean which provides a constant value
1103 for the condition's evaluation.
1104 "equals"
1106 "notEquals"
1108 Indicates that the condition compares two strings to see
1109 if they are equal (or not equal). The condition object
1110 will have the following additional fields:
1111 lhs First string to compare. This field supports macro
1113 expansion.
1114 rhs Second string to compare. This field supports
1116 macro expansion.
1117 "inList"
1119 "notInList"
1121 Indicates that the condition searches for a string in a
1122 list of strings. The condition object will have the fol‐
1123 lowing additional fields:
1124 string A required string to search for. This field sup‐
1126 ports macro expansion.
1127 list A required array of strings to search. This field
1129 supports macro expansion, and uses short-circuit
1130 evaluation.
1131 "matches"
1133 "notMatches"
1135 Indicates that the condition searches for a regular ex‐
1136 pression in a string. The condition object will have the
1137 following additional fields:
1138 string A required string to search. This field supports
1140 macro expansion.
1141 regex A required regular expression to search for. This
1143 field supports macro expansion.
1144 "anyOf"
1146 "allOf"
1148 Indicates that the condition is an aggregation of zero or
1149 more nested conditions. The condition object will have the
1150 following additional fields:
1151 conditions
1153 A required array of condition objects. These condi‐
1154 tions use short-circuit evaluation.
1155 "not" Indicates that the condition is an inversion of another
1157 condition. The condition object will have the following
1158 additional fields:
1159 condition
1161 A required condition object.
1162 Macro Expansion
1164 As mentioned above, some fields support macro expansion. Macros are
1165 recognized in the form $<macro-namespace>{<macro-name>}. All macros are
1166 evaluated in the context of the preset being used, even if the macro is
1167 in a field that was inherited from another preset. For example, if the
1168 Base preset sets variable PRESET_NAME to ${presetName}, and the Derived
1169 preset inherits from Base, PRESET_NAME will be set to Derived.
1170 It is an error to not put a closing brace at the end of a macro name.
1172 For example, ${sourceDir is invalid. A dollar sign ($) followed by any‐
1173 thing other than a left curly brace ({) with a possible namespace is
1174 interpreted as a literal dollar sign.
1175 Recognized macros include:
1177 ${sourceDir}
1179 Path to the project source directory (i.e. the same as
1180 CMAKE_SOURCE_DIR).
1181 ${sourceParentDir}
1183 Path to the project source directory's parent directory.
1184 ${sourceDirName}
1186 The last filename component of ${sourceDir}. For example, if
1187 ${sourceDir} is /path/to/source, this would be source.
1188 ${presetName}
1190 Name specified in the preset's name field.
1191 ${generator}
1193 Generator specified in the preset's generator field. For build
1194 and test presets, this will evaluate to the generator specified
1195 by configurePreset.
1196 ${hostSystemName}
1198 The name of the host operating system. Contains the same value
1199 as CMAKE_HOST_SYSTEM_NAME. This is allowed in preset files spec‐
1200 ifying version 3 or above.
1201 ${fileDir}
1203 Path to the directory containing the preset file which contains
1204 the macro. This is allowed in preset files specifying version 4
1205 or above.
1206 ${dollar}
1208 A literal dollar sign ($).
1209 ${pathListSep}
1211 Native character for separating lists of paths, such as : or ;.
1212 For example, by setting PATH to /path/to/ninja/bin${pathList‐
1214 Sep}$env{PATH}, ${pathListSep} will expand to the underlying op‐
1215 erating system's character used for concatenation in PATH.
1216 This is allowed in preset files specifying version 5 or above.
1218 $env{<variable-name>}
1220 Environment variable with name <variable-name>. The variable
1221 name may not be an empty string. If the variable is defined in
1222 the environment field, that value is used instead of the value
1223 from the parent environment. If the environment variable is not
1224 defined, this evaluates as an empty string.
1225 Note that while Windows environment variable names are case-in‐
1227 sensitive, variable names within a preset are still case-sensi‐
1228 tive. This may lead to unexpected results when using inconsis‐
1229 tent casing. For best results, keep the casing of environment
1230 variable names consistent.
1231 $penv{<variable-name>}
1233 Similar to $env{<variable-name>}, except that the value only
1234 comes from the parent environment, and never from the environ‐
1235 ment field. This allows you to prepend or append values to ex‐
1236 isting environment variables. For example, setting PATH to
1237 /path/to/ninja/bin:$penv{PATH} will prepend /path/to/ninja/bin
1238 to the PATH environment variable. This is needed because
1239 $env{<variable-name>} does not allow circular references.
1240 $vendor{<macro-name>}
1242 An extension point for vendors to insert their own macros. CMake
1243 will not be able to use presets which have a $ven‐
1244 dor{<macro-name>} macro, and effectively ignores such presets.
1245 However, it will still be able to use other presets from the
1246 same file.
1247 CMake does not make any attempt to interpret $ven‐
1249 dor{<macro-name>} macros. However, to avoid name collisions, IDE
1250 vendors should prefix <macro-name> with a very short (preferably
1251 <= 4 characters) vendor identifier prefix, followed by a ., fol‐
1252 lowed by the macro name. For example, the Example IDE could have
1253 $vendor{xide.ideInstallDir}.
1254
1256 This file provides a machine-readable JSON schema for the CMakePre‐
1257 sets.json format.
1258
1260 2000-2023 Kitware, Inc. and Contributors
12613.25.2 Jan 19, 2023 CMAKE-PRESETS(7)