1 .. cmake-manual-description: CMakePresets.json
13 One problem that CMake users often face is sharing settings with other people
14 for common ways to configure a project. This may be done to support CI builds,
15 or for users who frequently use the same build. CMake supports two main files,
16 ``CMakePresets.json`` and ``CMakeUserPresets.json``, that allow users to
17 specify common configure options and share them with others. CMake also
18 supports files included with the ``include`` field.
20 ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root
21 directory. They both have exactly the same format, and both are optional
22 (though at least one must be present if ``--preset`` is specified).
23 ``CMakePresets.json`` is meant to specify project-wide build details, while
24 ``CMakeUserPresets.json`` is meant for developers to specify their own local
27 ``CMakePresets.json`` may be checked into a version control system, and
28 ``CMakeUserPresets.json`` should NOT be checked in. For example, if a
29 project is using Git, ``CMakePresets.json`` may be tracked, and
30 ``CMakeUserPresets.json`` should be added to the ``.gitignore``.
35 The files are a JSON document with an object as the root:
37 .. literalinclude:: presets/example.json
40 The root object recognizes the following fields:
44 A required integer representing the version of the JSON schema.
45 The supported versions are:
48 .. versionadded:: 3.19
51 .. versionadded:: 3.20
54 .. versionadded:: 3.21
57 .. versionadded:: 3.23
60 .. versionadded:: 3.24
62 ``cmakeMinimumRequired``
64 An optional object representing the minimum version of CMake needed to
65 build this project. This object consists of the following fields:
69 An optional integer representing the major version.
73 An optional integer representing the minor version.
77 An optional integer representing the patch version.
81 An optional array of strings representing files to include. If the filenames
82 are not absolute, they are considered relative to the current file.
83 This is allowed in preset files specifying version ``4`` or above.
84 See `Includes`_ for discussion of the constraints on included files.
88 An optional map containing vendor-specific information. CMake does not
89 interpret the contents of this field except to verify that it is a map if
90 it does exist. However, the keys should be a vendor-specific domain name
91 followed by a ``/``-separated path. For example, the Example IDE 1.0 could
92 use ``example.com/ExampleIDE/1.0``. The value of each field can be anything
93 desired by the vendor, though will typically be a map.
97 An optional array of `Configure Preset`_ objects.
98 This is allowed in preset files specifying version ``1`` or above.
102 An optional array of `Build Preset`_ objects.
103 This is allowed in preset files specifying version ``2`` or above.
107 An optional array of `Test Preset`_ objects.
108 This is allowed in preset files specifying version ``2`` or above.
113 ``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files
114 with the ``include`` field in file version ``4`` and later. Files included
115 by these files can also include other files. If ``CMakePresets.json`` and
116 ``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json``
117 implicitly includes ``CMakePresets.json``, even with no ``include`` field,
118 in all versions of the format.
120 If a preset file contains presets that inherit from presets in another file,
121 the file must include the other file either directly or indirectly.
122 Include cycles are not allowed among files. If ``a.json`` includes
123 ``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be
124 included multiple times from the same file or from different files.
126 Files directly or indirectly included from ``CMakePresets.json`` should be
127 guaranteed to be provided by the project. ``CMakeUserPresets.json`` may
128 include files from anywhere.
133 Each entry of the ``configurePresets`` array is a JSON object
134 that may contain the following fields:
138 A required string representing the machine-friendly name of the preset.
139 This identifier is used in the :ref:`cmake --preset <CMake Options>` option.
140 There must not be two configure presets in the union of ``CMakePresets.json``
141 and ``CMakeUserPresets.json`` in the same directory with the same name.
142 However, a configure preset may have the same name as a build or test preset.
146 An optional boolean specifying whether or not a preset should be hidden.
147 If a preset is hidden, it cannot be used in the ``--preset=`` argument,
148 will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not
149 have to have a valid ``generator`` or ``binaryDir``, even from
150 inheritance. ``hidden`` presets are intended to be used as a base for
151 other presets to inherit via the ``inherits`` field.
155 An optional array of strings representing the names of presets to inherit
156 from. This field can also be a string, which is equivalent to an array
157 containing one string.
159 The preset will inherit all of the fields from the ``inherits``
160 presets by default (except ``name``, ``hidden``, ``inherits``,
161 ``description``, and ``displayName``), but can override them as
162 desired. If multiple ``inherits`` presets provide conflicting values for
163 the same field, the earlier preset in the ``inherits`` list will be
166 A preset can only inherit from another preset that is defined in the
167 same file or in one of the files it includes (directly or indirectly).
168 Presets in ``CMakePresets.json`` may not inherit from presets in
169 ``CMakeUserPresets.json``.
173 An optional `Condition`_ object. This is allowed in preset files specifying
174 version ``3`` or above.
178 An optional map containing vendor-specific information. CMake does not
179 interpret the contents of this field except to verify that it is a map
180 if it does exist. However, it should follow the same conventions as the
181 root-level ``vendor`` field. If vendors use their own per-preset
182 ``vendor`` field, they should implement inheritance in a sensible manner
187 An optional string with a human-friendly name of the preset.
191 An optional string with a human-friendly description of the preset.
195 An optional string representing the generator to use for the preset. If
196 ``generator`` is not specified, it must be inherited from the
197 ``inherits`` preset (unless this preset is ``hidden``). In version ``3``
198 or above, this field may be omitted to fall back to regular generator
201 Note that for Visual Studio generators, unlike in the command line ``-G``
202 argument, you cannot include the platform name in the generator name. Use
203 the ``architecture`` field instead.
205 ``architecture``, ``toolset``
207 Optional fields representing the platform and toolset, respectively, for
208 generators that support them. Each may be either a string or an object
209 with the following fields:
213 An optional string representing the value.
217 An optional string telling CMake how to handle the ``architecture`` or
218 ``toolset`` field. Valid values are:
222 Set the respective value. This will result in an error for generators
223 that do not support the respective field.
227 Do not set the value, even if the generator supports it. This is
228 useful if, for example, a preset uses the Ninja generator, and an IDE
229 knows how to set up the Visual C++ environment from the
230 ``architecture`` and ``toolset`` fields. In that case, CMake will
231 ignore the field, but the IDE can use them to set up the environment
232 before invoking CMake.
236 An optional string representing the path to the toolchain file.
237 This field supports `macro expansion`_. If a relative path is specified,
238 it is calculated relative to the build directory, and if not found,
239 relative to the source directory. This field takes precedence over any
240 :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files
241 specifying version ``3`` or above.
245 An optional string representing the path to the output binary directory.
246 This field supports `macro expansion`_. If a relative path is specified,
247 it is calculated relative to the source directory. If ``binaryDir`` is not
248 specified, it must be inherited from the ``inherits`` preset (unless this
249 preset is ``hidden``). In version ``3`` or above, this field may be
254 An optional string representing the path to the installation directory.
255 This field supports `macro expansion`_. If a relative path is specified,
256 it is calculated relative to the source directory. This is allowed in
257 preset files specifying version ``3`` or above.
261 An optional string representing the path to the CMake executable to use
262 for this preset. This is reserved for use by IDEs, and is not used by
263 CMake itself. IDEs that use this field should expand any macros in it.
267 An optional map of cache variables. The key is the variable name (which
268 may not be an empty string), and the value is either ``null``, a boolean
269 (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type
270 of ``BOOL``), a string representing the value of the variable (which
271 supports `macro expansion`_), or an object with the following fields:
275 An optional string representing the type of the variable.
279 A required string or boolean representing the value of the variable.
280 A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field
281 supports `macro expansion`_.
283 Cache variables are inherited through the ``inherits`` field, and the
284 preset's variables will be the union of its own ``cacheVariables`` and
285 the ``cacheVariables`` from all its parents. If multiple presets in this
286 union define the same variable, the standard rules of ``inherits`` are
287 applied. Setting a variable to ``null`` causes it to not be set, even if
288 a value was inherited from another preset.
292 An optional map of environment variables. The key is the variable name
293 (which may not be an empty string), and the value is either ``null`` or
294 a string representing the value of the variable. Each variable is set
295 regardless of whether or not a value was given to it by the process's
296 environment. This field supports `macro expansion`_, and environment
297 variables in this map may reference each other, and may be listed in any
298 order, as long as such references do not cause a cycle (for example,
299 if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
301 Environment variables are inherited through the ``inherits`` field, and
302 the preset's environment will be the union of its own ``environment`` and
303 the ``environment`` from all its parents. If multiple presets in this
304 union define the same variable, the standard rules of ``inherits`` are
305 applied. Setting a variable to ``null`` causes it to not be set, even if
306 a value was inherited from another preset.
310 An optional object specifying the warnings to enable. The object may
311 contain the following fields:
315 An optional boolean. Equivalent to passing ``-Wdev`` or ``-Wno-dev``
316 on the command line. This may not be set to ``false`` if ``errors.dev``
321 An optional boolean. Equivalent to passing ``-Wdeprecated`` or
322 ``-Wno-deprecated`` on the command line. This may not be set to
323 ``false`` if ``errors.deprecated`` is set to ``true``.
327 An optional boolean. Setting this to ``true`` is equivalent to passing
328 ``--warn-uninitialized`` on the command line.
332 An optional boolean. Setting this to ``false`` is equivalent to passing
333 ``--no-warn-unused-cli`` on the command line.
337 An optional boolean. Setting this to ``true`` is equivalent to passing
338 ``--check-system-vars`` on the command line.
342 An optional object specifying the errors to enable. The object may
343 contain the following fields:
347 An optional boolean. Equivalent to passing ``-Werror=dev`` or
348 ``-Wno-error=dev`` on the command line. This may not be set to ``true``
349 if ``warnings.dev`` is set to ``false``.
353 An optional boolean. Equivalent to passing ``-Werror=deprecated`` or
354 ``-Wno-error=deprecated`` on the command line. This may not be set to
355 ``true`` if ``warnings.deprecated`` is set to ``false``.
359 An optional object specifying debug options. The object may contain the
364 An optional boolean. Setting this to ``true`` is equivalent to passing
365 ``--debug-output`` on the command line.
369 An optional boolean. Setting this to ``true`` is equivalent to passing
370 ``--debug-trycompile`` on the command line.
374 An optional boolean. Setting this to ``true`` is equivalent to passing
375 ``--debug-find`` on the command line.
380 Each entry of the ``buildPresets`` array is a JSON object
381 that may contain the following fields:
385 A required string representing the machine-friendly name of the preset.
386 This identifier is used in the
387 :ref:`cmake --build --preset <Build Tool Mode>` option.
388 There must not be two build presets in the union of ``CMakePresets.json``
389 and ``CMakeUserPresets.json`` in the same directory with the same name.
390 However, a build preset may have the same name as a configure or test preset.
394 An optional boolean specifying whether or not a preset should be hidden.
395 If a preset is hidden, it cannot be used in the ``--preset`` argument
396 and does not have to have a valid ``configurePreset``, even from
397 inheritance. ``hidden`` presets are intended to be used as a base for
398 other presets to inherit via the ``inherits`` field.
402 An optional array of strings representing the names of presets to inherit
403 from. This field can also be a string, which is equivalent to an array
404 containing one string.
406 The preset will inherit all of the fields from the
407 ``inherits`` presets by default (except ``name``, ``hidden``,
408 ``inherits``, ``description``, and ``displayName``), but can override
409 them as desired. If multiple ``inherits`` presets provide conflicting
410 values for the same field, the earlier preset in the ``inherits`` list
413 A preset can only inherit from another preset that is defined in the
414 same file or in one of the files it includes (directly or indirectly).
415 Presets in ``CMakePresets.json`` may not inherit from presets in
416 ``CMakeUserPresets.json``.
420 An optional `Condition`_ object. This is allowed in preset files specifying
421 version ``3`` or above.
425 An optional map containing vendor-specific information. CMake does not
426 interpret the contents of this field except to verify that it is a map
427 if it does exist. However, it should follow the same conventions as the
428 root-level ``vendor`` field. If vendors use their own per-preset
429 ``vendor`` field, they should implement inheritance in a sensible manner
434 An optional string with a human-friendly name of the preset.
438 An optional string with a human-friendly description of the preset.
442 An optional map of environment variables. The key is the variable name
443 (which may not be an empty string), and the value is either ``null`` or
444 a string representing the value of the variable. Each variable is set
445 regardless of whether or not a value was given to it by the process's
446 environment. This field supports macro expansion, and environment
447 variables in this map may reference each other, and may be listed in any
448 order, as long as such references do not cause a cycle (for example, if
449 ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
451 Environment variables are inherited through the ``inherits`` field, and
452 the preset's environment will be the union of its own ``environment``
453 and the ``environment`` from all its parents. If multiple presets in
454 this union define the same variable, the standard rules of ``inherits``
455 are applied. Setting a variable to ``null`` causes it to not be set,
456 even if a value was inherited from another preset.
460 For a CMake project using ExternalProject with a configuration preset
461 having environment variables needed in the ExternalProject, use a build
462 preset that inherits that configuration preset or the ExternalProject
463 will not have the environment variables set in the configuration preset.
464 Example: suppose the host defaults to one compiler (say Clang)
465 and the user wishes to use another compiler (say GCC). Set configuration
466 preset environment variables ``CC`` and ``CXX`` and use a build preset
467 that inherits that configuration preset. Otherwise the ExternalProject
468 may use a different (system default) compiler than the top-level CMake
473 An optional string specifying the name of a configure preset to
474 associate with this build preset. If ``configurePreset`` is not
475 specified, it must be inherited from the inherits preset (unless this
476 preset is hidden). The build directory is inferred from the configure
477 preset, so the build will take place in the same ``binaryDir`` that the
480 ``inheritConfigureEnvironment``
482 An optional boolean that defaults to true. If true, the environment
483 variables from the associated configure preset are inherited after all
484 inherited build preset environments, but before environment variables
485 explicitly specified in this build preset.
489 An optional integer. Equivalent to passing ``--parallel`` or ``-j`` on
494 An optional string or array of strings. Equivalent to passing
495 ``--target`` or ``-t`` on the command line. Vendors may ignore the
496 targets property or hide build presets that explicitly specify targets.
497 This field supports macro expansion.
501 An optional string. Equivalent to passing ``--config`` on the command
506 An optional bool. If true, equivalent to passing ``--clean-first`` on
509 ``resolvePackageReferences``
511 An optional string that specifies the package resolve mode. This is
512 allowed in preset files specifying version ``4`` or above.
514 Package references are used to define dependencies to packages from
515 external package managers. Currently only NuGet in combination with the
516 Visual Studio generator is supported. If there are no targets that define
517 package references, this option does nothing. Valid values are:
521 Causes package references to be resolved before attempting a build.
525 Package references will not be resolved. Note that this may cause
526 errors in some build environments, such as .NET SDK style projects.
530 Only resolve package references, but do not perform a build.
534 The command line parameter ``--resolve-package-references`` will take
535 priority over this setting. If the command line parameter is not provided
536 and this setting is not specified, an environment-specific cache variable
537 will be evaluated to decide, if package restoration should be performed.
539 When using the Visual Studio generator, package references are defined
540 using the :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references
541 are restored using NuGet. It can be disabled by setting the
542 ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. This can also be
543 done from within a configure preset.
547 An optional bool. If true, equivalent to passing ``--verbose`` on the
550 ``nativeToolOptions``
552 An optional array of strings. Equivalent to passing options after ``--``
553 on the command line. The array values support macro expansion.
558 Each entry of the ``testPresets`` array is a JSON object
559 that may contain the following fields:
563 A required string representing the machine-friendly name of the preset.
564 This identifier is used in the :ref:`ctest --preset <CTest Options>` option.
565 There must not be two test presets in the union of ``CMakePresets.json``
566 and ``CMakeUserPresets.json`` in the same directory with the same name.
567 However, a test preset may have the same name as a configure or build preset.
571 An optional boolean specifying whether or not a preset should be hidden.
572 If a preset is hidden, it cannot be used in the ``--preset`` argument
573 and does not have to have a valid ``configurePreset``, even from
574 inheritance. ``hidden`` presets are intended to be used as a base for
575 other presets to inherit via the ``inherits`` field.
579 An optional array of strings representing the names of presets to inherit
580 from. This field can also be a string, which is equivalent to an array
581 containing one string.
583 The preset will inherit all of the fields from the
584 ``inherits`` presets by default (except ``name``, ``hidden``,
585 ``inherits``, ``description``, and ``displayName``), but can override
586 them as desired. If multiple ``inherits`` presets provide conflicting
587 values for the same field, the earlier preset in the ``inherits`` list
590 A preset can only inherit from another preset that is defined in the
591 same file or in one of the files it includes (directly or indirectly).
592 Presets in ``CMakePresets.json`` may not inherit from presets in
593 ``CMakeUserPresets.json``.
597 An optional `Condition`_ object. This is allowed in preset files specifying
598 version ``3`` or above.
602 An optional map containing vendor-specific information. CMake does not
603 interpret the contents of this field except to verify that it is a map
604 if it does exist. However, it should follow the same conventions as the
605 root-level ``vendor`` field. If vendors use their own per-preset
606 ``vendor`` field, they should implement inheritance in a sensible manner
611 An optional string with a human-friendly name of the preset.
615 An optional string with a human-friendly description of the preset.
619 An optional map of environment variables. The key is the variable name
620 (which may not be an empty string), and the value is either ``null`` or
621 a string representing the value of the variable. Each variable is set
622 regardless of whether or not a value was given to it by the process's
623 environment. This field supports macro expansion, and environment
624 variables in this map may reference each other, and may be listed in any
625 order, as long as such references do not cause a cycle (for example, if
626 ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.)
628 Environment variables are inherited through the ``inherits`` field, and
629 the preset's environment will be the union of its own ``environment``
630 and the ``environment`` from all its parents. If multiple presets in
631 this union define the same variable, the standard rules of ``inherits``
632 are applied. Setting a variable to ``null`` causes it to not be set,
633 even if a value was inherited from another preset.
637 An optional string specifying the name of a configure preset to
638 associate with this test preset. If ``configurePreset`` is not
639 specified, it must be inherited from the inherits preset (unless this
640 preset is hidden). The build directory is inferred from the configure
641 preset, so tests will run in the same ``binaryDir`` that the
642 configuration did and build did.
644 ``inheritConfigureEnvironment``
646 An optional boolean that defaults to true. If true, the environment
647 variables from the associated configure preset are inherited after all
648 inherited test preset environments, but before environment variables
649 explicitly specified in this test preset.
653 An optional string. Equivalent to passing ``--build-config`` on the
656 ``overwriteConfigurationFile``
658 An optional array of configuration options to overwrite options
659 specified in the CTest configuration file. Equivalent to passing
660 ``--overwrite`` for each value in the array. The array values
661 support macro expansion.
665 An optional object specifying output options. The object may contain the
670 An optional bool. If true, equivalent to passing ``--progress`` on the
675 An optional string specifying verbosity level. Must be one of the
680 Equivalent to passing no verbosity flags on the command line.
684 Equivalent to passing ``--verbose`` on the command line.
688 Equivalent to passing ``--extra-verbose`` on the command line.
692 An optional bool. If true, equivalent to passing ``--debug`` on the
697 An optional bool. If true, equivalent to passing
698 ``--output-on-failure`` on the command line.
702 An optional bool. If true, equivalent to passing ``--quiet`` on the
707 An optional string specifying a path to a log file. Equivalent to
708 passing ``--output-log`` on the command line. This field supports
713 An optional bool. If false, equivalent to passing
714 ``--no-label-summary`` on the command line.
716 ``subprojectSummary``
718 An optional bool. If false, equivalent to passing
719 ``--no-subproject-summary`` on the command line.
721 ``maxPassedTestOutputSize``
723 An optional integer specifying the maximum output for passed tests in
724 bytes. Equivalent to passing ``--test-output-size-passed`` on the
727 ``maxFailedTestOutputSize``
729 An optional integer specifying the maximum output for failed tests in
730 bytes. Equivalent to passing ``--test-output-size-failed`` on the
733 ``testOutputTruncation``
735 An optional string specifying the test output truncation mode. Equivalent
736 to passing ``--test-output-truncation`` on the command line."
737 This is allowed in preset files specifying version ``5`` or above.
741 An optional integer specifying the maximum width of a test name to
742 output. Equivalent to passing ``--max-width`` on the command line.
746 An optional object specifying how to filter the tests to run. The object
747 may contain the following fields.
751 An optional object specifying which tests to include. The object may
752 contain the following fields.
756 An optional string specifying a regex for test names. Equivalent to
757 passing ``--tests-regex`` on the command line. This field supports
758 macro expansion. CMake regex syntax is described under
759 :ref:`string(REGEX) <Regex Specification>`.
764 An optional string specifying a regex for test labels. Equivalent to
765 passing ``--label-regex`` on the command line. This field supports
770 An optional bool. Equivalent to passing ``--union`` on the command
775 An optional object specifying tests to include by test index. The
776 object may contain the following fields. Can also be an optional
777 string specifying a file with the command line syntax for
778 ``--tests-information``. If specified as a string, this field
779 supports macro expansion.
783 An optional integer specifying a test index to start testing at.
787 An optional integer specifying a test index to stop testing at.
791 An optional integer specifying the increment.
795 An optional array of integers specifying specific test indices to
800 An optional object specifying which tests to exclude. The object may
801 contain the following fields.
805 An optional string specifying a regex for test names. Equivalent to
806 passing ``--exclude-regex`` on the command line. This field supports
811 An optional string specifying a regex for test labels. Equivalent to
812 passing ``--label-exclude`` on the command line. This field supports
817 An optional object specifying which fixtures to exclude from adding
818 tests. The object may contain the following fields.
822 An optional string specifying a regex for text fixtures to exclude
823 from adding any tests. Equivalent to ``--fixture-exclude-any`` on
824 the command line. This field supports macro expansion.
828 An optional string specifying a regex for text fixtures to exclude
829 from adding setup tests. Equivalent to ``--fixture-exclude-setup``
830 on the command line. This field supports macro expansion.
834 An optional string specifying a regex for text fixtures to exclude
835 from adding cleanup tests. Equivalent to
836 ``--fixture-exclude-cleanup`` on the command line. This field
837 supports macro expansion.
841 An optional object specifying options for test execution. The object may
842 contain the following fields.
846 An optional bool. If true, equivalent to passing ``--stop-on-failure``
851 An optional bool. If true, equivalent to passing ``-F`` on the command
856 An optional integer. Equivalent to passing ``--parallel`` on the
861 An optional string. Equivalent to passing ``--resource-spec-file`` on
862 the command line. This field supports macro expansion.
866 An optional integer. Equivalent to passing ``--test-load`` on the
871 An optional string. Equivalent to passing ``--show-only`` on the
872 command line. The string must be one of the following values:
880 An optional object specifying how to repeat tests. Equivalent to
881 passing ``--repeat`` on the command line. The object must have the
886 A required string. Must be one of the following values:
898 ``interactiveDebugging``
900 An optional bool. If true, equivalent to passing
901 ``--interactive-debug-mode 1`` on the command line. If false,
902 equivalent to passing ``--interactive-debug-mode 0`` on the command
907 An optional bool. If true, equivalent to passing ``--schedule-random``
912 An optional integer. Equivalent to passing ``--timeout`` on the
917 An optional string specifying the behavior if no tests are found. Must
918 be one of the following values:
922 Equivalent to not passing any value on the command line.
926 Equivalent to passing ``--no-tests=error`` on the command line.
930 Equivalent to passing ``--no-tests=ignore`` on the command line.
935 The ``condition`` field of a preset, allowed in preset files specifying version
936 ``3`` or above, is used to determine whether or not the preset is enabled. For
937 example, this can be used to disable a preset on platforms other than Windows.
938 ``condition`` may be either a boolean, ``null``, or an object. If it is a
939 boolean, the boolean indicates whether the preset is enabled or disabled. If it
940 is ``null``, the preset is enabled, but the ``null`` condition is not inherited
941 by any presets that may inherit from the preset. Sub-conditions (for example in
942 a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an
943 object, it has the following fields:
947 A required string with one of the following values:
951 Indicates that the condition is constant. This is equivalent to using a
952 boolean in place of the object. The condition object will have the
953 following additional fields:
957 A required boolean which provides a constant value for the condition's
964 Indicates that the condition compares two strings to see if they are equal
965 (or not equal). The condition object will have the following additional
970 First string to compare. This field supports macro expansion.
974 Second string to compare. This field supports macro expansion.
980 Indicates that the condition searches for a string in a list of strings.
981 The condition object will have the following additional fields:
985 A required string to search for. This field supports macro expansion.
989 A required list of strings to search. This field supports macro
990 expansion, and uses short-circuit evaluation.
996 Indicates that the condition searches for a regular expression in a string.
997 The condition object will have the following additional fields:
1001 A required string to search. This field supports macro expansion.
1005 A required regular expression to search for. This field supports macro
1012 Indicates that the condition is an aggregation of zero or more nested
1013 conditions. The condition object will have the following additional fields:
1017 A required array of condition objects. These conditions use short-circuit
1022 Indicates that the condition is an inversion of another condition. The
1023 condition object will have the following additional fields:
1027 A required condition object.
1032 As mentioned above, some fields support macro expansion. Macros are
1033 recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are
1034 evaluated in the context of the preset being used, even if the macro is in a
1035 field that was inherited from another preset. For example, if the ``Base``
1036 preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the
1037 ``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to
1040 It is an error to not put a closing brace at the end of a macro name. For
1041 example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by
1042 anything other than a left curly brace (``{``) with a possible namespace is
1043 interpreted as a literal dollar sign.
1045 Recognized macros include:
1049 Path to the project source directory (i.e. the same as
1050 :variable:`CMAKE_SOURCE_DIR`).
1052 ``${sourceParentDir}``
1054 Path to the project source directory's parent directory.
1056 ``${sourceDirName}``
1058 The last filename component of ``${sourceDir}``. For example, if
1059 ``${sourceDir}`` is ``/path/to/source``, this would be ``source``.
1063 Name specified in the preset's ``name`` field.
1067 Generator specified in the preset's ``generator`` field. For build and
1068 test presets, this will evaluate to the generator specified by
1069 ``configurePreset``.
1071 ``${hostSystemName}``
1073 The name of the host operating system. Contains the same value as
1074 :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files
1075 specifying version ``3`` or above.
1079 Path to the directory containing the preset file which contains the macro.
1080 This is allowed in preset files specifying version ``4`` or above.
1084 A literal dollar sign (``$``).
1088 Native character for separating lists of paths, such as ``:`` or ``;``.
1090 For example, by setting ``PATH`` to
1091 ``/path/to/ninja/bin${pathListSep}$env{PATH}``, ``${pathListSep}`` will
1092 expand to the underlying operating system's character used for
1093 concatenation in ``PATH``.
1095 This is allowed in preset files specifying version ``5`` or above.
1097 ``$env{<variable-name>}``
1099 Environment variable with name ``<variable-name>``. The variable name may
1100 not be an empty string. If the variable is defined in the ``environment``
1101 field, that value is used instead of the value from the parent environment.
1102 If the environment variable is not defined, this evaluates as an empty
1105 Note that while Windows environment variable names are case-insensitive,
1106 variable names within a preset are still case-sensitive. This may lead to
1107 unexpected results when using inconsistent casing. For best results, keep
1108 the casing of environment variable names consistent.
1110 ``$penv{<variable-name>}``
1112 Similar to ``$env{<variable-name>}``, except that the value only comes from
1113 the parent environment, and never from the ``environment`` field. This
1114 allows you to prepend or append values to existing environment variables.
1115 For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will
1116 prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This
1117 is needed because ``$env{<variable-name>}`` does not allow circular
1120 ``$vendor{<macro-name>}``
1122 An extension point for vendors to insert their own macros. CMake will not
1123 be able to use presets which have a ``$vendor{<macro-name>}`` macro, and
1124 effectively ignores such presets. However, it will still be able to use
1125 other presets from the same file.
1127 CMake does not make any attempt to interpret ``$vendor{<macro-name>}``
1128 macros. However, to avoid name collisions, IDE vendors should prefix
1129 ``<macro-name>`` with a very short (preferably <= 4 characters) vendor
1130 identifier prefix, followed by a ``.``, followed by the macro name. For
1131 example, the Example IDE could have ``$vendor{xide.ideInstallDir}``.
1136 :download:`This file </manual/presets/schema.json>` provides a machine-readable
1137 JSON schema for the ``CMakePresets.json`` format.