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 7 New in version 3.27.
167 cmakeMinimumRequired
170 An optional object representing the minimum version of CMake
171 needed to build this project. This object consists of the fol‐
172 lowing fields:
173 major An optional integer representing the major version.
175 minor An optional integer representing the minor version.
177 patch An optional integer representing the patch version.
179 include
181 An optional array of strings representing files to include. If
182 the filenames are not absolute, they are considered relative to
183 the current file. This is allowed in preset files specifying
184 version 4 or above. See Includes for discussion of the con‐
185 straints on included files.
186 vendor An optional map containing vendor-specific information. CMake
188 does not interpret the contents of this field except to verify
189 that it is a map if it does exist. However, the keys should be a
190 vendor-specific domain name followed by a /-separated path. For
191 example, the Example IDE 1.0 could use example.com/Exam‐
192 pleIDE/1.0. The value of each field can be anything desired by
193 the vendor, though will typically be a map.
194 configurePresets
196 An optional array of Configure Preset objects. This is allowed
197 in preset files specifying version 1 or above.
198 buildPresets
200 An optional array of Build Preset objects. This is allowed in
201 preset files specifying version 2 or above.
202 testPresets
204 An optional array of Test Preset objects. This is allowed in
205 preset files specifying version 2 or above.
206 packagePresets
208 An optional array of Package Preset objects. This is allowed in
209 preset files specifying version 6 or above.
210 workflowPresets
212 An optional array of Workflow Preset objects. This is allowed
213 in preset files specifying version 6 or above.
214 Includes
216 CMakePresets.json and CMakeUserPresets.json can include other files
217 with the include field in file version 4 and later. Files included by
218 these files can also include other files. If CMakePresets.json and
219 CMakeUserPresets.json are both present, CMakeUserPresets.json implic‐
220 itly includes CMakePresets.json, even with no include field, in all
221 versions of the format.
222 If a preset file contains presets that inherit from presets in another
224 file, the file must include the other file either directly or indi‐
225 rectly. Include cycles are not allowed among files. If a.json includes
226 b.json, b.json cannot include a.json. However, a file may be included
227 multiple times from the same file or from different files.
228 Files directly or indirectly included from CMakePresets.json should be
230 guaranteed to be provided by the project. CMakeUserPresets.json may in‐
231 clude files from anywhere.
232 Starting from version 7, the include field supports macro expansion,
234 but only $penv{} macro expansion.
235 Configure Preset
237 Each entry of the configurePresets array is a JSON object that may con‐
238 tain the following fields:
239 name A required string representing the machine-friendly name of the
241 preset. This identifier is used in the cmake --preset option.
242 There must not be two configure presets in the union of CMakeP‐
243 resets.json and CMakeUserPresets.json in the same directory with
244 the same name. However, a configure preset may have the same
245 name as a build, test, package, or workflow preset.
246 hidden An optional boolean specifying whether or not a preset should be
248 hidden. If a preset is hidden, it cannot be used in the --pre‐
249 set= argument, will not show up in the CMake GUI, and does not
250 have to have a valid generator or binaryDir, even from inheri‐
251 tance. hidden presets are intended to be used as a base for
252 other presets to inherit via the inherits field.
253 inherits
255 An optional array of strings representing the names of presets
256 to inherit from. This field can also be a string, which is
257 equivalent to an array containing one string.
258 The preset will inherit all of the fields from the inherits pre‐
260 sets by default (except name, hidden, inherits, description, and
261 displayName), but can override them as desired. If multiple in‐
262 herits presets provide conflicting values for the same field,
263 the earlier preset in the inherits array will be preferred.
264 A preset can only inherit from another preset that is defined in
266 the same file or in one of the files it includes (directly or
267 indirectly). Presets in CMakePresets.json may not inherit from
268 presets in CMakeUserPresets.json.
269 condition
271 An optional Condition object. This is allowed in preset files
272 specifying version 3 or above.
273 vendor An optional map containing vendor-specific information. CMake
275 does not interpret the contents of this field except to verify
276 that it is a map if it does exist. However, it should follow the
277 same conventions as the root-level vendor field. If vendors use
278 their own per-preset vendor field, they should implement inheri‐
279 tance in a sensible manner when appropriate.
280 displayName
282 An optional string with a human-friendly name of the preset.
283 description
285 An optional string with a human-friendly description of the pre‐
286 set.
287 generator
289 An optional string representing the generator to use for the
290 preset. If generator is not specified, it must be inherited from
291 the inherits preset (unless this preset is hidden). In version 3
292 or above, this field may be omitted to fall back to regular gen‐
293 erator discovery procedure.
294 Note that for Visual Studio generators, unlike in the command
296 line -G argument, you cannot include the platform name in the
297 generator name. Use the architecture field instead.
298 architecture, toolset
300 Optional fields representing the platform and toolset, respec‐
301 tively, for generators that support them.
302 See cmake -A option for possible values for architecture and
304 cmake -T for toolset.
305 Each may be either a string or an object with the following
307 fields:
308 value An optional string representing the value.
310 strategy
312 An optional string telling CMake how to handle the archi‐
313 tecture or toolset field. Valid values are:
314 "set" Set the respective value. This will result in an
316 error for generators that do not support the re‐
317 spective field.
318 "external"
320 Do not set the value, even if the generator sup‐
321 ports it. This is useful if, for example, a preset
322 uses the Ninja generator, and an IDE knows how to
323 set up the Visual C++ environment from the archi‐
324 tecture and toolset fields. In that case, CMake
325 will ignore the field, but the IDE can use them to
326 set up the environment before invoking CMake.
327 If no strategy field is given, or if the field uses the
329 string form rather than the object form, the behavior is
330 the same as "set".
331 toolchainFile
333 An optional string representing the path to the toolchain file.
334 This field supports macro expansion. If a relative path is spec‐
335 ified, it is calculated relative to the build directory, and if
336 not found, relative to the source directory. This field takes
337 precedence over any CMAKE_TOOLCHAIN_FILE value. It is allowed in
338 preset files specifying version 3 or above.
339 binaryDir
341 An optional string representing the path to the output binary
342 directory. This field supports macro expansion. If a relative
343 path is specified, it is calculated relative to the source di‐
344 rectory. If binaryDir is not specified, it must be inherited
345 from the inherits preset (unless this preset is hidden). In ver‐
346 sion 3 or above, this field may be omitted.
347 installDir
349 An optional string representing the path to the installation di‐
350 rectory. This field supports macro expansion. If a relative
351 path is specified, it is calculated relative to the source di‐
352 rectory. This is allowed in preset files specifying version 3 or
353 above.
354 cmakeExecutable
356 An optional string representing the path to the CMake executable
357 to use for this preset. This is reserved for use by IDEs, and is
358 not used by CMake itself. IDEs that use this field should expand
359 any macros in it.
360 cacheVariables
362 An optional map of cache variables. The key is the variable name
363 (which may not be an empty string), and the value is either
364 null, a boolean (which is equivalent to a value of "TRUE" or
365 "FALSE" and a type of BOOL), a string representing the value of
366 the variable (which supports macro expansion), or an object with
367 the following fields:
368 type An optional string representing the type of the variable.
370 value A required string or boolean representing the value of
372 the variable. A boolean is equivalent to "TRUE" or
373 "FALSE". This field supports macro expansion.
374 Cache variables are inherited through the inherits field, and
376 the preset's variables will be the union of its own cacheVari‐
377 ables and the cacheVariables from all its parents. If multiple
378 presets in this union define the same variable, the standard
379 rules of inherits are applied. Setting a variable to null causes
380 it to not be set, even if a value was inherited from another
381 preset.
382 environment
384 An optional map of environment variables. The key is the vari‐
385 able name (which may not be an empty string), and the value is
386 either null or a string representing the value of the variable.
387 Each variable is set regardless of whether or not a value was
388 given to it by the process's environment. This field supports
389 macro expansion, and environment variables in this map may ref‐
390 erence each other, and may be listed in any order, as long as
391 such references do not cause a cycle (for example, if ENV_1 is
392 $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)
393 Environment variables are inherited through the inherits field,
395 and the preset's environment will be the union of its own envi‐
396 ronment and the environment from all its parents. If multiple
397 presets in this union define the same variable, the standard
398 rules of inherits are applied. Setting a variable to null causes
399 it to not be set, even if a value was inherited from another
400 preset.
401 warnings
403 An optional object specifying the warnings to enable. The object
404 may contain the following fields:
405 dev An optional boolean. Equivalent to passing -Wdev or
407 -Wno-dev on the command line. This may not be set to
408 false if errors.dev is set to true.
409 deprecated
411 An optional boolean. Equivalent to passing -Wdeprecated
412 or -Wno-deprecated on the command line. This may not be
413 set to false if errors.deprecated is set to true.
414 uninitialized
416 An optional boolean. Setting this to true is equivalent
417 to passing --warn-uninitialized on the command line.
418 unusedCli
420 An optional boolean. Setting this to false is equivalent
421 to passing --no-warn-unused-cli on the command line.
422 systemVars
424 An optional boolean. Setting this to true is equivalent
425 to passing --check-system-vars on the command line.
426 errors An optional object specifying the errors to enable. The object
428 may contain the following fields:
429 dev An optional boolean. Equivalent to passing -Werror=dev or
431 -Wno-error=dev on the command line. This may not be set
432 to true if warnings.dev is set to false.
433 deprecated
435 An optional boolean. Equivalent to passing
436 -Werror=deprecated or -Wno-error=deprecated on the com‐
437 mand line. This may not be set to true if warnings.dep‐
438 recated is set to false.
439 debug An optional object specifying debug options. The object may con‐
441 tain the following fields:
442 output An optional boolean. Setting this to true is equivalent
444 to passing --debug-output on the command line.
445 tryCompile
447 An optional boolean. Setting this to true is equivalent
448 to passing --debug-trycompile on the command line.
449 find An optional boolean. Setting this to true is equivalent
451 to passing --debug-find on the command line.
452 trace An optional object specifying trace options. This is allowed in
454 preset files specifying version 7. The object may contain the
455 following fields:
456 mode An optional string that specifies the trace mode. Valid
458 values are:
459 on Causes a trace of all calls made and from where to
461 be printed. Equivalent to passing --trace on the
462 command line.
463 off A trace of all calls will not be printed.
465 expand Causes a trace with variables expanded of all
467 calls made and from where to be printed. Equiva‐
468 lent to passing --trace-expand on the command
469 line.
470 format An optional string that specifies the format output of
472 the trace. Valid values are:
473 human Prints each trace line in a human-readable format.
475 This is the default format. Equivalent to passing
476 --trace-format=human on the command line.
477 json-v1
479 Prints each line as a separate JSON document.
480 Equivalent to passing --trace-format=json-v1 on
481 the command line.
482 source An optional array of strings representing the paths of
484 source files to be traced. This field can also be a
485 string, which is equivalent to an array containing one
486 string. Equivalent to passing --trace-source on the com‐
487 mand line.
488 redirect
490 An optional string specifying a path to a trace output
491 file. Equivalent to passing --trace-redirect on the com‐
492 mand line.
493 Build Preset
495 Each entry of the buildPresets array is a JSON object that may contain
496 the following fields:
497 name A required string representing the machine-friendly name of the
499 preset. This identifier is used in the cmake --build --preset
500 option. There must not be two build presets in the union of
501 CMakePresets.json and CMakeUserPresets.json in the same direc‐
502 tory with the same name. However, a build preset may have the
503 same name as a configure, test, package, or workflow preset.
504 hidden An optional boolean specifying whether or not a preset should be
506 hidden. If a preset is hidden, it cannot be used in the
507 --preset argument and does not have to have a valid configureP‐
508 reset, even from inheritance. hidden presets are intended to be
509 used as a base for other presets to inherit via the inherits
510 field.
511 inherits
513 An optional array of strings representing the names of presets
514 to inherit from. This field can also be a string, which is
515 equivalent to an array containing one string.
516 The preset will inherit all of the fields from the inherits pre‐
518 sets by default (except name, hidden, inherits, description, and
519 displayName), but can override them as desired. If multiple in‐
520 herits presets provide conflicting values for the same field,
521 the earlier preset in the inherits array will be preferred.
522 A preset can only inherit from another preset that is defined in
524 the same file or in one of the files it includes (directly or
525 indirectly). Presets in CMakePresets.json may not inherit from
526 presets in CMakeUserPresets.json.
527 condition
529 An optional Condition object. This is allowed in preset files
530 specifying version 3 or above.
531 vendor An optional map containing vendor-specific information. CMake
533 does not interpret the contents of this field except to verify
534 that it is a map if it does exist. However, it should follow the
535 same conventions as the root-level vendor field. If vendors use
536 their own per-preset vendor field, they should implement inheri‐
537 tance in a sensible manner when appropriate.
538 displayName
540 An optional string with a human-friendly name of the preset.
541 description
543 An optional string with a human-friendly description of the pre‐
544 set.
545 environment
547 An optional map of environment variables. The key is the vari‐
548 able name (which may not be an empty string), and the value is
549 either null or a string representing the value of the variable.
550 Each variable is set regardless of whether or not a value was
551 given to it by the process's environment. This field supports
552 macro expansion, and environment variables in this map may ref‐
553 erence each other, and may be listed in any order, as long as
554 such references do not cause a cycle (for example, if ENV_1 is
555 $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)
556 Environment variables are inherited through the inherits field,
558 and the preset's environment will be the union of its own envi‐
559 ronment and the environment from all its parents. If multiple
560 presets in this union define the same variable, the standard
561 rules of inherits are applied. Setting a variable to null causes
562 it to not be set, even if a value was inherited from another
563 preset.
564 NOTE:
566 For a CMake project using ExternalProject with a configura‐
567 tion preset having environment variables needed in the Exter‐
568 nalProject, use a build preset that inherits that configura‐
569 tion preset or the ExternalProject will not have the environ‐
570 ment variables set in the configuration preset. Example:
571 suppose the host defaults to one compiler (say Clang) and the
572 user wishes to use another compiler (say GCC). Set configura‐
573 tion preset environment variables CC and CXX and use a build
574 preset that inherits that configuration preset. Otherwise the
575 ExternalProject may use a different (system default) compiler
576 than the top-level CMake project.
577 configurePreset
579 An optional string specifying the name of a configure preset to
580 associate with this build preset. If configurePreset is not
581 specified, it must be inherited from the inherits preset (unless
582 this preset is hidden). The build directory is inferred from the
583 configure preset, so the build will take place in the same bina‐
584 ryDir that the configuration did.
585 inheritConfigureEnvironment
587 An optional boolean that defaults to true. If true, the environ‐
588 ment variables from the associated configure preset are inher‐
589 ited after all inherited build preset environments, but before
590 environment variables explicitly specified in this build preset.
591 jobs An optional integer. Equivalent to passing --parallel or -j on
593 the command line.
594 targets
596 An optional string or array of strings. Equivalent to passing
597 --target or -t on the command line. Vendors may ignore the tar‐
598 gets property or hide build presets that explicitly specify tar‐
599 gets. This field supports macro expansion.
600 configuration
602 An optional string. Equivalent to passing --config on the com‐
603 mand line.
604 cleanFirst
606 An optional bool. If true, equivalent to passing --clean-first
607 on the command line.
608 resolvePackageReferences
610 An optional string that specifies the package resolve mode. This
611 is allowed in preset files specifying version 4 or above.
612 Package references are used to define dependencies to packages
614 from external package managers. Currently only NuGet in combina‐
615 tion with the Visual Studio generator is supported. If there are
616 no targets that define package references, this option does
617 nothing. Valid values are:
618 on Causes package references to be resolved before attempt‐
620 ing a build.
621 off Package references will not be resolved. Note that this
623 may cause errors in some build environments, such as .NET
624 SDK style projects.
625 only Only resolve package references, but do not perform a
627 build.
628 NOTE:
630 The command line parameter --resolve-package-references will
631 take priority over this setting. If the command line parame‐
632 ter is not provided and this setting is not specified, an en‐
633 vironment-specific cache variable will be evaluated to de‐
634 cide, if package restoration should be performed.
635 When using the Visual Studio generator, package references
637 are defined using the VS_PACKAGE_REFERENCES property. Package
638 references are restored using NuGet. It can be disabled by
639 setting the CMAKE_VS_NUGET_PACKAGE_RESTORE variable to OFF.
640 This can also be done from within a configure preset.
641 verbose
643 An optional bool. If true, equivalent to passing --verbose on
644 the command line.
645 nativeToolOptions
647 An optional array of strings. Equivalent to passing options af‐
648 ter -- on the command line. The array values support macro ex‐
649 pansion.
650 Test Preset
652 Each entry of the testPresets array is a JSON object that may contain
653 the following fields:
654 name A required string representing the machine-friendly name of the
656 preset. This identifier is used in the ctest --preset option.
657 There must not be two test presets in the union of CMakePre‐
658 sets.json and CMakeUserPresets.json in the same directory with
659 the same name. However, a test preset may have the same name as
660 a configure, build, package, or workflow preset.
661 hidden An optional boolean specifying whether or not a preset should be
663 hidden. If a preset is hidden, it cannot be used in the
664 --preset argument and does not have to have a valid configureP‐
665 reset, even from inheritance. hidden presets are intended to be
666 used as a base for other presets to inherit via the inherits
667 field.
668 inherits
670 An optional array of strings representing the names of presets
671 to inherit from. This field can also be a string, which is
672 equivalent to an array containing one string.
673 The preset will inherit all of the fields from the inherits pre‐
675 sets by default (except name, hidden, inherits, description, and
676 displayName), but can override them as desired. If multiple in‐
677 herits presets provide conflicting values for the same field,
678 the earlier preset in the inherits array will be preferred.
679 A preset can only inherit from another preset that is defined in
681 the same file or in one of the files it includes (directly or
682 indirectly). Presets in CMakePresets.json may not inherit from
683 presets in CMakeUserPresets.json.
684 condition
686 An optional Condition object. This is allowed in preset files
687 specifying version 3 or above.
688 vendor An optional map containing vendor-specific information. CMake
690 does not interpret the contents of this field except to verify
691 that it is a map if it does exist. However, it should follow the
692 same conventions as the root-level vendor field. If vendors use
693 their own per-preset vendor field, they should implement inheri‐
694 tance in a sensible manner when appropriate.
695 displayName
697 An optional string with a human-friendly name of the preset.
698 description
700 An optional string with a human-friendly description of the pre‐
701 set.
702 environment
704 An optional map of environment variables. The key is the vari‐
705 able name (which may not be an empty string), and the value is
706 either null or a string representing the value of the variable.
707 Each variable is set regardless of whether or not a value was
708 given to it by the process's environment. This field supports
709 macro expansion, and environment variables in this map may ref‐
710 erence each other, and may be listed in any order, as long as
711 such references do not cause a cycle (for example, if ENV_1 is
712 $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)
713 Environment variables are inherited through the inherits field,
715 and the preset's environment will be the union of its own envi‐
716 ronment and the environment from all its parents. If multiple
717 presets in this union define the same variable, the standard
718 rules of inherits are applied. Setting a variable to null causes
719 it to not be set, even if a value was inherited from another
720 preset.
721 configurePreset
723 An optional string specifying the name of a configure preset to
724 associate with this test preset. If configurePreset is not spec‐
725 ified, it must be inherited from the inherits preset (unless
726 this preset is hidden). The build directory is inferred from the
727 configure preset, so tests will run in the same binaryDir that
728 the configuration did and build did.
729 inheritConfigureEnvironment
731 An optional boolean that defaults to true. If true, the environ‐
732 ment variables from the associated configure preset are inher‐
733 ited after all inherited test preset environments, but before
734 environment variables explicitly specified in this test preset.
735 configuration
737 An optional string. Equivalent to passing --build-config on the
738 command line.
739 overwriteConfigurationFile
741 An optional array of configuration options to overwrite options
742 specified in the CTest configuration file. Equivalent to passing
743 --overwrite for each value in the array. The array values sup‐
744 port macro expansion.
745 output An optional object specifying output options. The object may
747 contain the following fields.
748 shortProgress
750 An optional bool. If true, equivalent to passing
751 --progress on the command line.
752 verbosity
754 An optional string specifying verbosity level. Must be
755 one of the following:
756 default
758 Equivalent to passing no verbosity flags on the
759 command line.
760 verbose
762 Equivalent to passing --verbose on the command
763 line.
764 extra Equivalent to passing --extra-verbose on the com‐
766 mand line.
767 debug An optional bool. If true, equivalent to passing --debug
769 on the command line.
770 outputOnFailure
772 An optional bool. If true, equivalent to passing
773 --output-on-failure on the command line.
774 quiet An optional bool. If true, equivalent to passing --quiet
776 on the command line.
777 outputLogFile
779 An optional string specifying a path to a log file.
780 Equivalent to passing --output-log on the command line.
781 This field supports macro expansion.
782 outputJUnitFile
784 An optional string specifying a path to a JUnit file.
785 Equivalent to passing --output-junit on the command line.
786 This field supports macro expansion. This is allowed in
787 preset files specifying version 6 or above.
788 labelSummary
790 An optional bool. If false, equivalent to passing
791 --no-label-summary on the command line.
792 subprojectSummary
794 An optional bool. If false, equivalent to passing
795 --no-subproject-summary on the command line.
796 maxPassedTestOutputSize
798 An optional integer specifying the maximum output for
799 passed tests in bytes. Equivalent to passing
800 --test-output-size-passed on the command line.
801 maxFailedTestOutputSize
803 An optional integer specifying the maximum output for
804 failed tests in bytes. Equivalent to passing
805 --test-output-size-failed on the command line.
806 testOutputTruncation
808 An optional string specifying the test output truncation
809 mode. Equivalent to passing --test-output-truncation on
810 the command line. This is allowed in preset files speci‐
811 fying version 5 or above.
812 maxTestNameWidth
814 An optional integer specifying the maximum width of a
815 test name to output. Equivalent to passing --max-width on
816 the command line.
817 filter An optional object specifying how to filter the tests to run.
819 The object may contain the following fields.
820 include
822 An optional object specifying which tests to include. The
823 object may contain the following fields.
824 name An optional string specifying a regex for test
826 names. Equivalent to passing --tests-regex on the
827 command line. This field supports macro expansion.
828 CMake regex syntax is described under
829 string(REGEX).
830 label An optional string specifying a regex for test la‐
832 bels. Equivalent to passing --label-regex on the
833 command line. This field supports macro expansion.
834 useUnion
836 An optional bool. Equivalent to passing --union on
837 the command line.
838 index An optional object specifying tests to include by
840 test index. The object may contain the following
841 fields. Can also be an optional string specifying
842 a file with the command line syntax for
843 --tests-information. If specified as a string,
844 this field supports macro expansion.
845 start An optional integer specifying a test index
847 to start testing at.
848 end An optional integer specifying a test index
850 to stop testing at.
851 stride An optional integer specifying the incre‐
853 ment.
854 specificTests
856 An optional array of integers specifying
857 specific test indices to run.
858 exclude
860 An optional object specifying which tests to exclude. The
861 object may contain the following fields.
862 name An optional string specifying a regex for test
864 names. Equivalent to passing --exclude-regex on
865 the command line. This field supports macro expan‐
866 sion.
867 label An optional string specifying a regex for test la‐
869 bels. Equivalent to passing --label-exclude on the
870 command line. This field supports macro expansion.
871 fixtures
873 An optional object specifying which fixtures to
874 exclude from adding tests. The object may contain
875 the following fields.
876 any An optional string specifying a regex for
878 text fixtures to exclude from adding any
879 tests. Equivalent to --fixture-exclude-any
880 on the command line. This field supports
881 macro expansion.
882 setup An optional string specifying a regex for
884 text fixtures to exclude from adding setup
885 tests. Equivalent to
886 --fixture-exclude-setup on the command
887 line. This field supports macro expansion.
888 cleanup
890 An optional string specifying a regex for
891 text fixtures to exclude from adding
892 cleanup tests. Equivalent to
893 --fixture-exclude-cleanup on the command
894 line. This field supports macro expansion.
895 execution
897 An optional object specifying options for test execution. The
898 object may contain the following fields.
899 stopOnFailure
901 An optional bool. If true, equivalent to passing
902 --stop-on-failure on the command line.
903 enableFailover
905 An optional bool. If true, equivalent to passing -F on
906 the command line.
907 jobs An optional integer. Equivalent to passing --parallel on
909 the command line.
910 resourceSpecFile
912 An optional string. Equivalent to passing
913 --resource-spec-file on the command line. This field sup‐
914 ports macro expansion.
915 testLoad
917 An optional integer. Equivalent to passing --test-load on
918 the command line.
919 showOnly
921 An optional string. Equivalent to passing --show-only on
922 the command line. The string must be one of the following
923 values:
924 human
926 json-v1
928 repeat An optional object specifying how to repeat tests. Equiv‐
930 alent to passing --repeat on the command line. The ob‐
931 ject must have the following fields.
932 mode A required string. Must be one of the following
934 values:
935 until-fail
937 until-pass
939 after-timeout
941 count A required integer.
943 interactiveDebugging
945 An optional bool. If true, equivalent to passing
946 --interactive-debug-mode 1 on the command line. If false,
947 equivalent to passing --interactive-debug-mode 0 on the
948 command line.
949 scheduleRandom
951 An optional bool. If true, equivalent to passing
952 --schedule-random on the command line.
953 timeout
955 An optional integer. Equivalent to passing --timeout on
956 the command line.
957 noTestsAction
959 An optional string specifying the behavior if no tests
960 are found. Must be one of the following values:
961 default
963 Equivalent to not passing any value on the command
964 line.
965 error Equivalent to passing --no-tests=error on the com‐
967 mand line.
968 ignore Equivalent to passing --no-tests=ignore on the
970 command line.
971 Package Preset
973 Package presets may be used in schema version 6 or above. Each entry of
974 the packagePresets array is a JSON object that may contain the follow‐
975 ing fields:
976 name A required string representing the machine-friendly name of the
978 preset. This identifier is used in the cpack --preset option.
979 There must not be two package presets in the union of CMakePre‐
980 sets.json and CMakeUserPresets.json in the same directory with
981 the same name. However, a package preset may have the same name
982 as a configure, build, test, or workflow preset.
983 hidden An optional boolean specifying whether or not a preset should be
985 hidden. If a preset is hidden, it cannot be used in the
986 --preset argument and does not have to have a valid configureP‐
987 reset, even from inheritance. hidden presets are intended to be
988 used as a base for other presets to inherit via the inherits
989 field.
990 inherits
992 An optional array of strings representing the names of presets
993 to inherit from. This field can also be a string, which is
994 equivalent to an array containing one string.
995 The preset will inherit all of the fields from the inherits pre‐
997 sets by default (except name, hidden, inherits, description, and
998 displayName), but can override them as desired. If multiple in‐
999 herits presets provide conflicting values for the same field,
1000 the earlier preset in the inherits array will be preferred.
1001 A preset can only inherit from another preset that is defined in
1003 the same file or in one of the files it includes (directly or
1004 indirectly). Presets in CMakePresets.json may not inherit from
1005 presets in CMakeUserPresets.json.
1006 condition
1008 An optional Condition object.
1009 vendor An optional map containing vendor-specific information. CMake
1011 does not interpret the contents of this field except to verify
1012 that it is a map if it does exist. However, it should follow the
1013 same conventions as the root-level vendor field. If vendors use
1014 their own per-preset vendor field, they should implement inheri‐
1015 tance in a sensible manner when appropriate.
1016 displayName
1018 An optional string with a human-friendly name of the preset.
1019 description
1021 An optional string with a human-friendly description of the pre‐
1022 set.
1023 environment
1025 An optional map of environment variables. The key is the vari‐
1026 able name (which may not be an empty string), and the value is
1027 either null or a string representing the value of the variable.
1028 Each variable is set regardless of whether or not a value was
1029 given to it by the process's environment. This field supports
1030 macro expansion, and environment variables in this map may ref‐
1031 erence each other, and may be listed in any order, as long as
1032 such references do not cause a cycle (for example, if ENV_1 is
1033 $env{ENV_2}, ENV_2 may not be $env{ENV_1}.)
1034 Environment variables are inherited through the inherits field,
1036 and the preset's environment will be the union of its own envi‐
1037 ronment and the environment from all its parents. If multiple
1038 presets in this union define the same variable, the standard
1039 rules of inherits are applied. Setting a variable to null causes
1040 it to not be set, even if a value was inherited from another
1041 preset.
1042 configurePreset
1044 An optional string specifying the name of a configure preset to
1045 associate with this package preset. If configurePreset is not
1046 specified, it must be inherited from the inherits preset (unless
1047 this preset is hidden). The build directory is inferred from the
1048 configure preset, so packaging will run in the same binaryDir
1049 that the configuration did and build did.
1050 inheritConfigureEnvironment
1052 An optional boolean that defaults to true. If true, the environ‐
1053 ment variables from the associated configure preset are inher‐
1054 ited after all inherited package preset environments, but before
1055 environment variables explicitly specified in this package pre‐
1056 set.
1057 generators
1059 An optional array of strings representing generators for CPack
1060 to use.
1061 configurations
1063 An optional array of strings representing build configurations
1064 for CPack to package.
1065 variables
1067 An optional map of variables to pass to CPack, equivalent to -D
1068 arguments. Each key is the name of a variable, and the value is
1069 the string to assign to that variable.
1070 configFile
1072 An optional string representing the config file for CPack to
1073 use.
1074 output An optional object specifying output options. Valid keys are:
1076 debug An optional boolean specifying whether or not to print
1078 debug information. A value of true is equivalent to
1079 passing --debug on the command line.
1080 verbose
1082 An optional boolean specifying whether or not to print
1083 verbosely. A value of true is equivalent to passing
1084 --verbose on the command line.
1085 packageName
1087 An optional string representing the package name.
1088 packageVersion
1090 An optional string representing the package version.
1091 packageDirectory
1093 An optional string representing the directory in which to place
1094 the package.
1095 vendorName
1097 An optional string representing the vendor name.
1098 Workflow Preset
1100 Workflow presets may be used in schema version 6 or above. Each entry
1101 of the workflowPresets array is a JSON object that may contain the fol‐
1102 lowing fields:
1103 name A required string representing the machine-friendly name of the
1105 preset. This identifier is used in the cmake --workflow --pre‐
1106 set option. There must not be two workflow presets in the union
1107 of CMakePresets.json and CMakeUserPresets.json in the same di‐
1108 rectory with the same name. However, a workflow preset may have
1109 the same name as a configure, build, test, or package preset.
1110 vendor An optional map containing vendor-specific information. CMake
1112 does not interpret the contents of this field except to verify
1113 that it is a map if it does exist. However, it should follow the
1114 same conventions as the root-level vendor field.
1115 displayName
1117 An optional string with a human-friendly name of the preset.
1118 description
1120 An optional string with a human-friendly description of the pre‐
1121 set.
1122 steps A required array of objects describing the steps of the work‐
1124 flow. The first step must be a configure preset, and all subse‐
1125 quent steps must be non- configure presets whose configurePreset
1126 field matches the starting configure preset. Each object may
1127 contain the following fields:
1128 type A required string. The first step must be configure. Sub‐
1130 sequent steps must be either build, test, or package.
1131 name A required string representing the name of the configure,
1133 build, test, or package preset to run as this workflow
1134 step.
1135 Condition
1137 The condition field of a preset, allowed in preset files specifying
1138 version 3 or above, is used to determine whether or not the preset is
1139 enabled. For example, this can be used to disable a preset on platforms
1140 other than Windows. condition may be either a boolean, null, or an ob‐
1141 ject. If it is a boolean, the boolean indicates whether the preset is
1142 enabled or disabled. If it is null, the preset is enabled, but the null
1143 condition is not inherited by any presets that may inherit from the
1144 preset. Sub-conditions (for example in a not, anyOf, or allOf condi‐
1145 tion) may not be null. If it is an object, it has the following fields:
1146 type A required string with one of the following values:
1148 "const"
1150 Indicates that the condition is constant. This is equiva‐
1151 lent to using a boolean in place of the object. The con‐
1152 dition object will have the following additional fields:
1153 value A required boolean which provides a constant value
1155 for the condition's evaluation.
1156 "equals"
1158 "notEquals"
1160 Indicates that the condition compares two strings to see
1161 if they are equal (or not equal). The condition object
1162 will have the following additional fields:
1163 lhs First string to compare. This field supports macro
1165 expansion.
1166 rhs Second string to compare. This field supports
1168 macro expansion.
1169 "inList"
1171 "notInList"
1173 Indicates that the condition searches for a string in a
1174 list of strings. The condition object will have the fol‐
1175 lowing additional fields:
1176 string A required string to search for. This field sup‐
1178 ports macro expansion.
1179 list A required array of strings to search. This field
1181 supports macro expansion, and uses short-circuit
1182 evaluation.
1183 "matches"
1185 "notMatches"
1187 Indicates that the condition searches for a regular ex‐
1188 pression in a string. The condition object will have the
1189 following additional fields:
1190 string A required string to search. This field supports
1192 macro expansion.
1193 regex A required regular expression to search for. This
1195 field supports macro expansion.
1196 "anyOf"
1198 "allOf"
1200 Indicates that the condition is an aggregation of zero or
1201 more nested conditions. The condition object will have the
1202 following additional fields:
1203 conditions
1205 A required array of condition objects. These condi‐
1206 tions use short-circuit evaluation.
1207 "not" Indicates that the condition is an inversion of another
1209 condition. The condition object will have the following
1210 additional fields:
1211 condition
1213 A required condition object.
1214 Macro Expansion
1216 As mentioned above, some fields support macro expansion. Macros are
1217 recognized in the form $<macro-namespace>{<macro-name>}. All macros are
1218 evaluated in the context of the preset being used, even if the macro is
1219 in a field that was inherited from another preset. For example, if the
1220 Base preset sets variable PRESET_NAME to ${presetName}, and the Derived
1221 preset inherits from Base, PRESET_NAME will be set to Derived.
1222 It is an error to not put a closing brace at the end of a macro name.
1224 For example, ${sourceDir is invalid. A dollar sign ($) followed by any‐
1225 thing other than a left curly brace ({) with a possible namespace is
1226 interpreted as a literal dollar sign.
1227 Recognized macros include:
1229 ${sourceDir}
1231 Path to the project source directory (i.e. the same as
1232 CMAKE_SOURCE_DIR).
1233 ${sourceParentDir}
1235 Path to the project source directory's parent directory.
1236 ${sourceDirName}
1238 The last filename component of ${sourceDir}. For example, if
1239 ${sourceDir} is /path/to/source, this would be source.
1240 ${presetName}
1242 Name specified in the preset's name field.
1243 ${generator}
1245 Generator specified in the preset's generator field. For build
1246 and test presets, this will evaluate to the generator specified
1247 by configurePreset.
1248 ${hostSystemName}
1250 The name of the host operating system. Contains the same value
1251 as CMAKE_HOST_SYSTEM_NAME. This is allowed in preset files spec‐
1252 ifying version 3 or above.
1253 ${fileDir}
1255 Path to the directory containing the preset file which contains
1256 the macro. This is allowed in preset files specifying version 4
1257 or above.
1258 ${dollar}
1260 A literal dollar sign ($).
1261 ${pathListSep}
1263 Native character for separating lists of paths, such as : or ;.
1264 For example, by setting PATH to /path/to/ninja/bin${pathList‐
1266 Sep}$env{PATH}, ${pathListSep} will expand to the underlying op‐
1267 erating system's character used for concatenation in PATH.
1268 This is allowed in preset files specifying version 5 or above.
1270 $env{<variable-name>}
1272 Environment variable with name <variable-name>. The variable
1273 name may not be an empty string. If the variable is defined in
1274 the environment field, that value is used instead of the value
1275 from the parent environment. If the environment variable is not
1276 defined, this evaluates as an empty string.
1277 Note that while Windows environment variable names are case-in‐
1279 sensitive, variable names within a preset are still case-sensi‐
1280 tive. This may lead to unexpected results when using inconsis‐
1281 tent casing. For best results, keep the casing of environment
1282 variable names consistent.
1283 $penv{<variable-name>}
1285 Similar to $env{<variable-name>}, except that the value only
1286 comes from the parent environment, and never from the environ‐
1287 ment field. This allows you to prepend or append values to ex‐
1288 isting environment variables. For example, setting PATH to
1289 /path/to/ninja/bin:$penv{PATH} will prepend /path/to/ninja/bin
1290 to the PATH environment variable. This is needed because
1291 $env{<variable-name>} does not allow circular references.
1292 $vendor{<macro-name>}
1294 An extension point for vendors to insert their own macros. CMake
1295 will not be able to use presets which have a $ven‐
1296 dor{<macro-name>} macro, and effectively ignores such presets.
1297 However, it will still be able to use other presets from the
1298 same file.
1299 CMake does not make any attempt to interpret $ven‐
1301 dor{<macro-name>} macros. However, to avoid name collisions, IDE
1302 vendors should prefix <macro-name> with a very short (preferably
1303 <= 4 characters) vendor identifier prefix, followed by a ., fol‐
1304 lowed by the macro name. For example, the Example IDE could have
1305 $vendor{xide.ideInstallDir}.
1306
1308 This file provides a machine-readable JSON schema for the CMakePre‐
1309 sets.json format.
1310
1312 2000-2023 Kitware, Inc. and Contributors
13133.27.7 Oct 07, 2023 CMAKE-PRESETS(7)