1CMAKE-PRESETS(7)                     CMake                    CMAKE-PRESETS(7)
2
3
4

NAME

6       cmake-presets - CMakePresets.json
7

INTRODUCTION

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
16       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

FORMAT

27       The files are a JSON document with an object as the root:
28
29          {
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
100
101       The root object recognizes the following fields:
102
103       version
104          A required integer representing the version of the JSON schema.  The
105          supported versions are 1, 2, and 3.
106
107       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
111          major
112              An optional integer representing the major version.
113
114          minor
115              An optional integer representing the minor version.
116
117          patch
118              An optional integer representing the patch version.
119
120       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
129       configurePresets
130          An optional array of Configure Preset objects.  This is  allowed  in
131          preset files specifying version 1 or above.
132
133       buildPresets
134          An  optional array of Build Preset objects.  This is allowed in pre‐
135          set files specifying version 2 or above.
136
137       testPresets
138          An optional array of Test Preset objects.  This is allowed in preset
139          files specifying version 2 or above.
140
141   Configure Preset
142       Each entry of the configurePresets array is a JSON object that may con‐
143       tain the following fields:
144
145       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
153       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
161       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
171          This  field  can  also  be a string, which is equivalent to an array
172          containing one string.
173
174       condition
175          An optional Condition object. This is allowed in preset files speci‐
176          fying version 3 or above.
177
178       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
186       displayName
187          An optional string with a human-friendly name of the preset.
188
189       description
190          An optional string with a human-friendly description of the preset.
191
192       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
199          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
203       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
208          value
209              An optional string representing the value.
210
211          strategy
212              An optional string telling CMake how to handle the  architecture
213              or toolset field. Valid values are:
214
215              "set"
216                 Set  the  respective  value. This will result in an error for
217                 generators that do not support the respective field.
218
219              "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
227       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
235       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
243       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
249       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
255       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
263          type
264              An optional string representing the type of the variable.
265
266          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
271          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
278       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
289          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
296       warnings
297          An optional object specifying the warnings to enable. The object may
298          contain the following fields:
299
300          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
305          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
310          uninitialized
311              An optional boolean. Setting this to true is equivalent to pass‐
312              ing --warn-uninitialized on the command line.
313
314          unusedCli
315              An optional boolean. Setting this  to  false  is  equivalent  to
316              passing --no-warn-unused-cli on the command line.
317
318          systemVars
319              An optional boolean. Setting this to true is equivalent to pass‐
320              ing --check-system-vars on the command line.
321
322       errors
323          An optional object specifying the errors to enable. The  object  may
324          contain the following fields:
325
326          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
331          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
336       debug
337          An  optional object specifying debug options. The object may contain
338          the following fields:
339
340          output
341              An optional boolean. Setting this to true is equivalent to pass‐
342              ing --debug-output on the command line.
343
344          tryCompile
345              An optional boolean. Setting this to true is equivalent to pass‐
346              ing --debug-trycompile on the command line.
347
348          find
349              An optional boolean. Setting this to true is equivalent to pass‐
350              ing --debug-find on the command line.
351
352   Build Preset
353       Each  entry of the buildPresets array is a JSON object that may contain
354       the following fields:
355
356       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
364       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
371       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
381          This field can also be a string, which is  equivalent  to  an  array
382          containing one string.
383
384       condition
385          An optional Condition object. This is allowed in preset files speci‐
386          fying version 3 or above.
387
388       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
396       displayName
397          An optional string with a human-friendly name of the preset.
398
399       description
400          An optional string with a human-friendly description of the preset.
401
402       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
413          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
420          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
433       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
441       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
447       jobs
448          An optional integer. Equivalent to passing --parallel or -j  on  the
449          command line.
450
451       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
457       configuration
458          An optional string. Equivalent to passing --config  on  the  command
459          line.
460
461       cleanFirst
462          An  optional  bool.  If true, equivalent to passing --clean-first on
463          the command line.
464
465       verbose
466          An optional bool. If true, equivalent to passing  --verbose  on  the
467          command line.
468
469       nativeToolOptions
470          An optional array of strings. Equivalent to passing options after --
471          on the command line. The array values support macro expansion.
472
473   Test Preset
474       Each entry of the testPresets array is a JSON object that  may  contain
475       the following fields:
476
477       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
485       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
492       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
502          This  field  can  also  be a string, which is equivalent to an array
503          containing one string.
504
505       condition
506          An optional Condition object. This is allowed in preset files speci‐
507          fying version 3 or above.
508
509       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
517       displayName
518          An optional string with a human-friendly name of the preset.
519
520       description
521          An optional string with a human-friendly description of the preset.
522
523       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
534          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
541       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
549       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
555       configuration
556          An optional string. Equivalent to passing --build-config on the com‐
557          mand line.
558
559       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
565       output
566          An optional object specifying output options. The object may contain
567          the following fields.
568
569          shortProgress
570              An optional bool. If true, equivalent to passing  --progress  on
571              the command line.
572
573          verbosity
574              An  optional  string  specifying verbosity level. Must be one of
575              the following:
576
577              default
578                 Equivalent to passing no verbosity flags on the command line.
579
580              verbose
581                 Equivalent to passing --verbose on the command line.
582
583              extra
584                 Equivalent to passing --extra-verbose on the command line.
585
586          debug
587              An optional bool. If true, equivalent to passing --debug on  the
588              command line.
589
590          outputOnFailure
591              An   optional  bool.  If  true,  equivalent  to  passing  --out‐
592              put-on-failure on the command line.
593
594          quiet
595              An optional bool. If true, equivalent to passing --quiet on  the
596              command line.
597
598          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
603          labelSummary
604              An  optional  bool.  If  false,  equivalent  to passing --no-la‐
605              bel-summary on the command line.
606
607          subprojectSummary
608              An optional bool. If false, equivalent to  passing  --no-subpro‐
609              ject-summary on the command line.
610
611          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
616          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
621          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
626       filter
627          An  optional  object  specifying how to filter the tests to run. The
628          object may contain the following fields.
629
630          include
631              An optional object specifying which tests to include. The object
632              may contain the following fields.
633
634              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
640              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
645              useUnion
646                 An optional bool. Equivalent to passing --union on  the  com‐
647                 mand line.
648
649              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
656                 start
657                     An  optional  integer  specifying  a  test index to start
658                     testing at.
659
660                 end
661                     An optional integer specifying a test index to stop test‐
662                     ing at.
663
664                 stride
665                     An optional integer specifying the increment.
666
667                 specificTests
668                     An  optional  array  of integers specifying specific test
669                     indices to run.
670
671          exclude
672              An optional object specifying which tests to exclude. The object
673              may contain the following fields.
674
675              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
680              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
685              fixtures
686                 An  optional object specifying which fixtures to exclude from
687                 adding tests. The object may contain the following fields.
688
689                 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
695                 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
701                 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
707       execution
708          An optional object specifying options for test execution. The object
709          may contain the following fields.
710
711          stopOnFailure
712              An optional bool. If true, equivalent to passing --stop-on-fail‐
713              ure on the command line.
714
715          enableFailover
716              An  optional bool. If true, equivalent to passing -F on the com‐
717              mand line.
718
719          jobs
720              An optional integer. Equivalent to  passing  --parallel  on  the
721              command line.
722
723          resourceSpecFile
724              An  optional  string. Equivalent to passing --resource-spec-file
725              on the command line. This field supports macro expansion.
726
727          testLoad
728              An optional integer. Equivalent to passing  --test-load  on  the
729              command line.
730
731          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
735              human
736
737              json-v1
738
739          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
744              mode
745                 A required string. Must be one of the following values:
746
747                 until-fail
748
749                 until-pass
750
751                 after-timeout
752
753              count
754                 A required integer.
755
756          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
761          scheduleRandom
762              An optional bool. If true, equivalent to passing --schedule-ran‐
763              dom on the command line.
764
765          timeout
766              An optional integer. Equivalent to passing --timeout on the com‐
767              mand line.
768
769          noTestsAction
770              An optional string specifying  the  behavior  if  no  tests  are
771              found. Must be one of the following values:
772
773              default
774                 Equivalent to not passing any value on the command line.
775
776              error
777                 Equivalent to passing --no-tests=error on the command line.
778
779              ignore
780                 Equivalent to passing --no-tests=ignore on the command line.
781
782   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
793       type
794          A required string with one of the following values:
795
796          "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
801              value
802                 A  required  boolean  which provides a constant value for the
803                 condition's evaluation.
804
805          "equals"
806
807          "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
812              lhs
813                 First string to compare. This field supports macro expansion.
814
815              rhs
816                 Second string to compare. This field  supports  macro  expan‐
817                 sion.
818
819          "inList"
820
821          "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
826              string
827                 A  required  string  to search for. This field supports macro
828                 expansion.
829
830              list
831                 A required list of strings to  search.  This  field  supports
832                 macro expansion, and uses short-circuit evaluation.
833
834          "matches"
835
836          "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
841              string
842                 A required string to search. This field supports macro expan‐
843                 sion.
844
845              regex
846                 A required regular expression to search for. This field  sup‐
847                 ports macro expansion.
848
849          "anyOf"
850
851          "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
856              conditions
857                 A  required  array of condition objects. These conditions use
858                 short-circuit evaluation.
859
860          "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
865              condition
866                 A required condition object.
867
868   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
876       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
881       Recognized macros include:
882
883       ${sourceDir}
884          Path to the project source directory.
885
886       ${sourceParentDir}
887          Path to the project source directory's parent directory.
888
889       ${sourceDirName}
890          The  last  filename  component  of  ${sourceDir}.  For  example,  if
891          ${sourceDir} is /path/to/source, this would be source.
892
893       ${presetName}
894          Name specified in the preset's name field.
895
896       ${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
901       ${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
906       ${dollar}
907          A literal dollar sign ($).
908
909       $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
916          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
922       $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
931       $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
937          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

SCHEMA

944       This file provides a machine-readable JSON  schema  for  the  CMakePre‐
945       sets.json format.
946
948       2000-2022 Kitware, Inc. and Contributors
949
950
951
952
9533.22.2                           Jan 25, 2022                 CMAKE-PRESETS(7)
Impressum