1.. cmake-manual-description: CMakePresets.json
2
3cmake-presets(7)
4****************
5
6.. only:: html
7
8   .. contents::
9
10Introduction
11============
12
13One problem that CMake users often face is sharing settings with other people
14for common ways to configure a project. This may be done to support CI builds,
15or for users who frequently use the same build. CMake supports two files,
16``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to
17specify common configure options and share them with others.
18
19``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root
20directory. They both have exactly the same format, and both are optional
21(though at least one must be present if ``--preset`` is specified.)
22``CMakePresets.json`` is meant to save project-wide builds, while
23``CMakeUserPresets.json`` is meant for developers to save their own local
24builds. ``CMakePresets.json`` may be checked into a version control system, and
25``CMakeUserPresets.json`` should NOT be checked in. For example, if a project
26is using Git, ``CMakePresets.json`` may be tracked, and
27``CMakeUserPresets.json`` should be added to the ``.gitignore``.
28
29Format
30======
31
32The files are a JSON document with an object as the root:
33
34.. literalinclude:: presets/example.json
35  :language: json
36
37The root object recognizes the following fields:
38
39``version``
40
41  A required integer representing the version of the JSON schema.
42  The supported versions are ``1``, ``2``, and ``3``.
43
44``cmakeMinimumRequired``
45
46  An optional object representing the minimum version of CMake needed to
47  build this project. This object consists of the following fields:
48
49  ``major``
50
51    An optional integer representing the major version.
52
53  ``minor``
54
55    An optional integer representing the minor version.
56
57  ``patch``
58
59    An optional integer representing the patch version.
60
61``vendor``
62
63  An optional map containing vendor-specific information. CMake does not
64  interpret the contents of this field except to verify that it is a map if
65  it does exist. However, the keys should be a vendor-specific domain name
66  followed by a ``/``-separated path. For example, the Example IDE 1.0 could
67  use ``example.com/ExampleIDE/1.0``. The value of each field can be anything
68  desired by the vendor, though will typically be a map.
69
70``configurePresets``
71
72  An optional array of `Configure Preset`_ objects.
73  This is allowed in preset files specifying version ``1`` or above.
74
75``buildPresets``
76
77  An optional array of `Build Preset`_ objects.
78  This is allowed in preset files specifying version ``2`` or above.
79
80``testPresets``
81
82  An optional array of `Test Preset`_ objects.
83  This is allowed in preset files specifying version ``2`` or above.
84
85Configure Preset
86^^^^^^^^^^^^^^^^
87
88Each entry of the ``configurePresets`` array is a JSON object
89that may contain the following fields:
90
91``name``
92
93  A required string representing the machine-friendly name of the preset.
94  This identifier is used in the :ref:`cmake --preset <CMake Options>` option.
95  There must not be two configure presets in the union of ``CMakePresets.json``
96  and ``CMakeUserPresets.json`` in the same directory with the same name.
97  However, a configure preset may have the same name as a build or test preset.
98
99``hidden``
100
101  An optional boolean specifying whether or not a preset should be hidden.
102  If a preset is hidden, it cannot be used in the ``--preset=`` argument,
103  will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not
104  have to have a valid ``generator`` or ``binaryDir``, even from
105  inheritance. ``hidden`` presets are intended to be used as a base for
106  other presets to inherit via the ``inherits`` field.
107
108``inherits``
109
110  An optional array of strings representing the names of presets to inherit
111  from. The preset will inherit all of the fields from the ``inherits``
112  presets by default (except ``name``, ``hidden``, ``inherits``,
113  ``description``, and ``displayName``), but can override them as
114  desired. If multiple ``inherits`` presets provide conflicting values for
115  the same field, the earlier preset in the ``inherits`` list will be
116  preferred. Presets in ``CMakePresets.json`` may not inherit from presets
117  in ``CMakeUserPresets.json``.
118
119  This field can also be a string, which is equivalent to an array
120  containing one string.
121
122``condition``
123
124  An optional `Condition`_ object. This is allowed in preset files specifying
125  version ``3`` or above.
126
127``vendor``
128
129  An optional map containing vendor-specific information. CMake does not
130  interpret the contents of this field except to verify that it is a map
131  if it does exist. However, it should follow the same conventions as the
132  root-level ``vendor`` field. If vendors use their own per-preset
133  ``vendor`` field, they should implement inheritance in a sensible manner
134  when appropriate.
135
136``displayName``
137
138  An optional string with a human-friendly name of the preset.
139
140``description``
141
142  An optional string with a human-friendly description of the preset.
143
144``generator``
145
146  An optional string representing the generator to use for the preset. If
147  ``generator`` is not specified, it must be inherited from the
148  ``inherits`` preset (unless this preset is ``hidden``). In version ``3``
149  or above, this field may be omitted to fall back to regular generator
150  discovery procedure.
151
152  Note that for Visual Studio generators, unlike in the command line ``-G``
153  argument, you cannot include the platform name in the generator name. Use
154  the ``architecture`` field instead.
155
156``architecture``, ``toolset``
157
158  Optional fields representing the platform and toolset, respectively, for
159  generators that support them. Each may be either a string or an object
160  with the following fields:
161
162  ``value``
163
164    An optional string representing the value.
165
166  ``strategy``
167
168    An optional string telling CMake how to handle the ``architecture`` or
169    ``toolset`` field. Valid values are:
170
171    ``"set"``
172
173      Set the respective value. This will result in an error for generators
174      that do not support the respective field.
175
176    ``"external"``
177
178      Do not set the value, even if the generator supports it. This is
179      useful if, for example, a preset uses the Ninja generator, and an IDE
180      knows how to set up the Visual C++ environment from the
181      ``architecture`` and ``toolset`` fields. In that case, CMake will
182      ignore the field, but the IDE can use them to set up the environment
183      before invoking CMake.
184
185``toolchainFile``
186
187  An optional string representing the path to the toolchain file.
188  This field supports `macro expansion`_. If a relative path is specified,
189  it is calculated relative to the build directory, and if not found,
190  relative to the source directory. This field takes precedence over any
191  :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files
192  specifying version ``3`` or above.
193
194``binaryDir``
195
196  An optional string representing the path to the output binary directory.
197  This field supports `macro expansion`_. If a relative path is specified,
198  it is calculated relative to the source directory. If ``binaryDir`` is not
199  specified, it must be inherited from the ``inherits`` preset (unless this
200  preset is ``hidden``). In version ``3`` or above, this field may be
201  omitted.
202
203``installDir``
204
205  An optional string representing the path to the installation directory.
206  This field supports `macro expansion`_. If a relative path is specified,
207  it is calculated relative to the source directory. This is allowed in
208  preset files specifying version ``3`` or above.
209
210``cmakeExecutable``
211
212  An optional string representing the path to the CMake executable to use
213  for this preset. This is reserved for use by IDEs, and is not used by
214  CMake itself. IDEs that use this field should expand any macros in it.
215
216``cacheVariables``
217
218  An optional map of cache variables. The key is the variable name (which
219  may not be an empty string), and the value is either ``null``, a boolean
220  (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type
221  of ``BOOL``), a string representing the value of the variable (which
222  supports `macro expansion`_), or an object with the following fields:
223
224  ``type``
225
226    An optional string representing the type of the variable.
227
228  ``value``
229
230    A required string or boolean representing the value of the variable.
231    A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field
232    supports `macro expansion`_.
233
234  Cache variables are inherited through the ``inherits`` field, and the
235  preset's variables will be the union of its own ``cacheVariables`` and
236  the ``cacheVariables`` from all its parents. If multiple presets in this
237  union define the same variable, the standard rules of ``inherits`` are
238  applied. Setting a variable to ``null`` causes it to not be set, even if
239  a value was inherited from another preset.
240
241``environment``
242
243  An optional map of environment variables. The key is the variable name
244  (which may not be an empty string), and the value is either ``null`` or
245  a string representing the value of the variable. Each variable is set
246  regardless of whether or not a value was given to it by the process's
247  environment. This field supports `macro expansion`_, and environment
248  variables in this map may reference each other, and may be listed in any
249  order, as long as such references do not cause a cycle (for example,
250  if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
251
252  Environment variables are inherited through the ``inherits`` field, and
253  the preset's environment will be the union of its own ``environment`` and
254  the ``environment`` from all its parents. If multiple presets in this
255  union define the same variable, the standard rules of ``inherits`` are
256  applied. Setting a variable to ``null`` causes it to not be set, even if
257  a value was inherited from another preset.
258
259``warnings``
260
261  An optional object specifying the warnings to enable. The object may
262  contain the following fields:
263
264  ``dev``
265
266    An optional boolean. Equivalent to passing ``-Wdev`` or ``-Wno-dev``
267    on the command line. This may not be set to ``false`` if ``errors.dev``
268    is set to ``true``.
269
270  ``deprecated``
271
272    An optional boolean. Equivalent to passing ``-Wdeprecated`` or
273    ``-Wno-deprecated`` on the command line. This may not be set to
274    ``false`` if ``errors.deprecated`` is set to ``true``.
275
276  ``uninitialized``
277
278    An optional boolean. Setting this to ``true`` is equivalent to passing
279    ``--warn-uninitialized`` on the command line.
280
281  ``unusedCli``
282
283    An optional boolean. Setting this to ``false`` is equivalent to passing
284    ``--no-warn-unused-cli`` on the command line.
285
286  ``systemVars``
287
288    An optional boolean. Setting this to ``true`` is equivalent to passing
289    ``--check-system-vars`` on the command line.
290
291``errors``
292
293  An optional object specifying the errors to enable. The object may
294  contain the following fields:
295
296  ``dev``
297
298    An optional boolean. Equivalent to passing ``-Werror=dev`` or
299    ``-Wno-error=dev`` on the command line. This may not be set to ``true``
300    if ``warnings.dev`` is set to ``false``.
301
302  ``deprecated``
303
304    An optional boolean. Equivalent to passing ``-Werror=deprecated`` or
305    ``-Wno-error=deprecated`` on the command line. This may not be set to
306    ``true`` if ``warnings.deprecated`` is set to ``false``.
307
308``debug``
309
310  An optional object specifying debug options. The object may contain the
311  following fields:
312
313  ``output``
314
315    An optional boolean. Setting this to ``true`` is equivalent to passing
316    ``--debug-output`` on the command line.
317
318  ``tryCompile``
319
320    An optional boolean. Setting this to ``true`` is equivalent to passing
321    ``--debug-trycompile`` on the command line.
322
323  ``find``
324
325    An optional boolean. Setting this to ``true`` is equivalent to passing
326    ``--debug-find`` on the command line.
327
328Build Preset
329^^^^^^^^^^^^
330
331Each entry of the ``buildPresets`` array is a JSON object
332that may contain the following fields:
333
334``name``
335
336  A required string representing the machine-friendly name of the preset.
337  This identifier is used in the
338  :ref:`cmake --build --preset <Build Tool Mode>` option.
339  There must not be two build presets in the union of ``CMakePresets.json``
340  and ``CMakeUserPresets.json`` in the same directory with the same name.
341  However, a build preset may have the same name as a configure or test preset.
342
343``hidden``
344
345  An optional boolean specifying whether or not a preset should be hidden.
346  If a preset is hidden, it cannot be used in the ``--preset`` argument
347  and does not have to have a valid ``configurePreset``, even from
348  inheritance. ``hidden`` presets are intended to be used as a base for
349  other presets to inherit via the ``inherits`` field.
350
351``inherits``
352
353  An optional array of strings representing the names of presets to
354  inherit from. The preset will inherit all of the fields from the
355  ``inherits`` presets by default (except ``name``, ``hidden``,
356  ``inherits``, ``description``, and ``displayName``), but can override
357  them as desired. If multiple ``inherits`` presets provide conflicting
358  values for the same field, the earlier preset in the ``inherits`` list
359  will be preferred. Presets in ``CMakePresets.json`` may not inherit from
360  presets in ``CMakeUserPresets.json``.
361
362  This field can also be a string, which is equivalent to an array
363  containing one string.
364
365``condition``
366
367  An optional `Condition`_ object. This is allowed in preset files specifying
368  version ``3`` or above.
369
370``vendor``
371
372  An optional map containing vendor-specific information. CMake does not
373  interpret the contents of this field except to verify that it is a map
374  if it does exist. However, it should follow the same conventions as the
375  root-level ``vendor`` field. If vendors use their own per-preset
376  ``vendor`` field, they should implement inheritance in a sensible manner
377  when appropriate.
378
379``displayName``
380
381  An optional string with a human-friendly name of the preset.
382
383``description``
384
385  An optional string with a human-friendly description of the preset.
386
387``environment``
388
389  An optional map of environment variables. The key is the variable name
390  (which may not be an empty string), and the value is either ``null`` or
391  a string representing the value of the variable. Each variable is set
392  regardless of whether or not a value was given to it by the process's
393  environment. This field supports macro expansion, and environment
394  variables in this map may reference each other, and may be listed in any
395  order, as long as such references do not cause a cycle (for example, if
396  ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
397
398  Environment variables are inherited through the ``inherits`` field, and
399  the preset's environment will be the union of its own ``environment``
400  and the ``environment`` from all its parents. If multiple presets in
401  this union define the same variable, the standard rules of ``inherits``
402  are applied. Setting a variable to ``null`` causes it to not be set,
403  even if a value was inherited from another preset.
404
405  .. note::
406
407    For a CMake project using ExternalProject with a configuration preset
408    having environment variables needed in the ExternalProject, use a build
409    preset that inherits that configuration preset or the ExternalProject
410    will not have the environment variables set in the configuration preset.
411    Example: suppose the host defaults to one compiler (say Clang)
412    and the user wishes to use another compiler (say GCC). Set configuration
413    preset environment variables ``CC`` and ``CXX`` and use a build preset
414    that inherits that configuration preset. Otherwise the ExternalProject
415    may use a different (system default) compiler than the top-level CMake
416    project.
417
418``configurePreset``
419
420  An optional string specifying the name of a configure preset to
421  associate with this build preset. If ``configurePreset`` is not
422  specified, it must be inherited from the inherits preset (unless this
423  preset is hidden). The build directory is inferred from the configure
424  preset, so the build will take place in the same ``binaryDir`` that the
425  configuration did.
426
427``inheritConfigureEnvironment``
428
429  An optional boolean that defaults to true. If true, the environment
430  variables from the associated configure preset are inherited after all
431  inherited build preset environments, but before environment variables
432  explicitly specified in this build preset.
433
434``jobs``
435
436  An optional integer. Equivalent to passing ``--parallel`` or ``-j`` on
437  the command line.
438
439``targets``
440
441  An optional string or array of strings. Equivalent to passing
442  ``--target`` or ``-t`` on the command line. Vendors may ignore the
443  targets property or hide build presets that explicitly specify targets.
444  This field supports macro expansion.
445
446``configuration``
447
448  An optional string. Equivalent to passing ``--config`` on the command
449  line.
450
451``cleanFirst``
452
453  An optional bool. If true, equivalent to passing ``--clean-first`` on
454  the command line.
455
456``verbose``
457
458  An optional bool. If true, equivalent to passing ``--verbose`` on the
459  command line.
460
461``nativeToolOptions``
462
463  An optional array of strings. Equivalent to passing options after ``--``
464  on the command line. The array values support macro expansion.
465
466Test Preset
467^^^^^^^^^^^
468
469Each entry of the ``testPresets`` array is a JSON object
470that may contain the following fields:
471
472``name``
473
474  A required string representing the machine-friendly name of the preset.
475  This identifier is used in the :ref:`ctest --preset <CTest Options>` option.
476  There must not be two test presets in the union of ``CMakePresets.json``
477  and ``CMakeUserPresets.json`` in the same directory with the same name.
478  However, a test preset may have the same name as a configure or build preset.
479
480``hidden``
481
482  An optional boolean specifying whether or not a preset should be hidden.
483  If a preset is hidden, it cannot be used in the ``--preset`` argument
484  and does not have to have a valid ``configurePreset``, even from
485  inheritance. ``hidden`` presets are intended to be used as a base for
486  other presets to inherit via the ``inherits`` field.
487
488``inherits``
489
490  An optional array of strings representing the names of presets to
491  inherit from. The preset will inherit all of the fields from the
492  ``inherits`` presets by default (except ``name``, ``hidden``,
493  ``inherits``, ``description``, and ``displayName``), but can override
494  them as desired. If multiple ``inherits`` presets provide conflicting
495  values for the same field, the earlier preset in the ``inherits`` list
496  will be preferred. Presets in ``CMakePresets.json`` may not inherit from
497  presets in ``CMakeUserPresets.json``.
498
499  This field can also be a string, which is equivalent to an array
500  containing one string.
501
502``condition``
503
504  An optional `Condition`_ object. This is allowed in preset files specifying
505  version ``3`` or above.
506
507``vendor``
508
509  An optional map containing vendor-specific information. CMake does not
510  interpret the contents of this field except to verify that it is a map
511  if it does exist. However, it should follow the same conventions as the
512  root-level ``vendor`` field. If vendors use their own per-preset
513  ``vendor`` field, they should implement inheritance in a sensible manner
514  when appropriate.
515
516``displayName``
517
518  An optional string with a human-friendly name of the preset.
519
520``description``
521
522  An optional string with a human-friendly description of the preset.
523
524``environment``
525
526  An optional map of environment variables. The key is the variable name
527  (which may not be an empty string), and the value is either ``null`` or
528  a string representing the value of the variable. Each variable is set
529  regardless of whether or not a value was given to it by the process's
530  environment. This field supports macro expansion, and environment
531  variables in this map may reference each other, and may be listed in any
532  order, as long as such references do not cause a cycle (for example, if
533  ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
534
535  Environment variables are inherited through the ``inherits`` field, and
536  the preset's environment will be the union of its own ``environment``
537  and the ``environment`` from all its parents. If multiple presets in
538  this union define the same variable, the standard rules of ``inherits``
539  are applied. Setting a variable to ``null`` causes it to not be set,
540  even if a value was inherited from another preset.
541
542``configurePreset``
543
544  An optional string specifying the name of a configure preset to
545  associate with this test preset. If ``configurePreset`` is not
546  specified, it must be inherited from the inherits preset (unless this
547  preset is hidden). The build directory is inferred from the configure
548  preset, so tests will run in the same ``binaryDir`` that the
549  configuration did and build did.
550
551``inheritConfigureEnvironment``
552
553  An optional boolean that defaults to true. If true, the environment
554  variables from the associated configure preset are inherited after all
555  inherited test preset environments, but before environment variables
556  explicitly specified in this test preset.
557
558``configuration``
559
560  An optional string. Equivalent to passing ``--build-config`` on the
561  command line.
562
563``overwriteConfigurationFile``
564
565  An optional array of configuration options to overwrite options
566  specified in the CTest configuration file. Equivalent to passing
567  ``--overwrite`` for each value in the array. The array values
568  support macro expansion.
569
570``output``
571
572  An optional object specifying output options. The object may contain the
573  following fields.
574
575  ``shortProgress``
576
577    An optional bool. If true, equivalent to passing ``--progress`` on the
578    command line.
579
580  ``verbosity``
581
582    An optional string specifying verbosity level. Must be one of the
583    following:
584
585    ``default``
586
587      Equivalent to passing no verbosity flags on the command line.
588
589    ``verbose``
590
591      Equivalent to passing ``--verbose`` on the command line.
592
593    ``extra``
594
595      Equivalent to passing ``--extra-verbose`` on the command line.
596
597  ``debug``
598
599    An optional bool. If true, equivalent to passing ``--debug`` on the
600    command line.
601
602  ``outputOnFailure``
603
604    An optional bool. If true, equivalent to passing
605    ``--output-on-failure`` on the command line.
606
607  ``quiet``
608
609    An optional bool. If true, equivalent to passing ``--quiet`` on the
610    command line.
611
612  ``outputLogFile``
613
614    An optional string specifying a path to a log file. Equivalent to
615    passing ``--output-log`` on the command line. This field supports
616    macro expansion.
617
618  ``labelSummary``
619
620    An optional bool. If false, equivalent to passing
621    ``--no-label-summary`` on the command line.
622
623  ``subprojectSummary``
624
625    An optional bool. If false, equivalent to passing
626    ``--no-subproject-summary`` on the command line.
627
628  ``maxPassedTestOutputSize``
629
630    An optional integer specifying the maximum output for passed tests in
631    bytes. Equivalent to passing ``--test-output-size-passed`` on the
632    command line.
633
634  ``maxFailedTestOutputSize``
635
636    An optional integer specifying the maximum output for failed tests in
637    bytes. Equivalent to passing ``--test-output-size-failed`` on the
638    command line.
639
640  ``maxTestNameWidth``
641
642    An optional integer specifying the maximum width of a test name to
643    output. Equivalent to passing ``--max-width`` on the command line.
644
645``filter``
646
647  An optional object specifying how to filter the tests to run. The object
648  may contain the following fields.
649
650  ``include``
651
652    An optional object specifying which tests to include. The object may
653    contain the following fields.
654
655    ``name``
656
657      An optional string specifying a regex for test names. Equivalent to
658      passing ``--tests-regex`` on the command line. This field supports
659      macro expansion. CMake regex syntax is described under
660      :ref:`string(REGEX) <Regex Specification>`.
661
662
663    ``label``
664
665      An optional string specifying a regex for test labels. Equivalent to
666      passing ``--label-regex`` on the command line. This field supports
667      macro expansion.
668
669    ``useUnion``
670
671      An optional bool. Equivalent to passing ``--union`` on the command
672      line.
673
674    ``index``
675
676      An optional object specifying tests to include by test index. The
677      object may contain the following fields. Can also be an optional
678      string specifying a file with the command line syntax for
679      ``--tests-information``. If specified as a string, this field
680      supports macro expansion.
681
682      ``start``
683
684        An optional integer specifying a test index to start testing at.
685
686      ``end``
687
688        An optional integer specifying a test index to stop testing at.
689
690      ``stride``
691
692        An optional integer specifying the increment.
693
694      ``specificTests``
695
696        An optional array of integers specifying specific test indices to
697        run.
698
699  ``exclude``
700
701    An optional object specifying which tests to exclude. The object may
702    contain the following fields.
703
704    ``name``
705
706      An optional string specifying a regex for test names. Equivalent to
707      passing ``--exclude-regex`` on the command line. This field supports
708      macro expansion.
709
710    ``label``
711
712      An optional string specifying a regex for test labels. Equivalent to
713      passing ``--label-exclude`` on the command line. This field supports
714      macro expansion.
715
716    ``fixtures``
717
718      An optional object specifying which fixtures to exclude from adding
719      tests. The object may contain the following fields.
720
721      ``any``
722
723        An optional string specifying a regex for text fixtures to exclude
724        from adding any tests. Equivalent to ``--fixture-exclude-any`` on
725        the command line. This field supports macro expansion.
726
727      ``setup``
728
729        An optional string specifying a regex for text fixtures to exclude
730        from adding setup tests. Equivalent to ``--fixture-exclude-setup``
731        on the command line. This field supports macro expansion.
732
733      ``cleanup``
734
735        An optional string specifying a regex for text fixtures to exclude
736        from adding cleanup tests. Equivalent to
737        ``--fixture-exclude-cleanup`` on the command line. This field
738        supports macro expansion.
739
740``execution``
741
742  An optional object specifying options for test execution. The object may
743  contain the following fields.
744
745  ``stopOnFailure``
746
747    An optional bool. If true, equivalent to passing ``--stop-on-failure``
748    on the command line.
749
750  ``enableFailover``
751
752    An optional bool. If true, equivalent to passing ``-F`` on the command
753    line.
754
755  ``jobs``
756
757    An optional integer. Equivalent to passing ``--parallel`` on the
758    command line.
759
760  ``resourceSpecFile``
761
762    An optional string. Equivalent to passing ``--resource-spec-file`` on
763    the command line. This field supports macro expansion.
764
765  ``testLoad``
766
767    An optional integer. Equivalent to passing ``--test-load`` on the
768    command line.
769
770  ``showOnly``
771
772    An optional string. Equivalent to passing ``--show-only`` on the
773    command line. The string must be one of the following values:
774
775    ``human``
776
777    ``json-v1``
778
779  ``repeat``
780
781    An optional object specifying how to repeat tests. Equivalent to
782    passing ``--repeat`` on the command line. The object must have the
783    following fields.
784
785    ``mode``
786
787      A required string. Must be one of the following values:
788
789      ``until-fail``
790
791      ``until-pass``
792
793      ``after-timeout``
794
795    ``count``
796
797      A required integer.
798
799  ``interactiveDebugging``
800
801    An optional bool. If true, equivalent to passing
802    ``--interactive-debug-mode 1`` on the command line. If false,
803    equivalent to passing ``--interactive-debug-mode 0`` on the command
804    line.
805
806  ``scheduleRandom``
807
808    An optional bool. If true, equivalent to passing ``--schedule-random``
809    on the command line.
810
811  ``timeout``
812
813    An optional integer. Equivalent to passing ``--timeout`` on the
814    command line.
815
816  ``noTestsAction``
817
818    An optional string specifying the behavior if no tests are found. Must
819    be one of the following values:
820
821    ``default``
822
823      Equivalent to not passing any value on the command line.
824
825    ``error``
826
827      Equivalent to passing ``--no-tests=error`` on the command line.
828
829    ``ignore``
830
831      Equivalent to passing ``--no-tests=ignore`` on the command line.
832
833Condition
834^^^^^^^^^
835
836The ``condition`` field of a preset, allowed in preset files specifying version
837``3`` or above, is used to determine whether or not the preset is enabled. For
838example, this can be used to disable a preset on platforms other than Windows.
839``condition`` may be either a boolean, ``null``, or an object. If it is a
840boolean, the boolean indicates whether the preset is enabled or disabled. If it
841is ``null``, the preset is enabled, but the ``null`` condition is not inherited
842by any presets that may inherit from the preset. Sub-conditions (for example in
843a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an
844object, it has the following fields:
845
846``type``
847
848  A required string with one of the following values:
849
850  ``"const"``
851
852    Indicates that the condition is constant. This is equivalent to using a
853    boolean in place of the object. The condition object will have the
854    following additional fields:
855
856    ``value``
857
858      A required boolean which provides a constant value for the condition's
859      evaluation.
860
861  ``"equals"``
862
863  ``"notEquals"``
864
865    Indicates that the condition compares two strings to see if they are equal
866    (or not equal). The condition object will have the following additional
867    fields:
868
869    ``lhs``
870
871      First string to compare. This field supports macro expansion.
872
873    ``rhs``
874
875      Second string to compare. This field supports macro expansion.
876
877  ``"inList"``
878
879  ``"notInList"``
880
881    Indicates that the condition searches for a string in a list of strings.
882    The condition object will have the following additional fields:
883
884    ``string``
885
886      A required string to search for. This field supports macro expansion.
887
888    ``list``
889
890      A required list of strings to search. This field supports macro
891      expansion, and uses short-circuit evaluation.
892
893  ``"matches"``
894
895  ``"notMatches"``
896
897    Indicates that the condition searches for a regular expression in a string.
898    The condition object will have the following additional fields:
899
900    ``string``
901
902      A required string to search. This field supports macro expansion.
903
904    ``regex``
905
906      A required regular expression to search for. This field supports macro
907      expansion.
908
909  ``"anyOf"``
910
911  ``"allOf"``
912
913    Indicates that the condition is an aggregation of zero or more nested
914    conditions. The condition object will have the following additional fields:
915
916    ``conditions``
917
918      A required array of condition objects. These conditions use short-circuit
919      evaluation.
920
921  ``"not"``
922
923    Indicates that the condition is an inversion of another condition. The
924    condition object will have the following additional fields:
925
926    ``condition``
927
928      A required condition object.
929
930Macro Expansion
931^^^^^^^^^^^^^^^
932
933As mentioned above, some fields support macro expansion. Macros are
934recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are
935evaluated in the context of the preset being used, even if the macro is in a
936field that was inherited from another preset. For example, if the ``Base``
937preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the
938``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to
939``Derived``.
940
941It is an error to not put a closing brace at the end of a macro name. For
942example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by
943anything other than a left curly brace (``{``) with a possible namespace is
944interpreted as a literal dollar sign.
945
946Recognized macros include:
947
948``${sourceDir}``
949
950  Path to the project source directory.
951
952``${sourceParentDir}``
953
954  Path to the project source directory's parent directory.
955
956``${sourceDirName}``
957
958  The last filename component of ``${sourceDir}``. For example, if
959  ``${sourceDir}`` is ``/path/to/source``, this would be ``source``.
960
961``${presetName}``
962
963  Name specified in the preset's ``name`` field.
964
965``${generator}``
966
967  Generator specified in the preset's ``generator`` field. For build and
968  test presets, this will evaluate to the generator specified by
969  ``configurePreset``.
970
971``${hostSystemName}``
972
973  The name of the host operating system. Contains the same value as
974  :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files
975  specifying version ``3`` or above.
976
977``${dollar}``
978
979  A literal dollar sign (``$``).
980
981``$env{<variable-name>}``
982
983  Environment variable with name ``<variable-name>``. The variable name may
984  not be an empty string. If the variable is defined in the ``environment``
985  field, that value is used instead of the value from the parent environment.
986  If the environment variable is not defined, this evaluates as an empty
987  string.
988
989  Note that while Windows environment variable names are case-insensitive,
990  variable names within a preset are still case-sensitive. This may lead to
991  unexpected results when using inconsistent casing. For best results, keep
992  the casing of environment variable names consistent.
993
994``$penv{<variable-name>}``
995
996  Similar to ``$env{<variable-name>}``, except that the value only comes from
997  the parent environment, and never from the ``environment`` field. This
998  allows you to prepend or append values to existing environment variables.
999  For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will
1000  prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
1001  is needed because ``$env{<variable-name>}`` does not allow circular
1002  references.
1003
1004``$vendor{<macro-name>}``
1005
1006  An extension point for vendors to insert their own macros. CMake will not
1007  be able to use presets which have a ``$vendor{<macro-name>}`` macro, and
1008  effectively ignores such presets. However, it will still be able to use
1009  other presets from the same file.
1010
1011  CMake does not make any attempt to interpret ``$vendor{<macro-name>}``
1012  macros. However, to avoid name collisions, IDE vendors should prefix
1013  ``<macro-name>`` with a very short (preferably <= 4 characters) vendor
1014  identifier prefix, followed by a ``.``, followed by the macro name. For
1015  example, the Example IDE could have ``$vendor{xide.ideInstallDir}``.
1016
1017Schema
1018======
1019
1020:download:`This file </manual/presets/schema.json>` provides a machine-readable
1021JSON schema for the ``CMakePresets.json`` format.
1022