1CMAKE-PRESETS(7) CMake CMAKE-PRESETS(7)
2
6 cmake-presets - CMakePresets.json
7
9 One problem that CMake users often face is sharing settings with other
10 people for common ways to configure a project. This may be done to sup‐
11 port CI builds, or for users who frequently use the same build. CMake
12 supports two files, CMakePresets.json and CMakeUserPresets.json, that
13 allow users to specify common configure options and share them with
14 others.
15 CMakePresets.json and CMakeUserPresets.json live in the project's root
17 directory. They both have exactly the same format, and both are op‐
18 tional (though at least one must be present if --preset is specified.)
19 CMakePresets.json is meant to save project-wide builds, while
20 CMakeUserPresets.json is meant for developers to save their own local
21 builds. CMakePresets.json may be checked into a version control system,
22 and CMakeUserPresets.json should NOT be checked in. For example, if a
23 project is using Git, CMakePresets.json may be tracked, and CMakeUserP‐
24 resets.json should be added to the .gitignore.
25
27 The files are a JSON document with an object as the root:
28 {
30 "version": 3,
31 "cmakeMinimumRequired": {
32 "major": 3,
33 "minor": 21,
34 "patch": 0
35 },
36 "configurePresets": [
37 {
38 "name": "default",
39 "displayName": "Default Config",
40 "description": "Default build using Ninja generator",
41 "generator": "Ninja",
42 "binaryDir": "${sourceDir}/build/default",
43 "cacheVariables": {
44 "FIRST_CACHE_VARIABLE": {
45 "type": "BOOL",
46 "value": "OFF"
47 },
48 "SECOND_CACHE_VARIABLE": "ON"
49 },
50 "environment": {
51 "MY_ENVIRONMENT_VARIABLE": "Test",
52 "PATH": "$env{HOME}/ninja/bin:$penv{PATH}"
53 },
54 "vendor": {
55 "example.com/ExampleIDE/1.0": {
56 "autoFormat": true
57 }
58 }
59 },
60 {
61 "name": "ninja-multi",
62 "inherits": "default",
63 "displayName": "Ninja Multi-Config",
64 "description": "Default build using Ninja Multi-Config generator",
65 "generator": "Ninja Multi-Config"
66 },
67 {
68 "name": "windows-only",
69 "inherits": "default",
70 "displayName": "Windows-only configuration",
71 "description": "This build is only available on Windows",
72 "condition": {
73 "type": "equals",
74 "lhs": "${hostSystemName}",
75 "rhs": "Windows"
76 }
77 }
78 ],
79 "buildPresets": [
80 {
81 "name": "default",
82 "configurePreset": "default"
83 }
84 ],
85 "testPresets": [
86 {
87 "name": "default",
88 "configurePreset": "default",
89 "output": {"outputOnFailure": true},
90 "execution": {"noTestsAction": "error", "stopOnFailure": true}
91 }
92 ],
93 "vendor": {
94 "example.com/ExampleIDE/1.0": {
95 "autoFormat": false
96 }
97 }
98 }
99 The root object recognizes the following fields:
102 version
104 A required integer representing the version of the JSON schema. The
105 supported versions are 1, 2, and 3.
106 cmakeMinimumRequired
108 An optional object representing the minimum version of CMake needed
109 to build this project. This object consists of the following fields:
110 major
112 An optional integer representing the major version.
113 minor
115 An optional integer representing the minor version.
116 patch
118 An optional integer representing the patch version.
119 vendor
121 An optional map containing vendor-specific information. CMake does
122 not interpret the contents of this field except to verify that it is
123 a map if it does exist. However, the keys should be a vendor-spe‐
124 cific domain name followed by a /-separated path. For example, the
125 Example IDE 1.0 could use example.com/ExampleIDE/1.0. The value of
126 each field can be anything desired by the vendor, though will typi‐
127 cally be a map.
128 configurePresets
130 An optional array of Configure Preset objects. This is allowed in
131 preset files specifying version 1 or above.
132 buildPresets
134 An optional array of Build Preset objects. This is allowed in pre‐
135 set files specifying version 2 or above.
136 testPresets
138 An optional array of Test Preset objects. This is allowed in preset
139 files specifying version 2 or above.
140 Configure Preset
142 Each entry of the configurePresets array is a JSON object that may con‐
143 tain the following fields:
144 name
146 A required string representing the machine-friendly name of the pre‐
147 set. This identifier is used in the cmake --preset option. There
148 must not be two configure presets in the union of CMakePresets.json
149 and CMakeUserPresets.json in the same directory with the same name.
150 However, a configure preset may have the same name as a build or
151 test preset.
152 hidden
154 An optional boolean specifying whether or not a preset should be
155 hidden. If a preset is hidden, it cannot be used in the --preset=
156 argument, will not show up in the CMake GUI, and does not have to
157 have a valid generator or binaryDir, even from inheritance. hidden
158 presets are intended to be used as a base for other presets to in‐
159 herit via the inherits field.
160 inherits
162 An optional array of strings representing the names of presets to
163 inherit from. The preset will inherit all of the fields from the in‐
164 herits presets by default (except name, hidden, inherits, descrip‐
165 tion, and displayName), but can override them as desired. If multi‐
166 ple inherits presets provide conflicting values for the same field,
167 the earlier preset in the inherits list will be preferred. Presets
168 in CMakePresets.json may not inherit from presets in CMakeUserPre‐
169 sets.json.
170 This field can also be a string, which is equivalent to an array
172 containing one string.
173 condition
175 An optional Condition object. This is allowed in preset files speci‐
176 fying version 3 or above.
177 vendor
179 An optional map containing vendor-specific information. CMake does
180 not interpret the contents of this field except to verify that it is
181 a map if it does exist. However, it should follow the same conven‐
182 tions as the root-level vendor field. If vendors use their own
183 per-preset vendor field, they should implement inheritance in a sen‐
184 sible manner when appropriate.
185 displayName
187 An optional string with a human-friendly name of the preset.
188 description
190 An optional string with a human-friendly description of the preset.
191 generator
193 An optional string representing the generator to use for the preset.
194 If generator is not specified, it must be inherited from the inher‐
195 its preset (unless this preset is hidden). In version 3 or above,
196 this field may be omitted to fall back to regular generator discov‐
197 ery procedure.
198 Note that for Visual Studio generators, unlike in the command line
200 -G argument, you cannot include the platform name in the generator
201 name. Use the architecture field instead.
202 architecture, toolset
204 Optional fields representing the platform and toolset, respectively,
205 for generators that support them. Each may be either a string or an
206 object with the following fields:
207 value
209 An optional string representing the value.
210 strategy
212 An optional string telling CMake how to handle the architecture
213 or toolset field. Valid values are:
214 "set"
216 Set the respective value. This will result in an error for
217 generators that do not support the respective field.
218 "external"
220 Do not set the value, even if the generator supports it. This
221 is useful if, for example, a preset uses the Ninja generator,
222 and an IDE knows how to set up the Visual C++ environment
223 from the architecture and toolset fields. In that case, CMake
224 will ignore the field, but the IDE can use them to set up the
225 environment before invoking CMake.
226 toolchainFile
228 An optional string representing the path to the toolchain file.
229 This field supports macro expansion. If a relative path is speci‐
230 fied, it is calculated relative to the build directory, and if not
231 found, relative to the source directory. This field takes precedence
232 over any CMAKE_TOOLCHAIN_FILE value. It is allowed in preset files
233 specifying version 3 or above.
234 binaryDir
236 An optional string representing the path to the output binary direc‐
237 tory. This field supports macro expansion. If a relative path is
238 specified, it is calculated relative to the source directory. If bi‐
239 naryDir is not specified, it must be inherited from the inherits
240 preset (unless this preset is hidden). In version 3 or above, this
241 field may be omitted.
242 installDir
244 An optional string representing the path to the installation direc‐
245 tory. This field supports macro expansion. If a relative path is
246 specified, it is calculated relative to the source directory. This
247 is allowed in preset files specifying version 3 or above.
248 cmakeExecutable
250 An optional string representing the path to the CMake executable to
251 use for this preset. This is reserved for use by IDEs, and is not
252 used by CMake itself. IDEs that use this field should expand any
253 macros in it.
254 cacheVariables
256 An optional map of cache variables. The key is the variable name
257 (which may not be an empty string), and the value is either null, a
258 boolean (which is equivalent to a value of "TRUE" or "FALSE" and a
259 type of BOOL), a string representing the value of the variable
260 (which supports macro expansion), or an object with the following
261 fields:
262 type
264 An optional string representing the type of the variable.
265 value
267 A required string or boolean representing the value of the vari‐
268 able. A boolean is equivalent to "TRUE" or "FALSE". This field
269 supports macro expansion.
270 Cache variables are inherited through the inherits field, and the
272 preset's variables will be the union of its own cacheVariables and
273 the cacheVariables from all its parents. If multiple presets in this
274 union define the same variable, the standard rules of inherits are
275 applied. Setting a variable to null causes it to not be set, even if
276 a value was inherited from another preset.
277 environment
279 An optional map of environment variables. The key is the variable
280 name (which may not be an empty string), and the value is either
281 null or a string representing the value of the variable. Each vari‐
282 able is set regardless of whether or not a value was given to it by
283 the process's environment. This field supports macro expansion, and
284 environment variables in this map may reference each other, and may
285 be listed in any order, as long as such references do not cause a
286 cycle (for example, if ENV_1 is $env{ENV_2}, ENV_2 may not be
287 $env{ENV_1}.)
288 Environment variables are inherited through the inherits field, and
290 the preset's environment will be the union of its own environment
291 and the environment from all its parents. If multiple presets in
292 this union define the same variable, the standard rules of inherits
293 are applied. Setting a variable to null causes it to not be set,
294 even if a value was inherited from another preset.
295 warnings
297 An optional object specifying the warnings to enable. The object may
298 contain the following fields:
299 dev
301 An optional boolean. Equivalent to passing -Wdev or -Wno-dev on
302 the command line. This may not be set to false if errors.dev is
303 set to true.
304 deprecated
306 An optional boolean. Equivalent to passing -Wdeprecated or
307 -Wno-deprecated on the command line. This may not be set to
308 false if errors.deprecated is set to true.
309 uninitialized
311 An optional boolean. Setting this to true is equivalent to pass‐
312 ing --warn-uninitialized on the command line.
313 unusedCli
315 An optional boolean. Setting this to false is equivalent to
316 passing --no-warn-unused-cli on the command line.
317 systemVars
319 An optional boolean. Setting this to true is equivalent to pass‐
320 ing --check-system-vars on the command line.
321 errors
323 An optional object specifying the errors to enable. The object may
324 contain the following fields:
325 dev
327 An optional boolean. Equivalent to passing -Werror=dev or
328 -Wno-error=dev on the command line. This may not be set to true
329 if warnings.dev is set to false.
330 deprecated
332 An optional boolean. Equivalent to passing -Werror=deprecated or
333 -Wno-error=deprecated on the command line. This may not be set
334 to true if warnings.deprecated is set to false.
335 debug
337 An optional object specifying debug options. The object may contain
338 the following fields:
339 output
341 An optional boolean. Setting this to true is equivalent to pass‐
342 ing --debug-output on the command line.
343 tryCompile
345 An optional boolean. Setting this to true is equivalent to pass‐
346 ing --debug-trycompile on the command line.
347 find
349 An optional boolean. Setting this to true is equivalent to pass‐
350 ing --debug-find on the command line.
351 Build Preset
353 Each entry of the buildPresets array is a JSON object that may contain
354 the following fields:
355 name
357 A required string representing the machine-friendly name of the pre‐
358 set. This identifier is used in the cmake --build --preset option.
359 There must not be two build presets in the union of CMakePre‐
360 sets.json and CMakeUserPresets.json in the same directory with the
361 same name. However, a build preset may have the same name as a con‐
362 figure or test preset.
363 hidden
365 An optional boolean specifying whether or not a preset should be
366 hidden. If a preset is hidden, it cannot be used in the --preset
367 argument and does not have to have a valid configurePreset, even
368 from inheritance. hidden presets are intended to be used as a base
369 for other presets to inherit via the inherits field.
370 inherits
372 An optional array of strings representing the names of presets to
373 inherit from. The preset will inherit all of the fields from the in‐
374 herits presets by default (except name, hidden, inherits, descrip‐
375 tion, and displayName), but can override them as desired. If multi‐
376 ple inherits presets provide conflicting values for the same field,
377 the earlier preset in the inherits list will be preferred. Presets
378 in CMakePresets.json may not inherit from presets in CMakeUserPre‐
379 sets.json.
380 This field can also be a string, which is equivalent to an array
382 containing one string.
383 condition
385 An optional Condition object. This is allowed in preset files speci‐
386 fying version 3 or above.
387 vendor
389 An optional map containing vendor-specific information. CMake does
390 not interpret the contents of this field except to verify that it is
391 a map if it does exist. However, it should follow the same conven‐
392 tions as the root-level vendor field. If vendors use their own
393 per-preset vendor field, they should implement inheritance in a sen‐
394 sible manner when appropriate.
395 displayName
397 An optional string with a human-friendly name of the preset.
398 description
400 An optional string with a human-friendly description of the preset.
401 environment
403 An optional map of environment variables. The key is the variable
404 name (which may not be an empty string), and the value is either
405 null or a string representing the value of the variable. Each vari‐
406 able is set regardless of whether or not a value was given to it by
407 the process's environment. This field supports macro expansion, and
408 environment variables in this map may reference each other, and may
409 be listed in any order, as long as such references do not cause a
410 cycle (for example, if ENV_1 is $env{ENV_2}, ENV_2 may not be
411 $env{ENV_1}.)
412 Environment variables are inherited through the inherits field, and
414 the preset's environment will be the union of its own environment
415 and the environment from all its parents. If multiple presets in
416 this union define the same variable, the standard rules of inherits
417 are applied. Setting a variable to null causes it to not be set,
418 even if a value was inherited from another preset.
419 NOTE:
421 For a CMake project using ExternalProject with a configuration
422 preset having environment variables needed in the ExternalPro‐
423 ject, use a build preset that inherits that configuration preset
424 or the ExternalProject will not have the environment variables
425 set in the configuration preset. Example: suppose the host de‐
426 faults to one compiler (say Clang) and the user wishes to use
427 another compiler (say GCC). Set configuration preset environment
428 variables CC and CXX and use a build preset that inherits that
429 configuration preset. Otherwise the ExternalProject may use a
430 different (system default) compiler than the top-level CMake
431 project.
432 configurePreset
434 An optional string specifying the name of a configure preset to as‐
435 sociate with this build preset. If configurePreset is not specified,
436 it must be inherited from the inherits preset (unless this preset is
437 hidden). The build directory is inferred from the configure preset,
438 so the build will take place in the same binaryDir that the configu‐
439 ration did.
440 inheritConfigureEnvironment
442 An optional boolean that defaults to true. If true, the environment
443 variables from the associated configure preset are inherited after
444 all inherited build preset environments, but before environment
445 variables explicitly specified in this build preset.
446 jobs
448 An optional integer. Equivalent to passing --parallel or -j on the
449 command line.
450 targets
452 An optional string or array of strings. Equivalent to passing --tar‐
453 get or -t on the command line. Vendors may ignore the targets prop‐
454 erty or hide build presets that explicitly specify targets. This
455 field supports macro expansion.
456 configuration
458 An optional string. Equivalent to passing --config on the command
459 line.
460 cleanFirst
462 An optional bool. If true, equivalent to passing --clean-first on
463 the command line.
464 verbose
466 An optional bool. If true, equivalent to passing --verbose on the
467 command line.
468 nativeToolOptions
470 An optional array of strings. Equivalent to passing options after --
471 on the command line. The array values support macro expansion.
472 Test Preset
474 Each entry of the testPresets array is a JSON object that may contain
475 the following fields:
476 name
478 A required string representing the machine-friendly name of the pre‐
479 set. This identifier is used in the ctest --preset option. There
480 must not be two test presets in the union of CMakePresets.json and
481 CMakeUserPresets.json in the same directory with the same name.
482 However, a test preset may have the same name as a configure or
483 build preset.
484 hidden
486 An optional boolean specifying whether or not a preset should be
487 hidden. If a preset is hidden, it cannot be used in the --preset
488 argument and does not have to have a valid configurePreset, even
489 from inheritance. hidden presets are intended to be used as a base
490 for other presets to inherit via the inherits field.
491 inherits
493 An optional array of strings representing the names of presets to
494 inherit from. The preset will inherit all of the fields from the in‐
495 herits presets by default (except name, hidden, inherits, descrip‐
496 tion, and displayName), but can override them as desired. If multi‐
497 ple inherits presets provide conflicting values for the same field,
498 the earlier preset in the inherits list will be preferred. Presets
499 in CMakePresets.json may not inherit from presets in CMakeUserPre‐
500 sets.json.
501 This field can also be a string, which is equivalent to an array
503 containing one string.
504 condition
506 An optional Condition object. This is allowed in preset files speci‐
507 fying version 3 or above.
508 vendor
510 An optional map containing vendor-specific information. CMake does
511 not interpret the contents of this field except to verify that it is
512 a map if it does exist. However, it should follow the same conven‐
513 tions as the root-level vendor field. If vendors use their own
514 per-preset vendor field, they should implement inheritance in a sen‐
515 sible manner when appropriate.
516 displayName
518 An optional string with a human-friendly name of the preset.
519 description
521 An optional string with a human-friendly description of the preset.
522 environment
524 An optional map of environment variables. The key is the variable
525 name (which may not be an empty string), and the value is either
526 null or a string representing the value of the variable. Each vari‐
527 able is set regardless of whether or not a value was given to it by
528 the process's environment. This field supports macro expansion, and
529 environment variables in this map may reference each other, and may
530 be listed in any order, as long as such references do not cause a
531 cycle (for example, if ENV_1 is $env{ENV_2}, ENV_2 may not be
532 $env{ENV_1}.)
533 Environment variables are inherited through the inherits field, and
535 the preset's environment will be the union of its own environment
536 and the environment from all its parents. If multiple presets in
537 this union define the same variable, the standard rules of inherits
538 are applied. Setting a variable to null causes it to not be set,
539 even if a value was inherited from another preset.
540 configurePreset
542 An optional string specifying the name of a configure preset to as‐
543 sociate with this test preset. If configurePreset is not specified,
544 it must be inherited from the inherits preset (unless this preset is
545 hidden). The build directory is inferred from the configure preset,
546 so tests will run in the same binaryDir that the configuration did
547 and build did.
548 inheritConfigureEnvironment
550 An optional boolean that defaults to true. If true, the environment
551 variables from the associated configure preset are inherited after
552 all inherited test preset environments, but before environment vari‐
553 ables explicitly specified in this test preset.
554 configuration
556 An optional string. Equivalent to passing --build-config on the com‐
557 mand line.
558 overwriteConfigurationFile
560 An optional array of configuration options to overwrite options
561 specified in the CTest configuration file. Equivalent to passing
562 --overwrite for each value in the array. The array values support
563 macro expansion.
564 output
566 An optional object specifying output options. The object may contain
567 the following fields.
568 shortProgress
570 An optional bool. If true, equivalent to passing --progress on
571 the command line.
572 verbosity
574 An optional string specifying verbosity level. Must be one of
575 the following:
576 default
578 Equivalent to passing no verbosity flags on the command line.
579 verbose
581 Equivalent to passing --verbose on the command line.
582 extra
584 Equivalent to passing --extra-verbose on the command line.
585 debug
587 An optional bool. If true, equivalent to passing --debug on the
588 command line.
589 outputOnFailure
591 An optional bool. If true, equivalent to passing --out‐
592 put-on-failure on the command line.
593 quiet
595 An optional bool. If true, equivalent to passing --quiet on the
596 command line.
597 outputLogFile
599 An optional string specifying a path to a log file. Equivalent
600 to passing --output-log on the command line. This field supports
601 macro expansion.
602 labelSummary
604 An optional bool. If false, equivalent to passing --no-la‐
605 bel-summary on the command line.
606 subprojectSummary
608 An optional bool. If false, equivalent to passing --no-subpro‐
609 ject-summary on the command line.
610 maxPassedTestOutputSize
612 An optional integer specifying the maximum output for passed
613 tests in bytes. Equivalent to passing --test-output-size-passed
614 on the command line.
615 maxFailedTestOutputSize
617 An optional integer specifying the maximum output for failed
618 tests in bytes. Equivalent to passing --test-output-size-failed
619 on the command line.
620 maxTestNameWidth
622 An optional integer specifying the maximum width of a test name
623 to output. Equivalent to passing --max-width on the command
624 line.
625 filter
627 An optional object specifying how to filter the tests to run. The
628 object may contain the following fields.
629 include
631 An optional object specifying which tests to include. The object
632 may contain the following fields.
633 name
635 An optional string specifying a regex for test names. Equiva‐
636 lent to passing --tests-regex on the command line. This field
637 supports macro expansion. CMake regex syntax is described un‐
638 der string(REGEX).
639 label
641 An optional string specifying a regex for test labels. Equiv‐
642 alent to passing --label-regex on the command line. This
643 field supports macro expansion.
644 useUnion
646 An optional bool. Equivalent to passing --union on the com‐
647 mand line.
648 index
650 An optional object specifying tests to include by test index.
651 The object may contain the following fields. Can also be an
652 optional string specifying a file with the command line syn‐
653 tax for --tests-information. If specified as a string, this
654 field supports macro expansion.
655 start
657 An optional integer specifying a test index to start
658 testing at.
659 end
661 An optional integer specifying a test index to stop test‐
662 ing at.
663 stride
665 An optional integer specifying the increment.
666 specificTests
668 An optional array of integers specifying specific test
669 indices to run.
670 exclude
672 An optional object specifying which tests to exclude. The object
673 may contain the following fields.
674 name
676 An optional string specifying a regex for test names. Equiva‐
677 lent to passing --exclude-regex on the command line. This
678 field supports macro expansion.
679 label
681 An optional string specifying a regex for test labels. Equiv‐
682 alent to passing --label-exclude on the command line. This
683 field supports macro expansion.
684 fixtures
686 An optional object specifying which fixtures to exclude from
687 adding tests. The object may contain the following fields.
688 any
690 An optional string specifying a regex for text fixtures
691 to exclude from adding any tests. Equivalent to --fix‐
692 ture-exclude-any on the command line. This field supports
693 macro expansion.
694 setup
696 An optional string specifying a regex for text fixtures
697 to exclude from adding setup tests. Equivalent to --fix‐
698 ture-exclude-setup on the command line. This field sup‐
699 ports macro expansion.
700 cleanup
702 An optional string specifying a regex for text fixtures
703 to exclude from adding cleanup tests. Equivalent to
704 --fixture-exclude-cleanup on the command line. This field
705 supports macro expansion.
706 execution
708 An optional object specifying options for test execution. The object
709 may contain the following fields.
710 stopOnFailure
712 An optional bool. If true, equivalent to passing --stop-on-fail‐
713 ure on the command line.
714 enableFailover
716 An optional bool. If true, equivalent to passing -F on the com‐
717 mand line.
718 jobs
720 An optional integer. Equivalent to passing --parallel on the
721 command line.
722 resourceSpecFile
724 An optional string. Equivalent to passing --resource-spec-file
725 on the command line. This field supports macro expansion.
726 testLoad
728 An optional integer. Equivalent to passing --test-load on the
729 command line.
730 showOnly
732 An optional string. Equivalent to passing --show-only on the
733 command line. The string must be one of the following values:
734 human
736 json-v1
738 repeat
740 An optional object specifying how to repeat tests. Equivalent to
741 passing --repeat on the command line. The object must have the
742 following fields.
743 mode
745 A required string. Must be one of the following values:
746 until-fail
748 until-pass
750 after-timeout
752 count
754 A required integer.
755 interactiveDebugging
757 An optional bool. If true, equivalent to passing --interac‐
758 tive-debug-mode 1 on the command line. If false, equivalent to
759 passing --interactive-debug-mode 0 on the command line.
760 scheduleRandom
762 An optional bool. If true, equivalent to passing --schedule-ran‐
763 dom on the command line.
764 timeout
766 An optional integer. Equivalent to passing --timeout on the com‐
767 mand line.
768 noTestsAction
770 An optional string specifying the behavior if no tests are
771 found. Must be one of the following values:
772 default
774 Equivalent to not passing any value on the command line.
775 error
777 Equivalent to passing --no-tests=error on the command line.
778 ignore
780 Equivalent to passing --no-tests=ignore on the command line.
781 Condition
783 The condition field of a preset, allowed in preset files specifying
784 version 3 or above, is used to determine whether or not the preset is
785 enabled. For example, this can be used to disable a preset on platforms
786 other than Windows. condition may be either a boolean, null, or an ob‐
787 ject. If it is a boolean, the boolean indicates whether the preset is
788 enabled or disabled. If it is null, the preset is enabled, but the null
789 condition is not inherited by any presets that may inherit from the
790 preset. Sub-conditions (for example in a not, anyOf, or allOf condi‐
791 tion) may not be null. If it is an object, it has the following fields:
792 type
794 A required string with one of the following values:
795 "const"
797 Indicates that the condition is constant. This is equivalent to
798 using a boolean in place of the object. The condition object
799 will have the following additional fields:
800 value
802 A required boolean which provides a constant value for the
803 condition's evaluation.
804 "equals"
806 "notEquals"
808 Indicates that the condition compares two strings to see if they
809 are equal (or not equal). The condition object will have the
810 following additional fields:
811 lhs
813 First string to compare. This field supports macro expansion.
814 rhs
816 Second string to compare. This field supports macro expan‐
817 sion.
818 "inList"
820 "notInList"
822 Indicates that the condition searches for a string in a list of
823 strings. The condition object will have the following addi‐
824 tional fields:
825 string
827 A required string to search for. This field supports macro
828 expansion.
829 list
831 A required list of strings to search. This field supports
832 macro expansion, and uses short-circuit evaluation.
833 "matches"
835 "notMatches"
837 Indicates that the condition searches for a regular expression
838 in a string. The condition object will have the following addi‐
839 tional fields:
840 string
842 A required string to search. This field supports macro expan‐
843 sion.
844 regex
846 A required regular expression to search for. This field sup‐
847 ports macro expansion.
848 "anyOf"
850 "allOf"
852 Indicates that the condition is an aggregation of zero or more
853 nested conditions. The condition object will have the following
854 additional fields:
855 conditions
857 A required array of condition objects. These conditions use
858 short-circuit evaluation.
859 "not"
861 Indicates that the condition is an inversion of another condi‐
862 tion. The condition object will have the following additional
863 fields:
864 condition
866 A required condition object.
867 Macro Expansion
869 As mentioned above, some fields support macro expansion. Macros are
870 recognized in the form $<macro-namespace>{<macro-name>}. All macros are
871 evaluated in the context of the preset being used, even if the macro is
872 in a field that was inherited from another preset. For example, if the
873 Base preset sets variable PRESET_NAME to ${presetName}, and the Derived
874 preset inherits from Base, PRESET_NAME will be set to Derived.
875 It is an error to not put a closing brace at the end of a macro name.
877 For example, ${sourceDir is invalid. A dollar sign ($) followed by any‐
878 thing other than a left curly brace ({) with a possible namespace is
879 interpreted as a literal dollar sign.
880 Recognized macros include:
882 ${sourceDir}
884 Path to the project source directory.
885 ${sourceParentDir}
887 Path to the project source directory's parent directory.
888 ${sourceDirName}
890 The last filename component of ${sourceDir}. For example, if
891 ${sourceDir} is /path/to/source, this would be source.
892 ${presetName}
894 Name specified in the preset's name field.
895 ${generator}
897 Generator specified in the preset's generator field. For build and
898 test presets, this will evaluate to the generator specified by con‐
899 figurePreset.
900 ${hostSystemName}
902 The name of the host operating system. Contains the same value as
903 CMAKE_HOST_SYSTEM_NAME. This is allowed in preset files specifying
904 version 3 or above.
905 ${dollar}
907 A literal dollar sign ($).
908 $env{<variable-name>}
910 Environment variable with name <variable-name>. The variable name
911 may not be an empty string. If the variable is defined in the envi‐
912 ronment field, that value is used instead of the value from the par‐
913 ent environment. If the environment variable is not defined, this
914 evaluates as an empty string.
915 Note that while Windows environment variable names are case-insensi‐
917 tive, variable names within a preset are still case-sensitive. This
918 may lead to unexpected results when using inconsistent casing. For
919 best results, keep the casing of environment variable names consis‐
920 tent.
921 $penv{<variable-name>}
923 Similar to $env{<variable-name>}, except that the value only comes
924 from the parent environment, and never from the environment field.
925 This allows you to prepend or append values to existing environment
926 variables. For example, setting PATH to
927 /path/to/ninja/bin:$penv{PATH} will prepend /path/to/ninja/bin to
928 the PATH environment variable. This is needed because $env{<vari‐
929 able-name>} does not allow circular references.
930 $vendor{<macro-name>}
932 An extension point for vendors to insert their own macros. CMake
933 will not be able to use presets which have a $vendor{<macro-name>}
934 macro, and effectively ignores such presets. However, it will still
935 be able to use other presets from the same file.
936 CMake does not make any attempt to interpret $vendor{<macro-name>}
938 macros. However, to avoid name collisions, IDE vendors should prefix
939 <macro-name> with a very short (preferably <= 4 characters) vendor
940 identifier prefix, followed by a ., followed by the macro name. For
941 example, the Example IDE could have $vendor{xide.ideInstallDir}.
942
944 This file provides a machine-readable JSON schema for the CMakePre‐
945 sets.json format.
946
948 2000-2021 Kitware, Inc. and Contributors
9493.22.0 Dec 02, 2021 CMAKE-PRESETS(7)