diff options
Diffstat (limited to 'Help/manual/cmake-presets.7.rst')
| -rw-r--r-- | Help/manual/cmake-presets.7.rst | 952 |
1 files changed, 727 insertions, 225 deletions
diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 6f137c459e..467818dfa6 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -29,337 +29,839 @@ is using Git, ``CMakePresets.json`` may be tracked, and Format ====== - The files are a JSON document with an object as the root: +The files are a JSON document with an object as the root: - .. literalinclude:: presets/example.json - :language: json +.. literalinclude:: presets/example.json + :language: json - The root object recognizes the following fields: +The root object recognizes the following fields: - ``version`` +``version`` - A required integer representing the version of the JSON schema. Currently, - the only supported version is 1. + A required integer representing the version of the JSON schema. + The supported versions are ``1`` and ``2``. - ``cmakeMinimumRequired`` +``cmakeMinimumRequired`` - An optional object representing the minimum version of CMake needed to - build this project. This object consists of the following fields: + An optional object representing the minimum version of CMake needed to + build this project. This object consists of the following fields: - ``major`` + ``major`` - An optional integer representing the major version. + An optional integer representing the major version. - ``minor`` + ``minor`` - An optional integer representing the minor version. + An optional integer representing the minor version. - ``patch`` + ``patch`` - An optional integer representing the patch version. + An optional integer representing the patch version. - ``vendor`` +``vendor`` - An optional map containing vendor-specific information. CMake does not - interpret the contents of this field except to verify that it is a map if - it does exist. However, the keys should be a vendor-specific domain name - followed by a ``/``-separated path. For example, the Example IDE 1.0 could - use ``example.com/ExampleIDE/1.0``. The value of each field can be anything - desired by the vendor, though will typically be a map. + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map if + it does exist. However, the keys should be a vendor-specific domain name + followed by a ``/``-separated path. For example, the Example IDE 1.0 could + use ``example.com/ExampleIDE/1.0``. The value of each field can be anything + desired by the vendor, though will typically be a map. - ``configurePresets`` +``configurePresets`` - An optional array of configure preset objects. Each preset may contain the - following fields: + An optional array of `Configure Preset`_ objects. + This is allowed in preset files specifying version 1 or above. - ``name`` +``buildPresets`` + + An optional array of `Build Preset`_ objects. + This is allowed in preset files specifying version 2 or above. + +``testPresets`` + + An optional array of `Test Preset`_ objects. + This is allowed in preset files specifying version 2 or above. + +Configure Preset +^^^^^^^^^^^^^^^^ + +Each entry of the ``configurePresets`` array is a JSON object +that may contain the following fields: + +``name`` + + A required string representing the machine-friendly name of the preset. + This identifier is used in the :ref:`cmake --preset <CMake Options>` option. + There must not be two configure presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a configure preset may have the same name as a build or test preset. + +``hidden`` + + An optional boolean specifying whether or not a preset should be hidden. + If a preset is hidden, it cannot be used in the ``--preset=`` argument, + will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not + have to have a valid ``generator`` or ``binaryDir``, even from + inheritance. ``hidden`` presets are intended to be used as a base for + other presets to inherit via the ``inherits`` field. + +``inherits`` + + An optional array of strings representing the names of presets to inherit + from. The preset will inherit all of the fields from the ``inherits`` + presets by default (except ``name``, ``hidden``, ``inherits``, + ``description``, and ``displayName``), but can override them as + desired. If multiple ``inherits`` presets provide conflicting values for + the same field, the earlier preset in the ``inherits`` list will be + preferred. Presets in ``CMakePresets.json`` may not inherit from presets + in ``CMakeUserPresets.json``. + + This field can also be a string, which is equivalent to an array + containing one string. + +``vendor`` + + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. If vendors use their own per-preset + ``vendor`` field, they should implement inheritance in a sensible manner + when appropriate. + +``displayName`` + + An optional string with a human-friendly name of the preset. + +``description`` + + An optional string with a human-friendly description of the preset. + +``generator`` + + An optional string representing the generator to use for the preset. If + ``generator`` is not specified, it must be inherited from the + ``inherits`` preset (unless this preset is ``hidden``). + + Note that for Visual Studio generators, unlike in the command line ``-G`` + argument, you cannot include the platform name in the generator name. Use + the ``architecture`` field instead. + +``architecture``, ``toolset`` + + Optional fields representing the platform and toolset, respectively, for + generators that support them. Each may be either a string or an object + with the following fields: + + ``value`` + + An optional string representing the value. + + ``strategy`` + + An optional string telling CMake how to handle the ``architecture`` or + ``toolset`` field. Valid values are: + + ``"set"`` + + Set the respective value. This will result in an error for generators + that do not support the respective field. + + ``"external"`` + + Do not set the value, even if the generator supports it. This is + useful if, for example, a preset uses the Ninja generator, and an IDE + knows how to set up the Visual C++ environment from the + ``architecture`` and ``toolset`` fields. In that case, CMake will + ignore the field, but the IDE can use them to set up the environment + before invoking CMake. + +``binaryDir`` + + An optional string representing the path to the output binary directory. + This field supports `macro expansion`_. If a relative path is specified, + it is calculated relative to the source directory. If ``binaryDir`` is not + specified, it must be inherited from the ``inherits`` preset (unless this + preset is ``hidden``). + +``cmakeExecutable`` + + An optional string representing the path to the CMake executable to use + for this preset. This is reserved for use by IDEs, and is not used by + CMake itself. IDEs that use this field should expand any macros in it. + +``cacheVariables`` + + An optional map of cache variables. The key is the variable name (which + may not be an empty string), and the value is either ``null``, a boolean + (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type + of ``BOOL``), a string representing the value of the variable (which + supports `macro expansion`_), or an object with the following fields: + + ``type`` + + An optional string representing the type of the variable. + + ``value`` + + A required string or boolean representing the value of the variable. + A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field + supports `macro expansion`_. + + Cache variables are inherited through the ``inherits`` field, and the + preset's variables will be the union of its own ``cacheVariables`` and + the ``cacheVariables`` from all its parents. If multiple presets in this + union define the same variable, the standard rules of ``inherits`` are + applied. Setting a variable to ``null`` causes it to not be set, even if + a value was inherited from another preset. + +``environment`` + + An optional map of environment variables. The key is the variable name + (which may not be an empty string), and the value is either ``null`` or + a string representing the value of the variable. Each variable is set + regardless of whether or not a value was given to it by the process's + environment. This field supports `macro expansion`_, and environment + variables in this map may reference each other, and may be listed in any + order, as long as such references do not cause a cycle (for example, + if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) + + Environment variables are inherited through the ``inherits`` field, and + the preset's environment will be the union of its own ``environment`` and + the ``environment`` from all its parents. If multiple presets in this + union define the same variable, the standard rules of ``inherits`` are + applied. Setting a variable to ``null`` causes it to not be set, even if + a value was inherited from another preset. + +``warnings`` + + An optional object specifying the warnings to enable. The object may + contain the following fields: + + ``dev`` + + An optional boolean. Equivalent to passing ``-Wdev`` or ``-Wno-dev`` + on the command line. This may not be set to ``false`` if ``errors.dev`` + is set to ``true``. + + ``deprecated`` + + An optional boolean. Equivalent to passing ``-Wdeprecated`` or + ``-Wno-deprecated`` on the command line. This may not be set to + ``false`` if ``errors.deprecated`` is set to ``true``. + + ``uninitialized`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--warn-uninitialized`` on the command line. + + ``unusedCli`` + + An optional boolean. Setting this to ``false`` is equivalent to passing + ``--no-warn-unused-cli`` on the command line. + + ``systemVars`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--check-system-vars`` on the command line. + +``errors`` + + An optional object specifying the errors to enable. The object may + contain the following fields: + + ``dev`` + + An optional boolean. Equivalent to passing ``-Werror=dev`` or + ``-Wno-error=dev`` on the command line. This may not be set to ``true`` + if ``warnings.dev`` is set to ``false``. + + ``deprecated`` + + An optional boolean. Equivalent to passing ``-Werror=deprecated`` or + ``-Wno-error=deprecated`` on the command line. This may not be set to + ``true`` if ``warnings.deprecated`` is set to ``false``. + +``debug`` + + An optional object specifying debug options. The object may contain the + following fields: + + ``output`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-output`` on the command line. + + ``tryCompile`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-trycompile`` on the command line. + + ``find`` + + An optional boolean. Setting this to ``true`` is equivalent to passing + ``--debug-find`` on the command line. + +Build Preset +^^^^^^^^^^^^ + +Each entry of the ``buildPresets`` array is a JSON object +that may contain the following fields: + +``name`` + + A required string representing the machine-friendly name of the preset. + This identifier is used in the + :ref:`cmake --build --preset <Build Tool Mode>` option. + There must not be two build presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a build preset may have the same name as a configure or test preset. + +``hidden`` + + An optional boolean specifying whether or not a preset should be hidden. + If a preset is hidden, it cannot be used in the ``--preset`` argument + and does not have to have a valid ``configurePreset``, even from + inheritance. ``hidden`` presets are intended to be used as a base for + other presets to inherit via the ``inherits`` field. + +``inherits`` + + An optional array of strings representing the names of presets to + inherit from. The preset will inherit all of the fields from the + ``inherits`` presets by default (except ``name``, ``hidden``, + ``inherits``, ``description``, and ``displayName``), but can override + them as desired. If multiple ``inherits`` presets provide conflicting + values for the same field, the earlier preset in the ``inherits`` list + will be preferred. Presets in ``CMakePresets.json`` may not inherit from + presets in ``CMakeUserPresets.json``. + + This field can also be a string, which is equivalent to an array + containing one string. + +``vendor`` + + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. If vendors use their own per-preset + ``vendor`` field, they should implement inheritance in a sensible manner + when appropriate. + +``displayName`` + + An optional string with a human-friendly name of the preset. + +``description`` + + An optional string with a human-friendly description of the preset. - A required string representing the machine-friendly name of the preset. - This identifier is used in the ``--preset`` argument. There must not be - two presets in the union of ``CMakePresets.json`` and - ``CMakeUserPresets.json`` in the same directory with the same name. +``environment`` - ``hidden`` + An optional map of environment variables. The key is the variable name + (which may not be an empty string), and the value is either ``null`` or + a string representing the value of the variable. Each variable is set + regardless of whether or not a value was given to it by the process's + environment. This field supports macro expansion, and environment + variables in this map may reference each other, and may be listed in any + order, as long as such references do not cause a cycle (for example, if + ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) - An optional boolean specifying whether or not a preset should be hidden. - If a preset is hidden, it cannot be used in the ``--preset=`` argument, - will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not - have to have a valid ``generator`` or ``binaryDir``, even from - inheritance. ``hidden`` presets are intended to be used as a base for - other presets to inherit via the ``inherits`` field. + Environment variables are inherited through the ``inherits`` field, and + the preset's environment will be the union of its own ``environment`` + and the ``environment`` from all its parents. If multiple presets in + this union define the same variable, the standard rules of ``inherits`` + are applied. Setting a variable to ``null`` causes it to not be set, + even if a value was inherited from another preset. - ``inherits`` +``configurePreset`` - An optional array of strings representing the names of presets to inherit - from. The preset will inherit all of the fields from the ``inherits`` - presets by default (except ``name``, ``hidden``, ``inherits``, - ``description``, and ``displayName``), but can override them as - desired. If multiple ``inherits`` presets provide conflicting values for - the same field, the earlier preset in the ``inherits`` list will be - preferred. Presets in ``CMakePresets.json`` may not inherit from presets - in ``CMakeUserPresets.json``. + An optional string specifying the name of a configure preset to + associate with this build preset. If ``configurePreset`` is not + specified, it must be inherited from the inherits preset (unless this + preset is hidden). The build directory is inferred from the configure + preset, so the build will take place in the same ``binaryDir`` that the + configuration did. - This field can also be a string, which is equivalent to an array - containing one string. +``inheritConfigureEnvironment`` - ``vendor`` + An optional boolean that defaults to true. If true, the environment + variables from the associated configure preset are inherited after all + inherited build preset environments, but before environment variables + explicitly specified in this build preset. - An optional map containing vendor-specific information. CMake does not - interpret the contents of this field except to verify that it is a map - if it does exist. However, it should follow the same conventions as the - root-level ``vendor`` field. If vendors use their own per-preset - ``vendor`` field, they should implement inheritance in a sensible manner - when appropriate. +``jobs`` - ``displayName`` + An optional integer. Equivalent to passing ``--parallel`` or ``-j`` on + the command line. - An optional string with a human-friendly name of the preset. +``targets`` - ``description`` + An optional string or array of strings. Equivalent to passing + ``--target`` or ``-t`` on the command line. Vendors may ignore the + targets property or hide build presets that explicitly specify targets. + This field supports macro expansion. - An optional string with a human-friendly description of the preset. +``configuration`` - ``generator`` + An optional string. Equivalent to passing ``--config`` on the command + line. - An optional string representing the generator to use for the preset. If - ``generator`` is not specified, it must be inherited from the - ``inherits`` preset (unless this preset is ``hidden``). +``cleanFirst`` - Note that for Visual Studio generators, unlike in the command line ``-G`` - argument, you cannot include the platform name in the generator name. Use - the ``architecture`` field instead. + An optional bool. If true, equivalent to passing ``--clean-first`` on + the command line. - ``architecture`` - ``toolset`` +``verbose`` - Optional fields representing the platform and toolset, respectively, for - generators that support them. Each may be either a string or an object - with the following fields: + An optional bool. If true, equivalent to passing ``--verbose`` on the + command line. - ``value`` +``nativeToolOptions`` - An optional string representing the value. + An optional array of strings. Equivalent to passing options after ``--`` + on the command line. The array values support macro expansion. - ``strategy`` +Test Preset +^^^^^^^^^^^ - An optional string telling CMake how to handle the ``architecture`` or - ``toolset`` field. Valid values are: +Each entry of the ``testPresets`` array is a JSON object +that may contain the following fields: - ``"set"`` +``name`` - Set the respective value. This will result in an error for generators - that do not support the respective field. + A required string representing the machine-friendly name of the preset. + This identifier is used in the :ref:`ctest --preset <CTest Options>` option. + There must not be two test presets in the union of ``CMakePresets.json`` + and ``CMakeUserPresets.json`` in the same directory with the same name. + However, a test preset may have the same name as a configure or build preset. - ``"external"`` +``hidden`` - Do not set the value, even if the generator supports it. This is - useful if, for example, a preset uses the Ninja generator, and an IDE - knows how to set up the Visual C++ environment from the - ``architecture`` and ``toolset`` fields. In that case, CMake will - ignore the field, but the IDE can use them to set up the environment - before invoking CMake. + An optional boolean specifying whether or not a preset should be hidden. + If a preset is hidden, it cannot be used in the ``--preset`` argument + and does not have to have a valid ``configurePreset``, even from + inheritance. ``hidden`` presets are intended to be used as a base for + other presets to inherit via the ``inherits`` field. - ``binaryDir`` +``inherits`` - An optional string representing the path to the output binary directory. - This field supports macro expansion. If a relative path is specified, it - is calculated relative to the source directory. If ``binaryDir`` is not - specified, it must be inherited from the ``inherits`` preset (unless this - preset is ``hidden``). + An optional array of strings representing the names of presets to + inherit from. The preset will inherit all of the fields from the + ``inherits`` presets by default (except ``name``, ``hidden``, + ``inherits``, ``description``, and ``displayName``), but can override + them as desired. If multiple ``inherits`` presets provide conflicting + values for the same field, the earlier preset in the ``inherits`` list + will be preferred. Presets in ``CMakePresets.json`` may not inherit from + presets in ``CMakeUserPresets.json``. - ``cmakeExecutable`` + This field can also be a string, which is equivalent to an array + containing one string. - An optional string representing the path to the CMake executable to use - for this preset. This is reserved for use by IDEs, and is not used by - CMake itself. IDEs that use this field should expand any macros in it. +``vendor`` - ``cacheVariables`` + An optional map containing vendor-specific information. CMake does not + interpret the contents of this field except to verify that it is a map + if it does exist. However, it should follow the same conventions as the + root-level ``vendor`` field. If vendors use their own per-preset + ``vendor`` field, they should implement inheritance in a sensible manner + when appropriate. - An optional map of cache variables. The key is the variable name (which - may not be an empty string), and the value is either ``null``, a boolean - (which is equivalent to a value of ``"TRUE"`` or ``"FALSE"`` and a type - of ``BOOL``), a string representing the value of the variable (which - supports macro expansion), or an object with the following fields: +``displayName`` - ``type`` + An optional string with a human-friendly name of the preset. - An optional string representing the type of the variable. +``description`` - ``value`` + An optional string with a human-friendly description of the preset. - A required string or boolean representing the value of the variable. - A boolean is equivalent to ``"TRUE"`` or ``"FALSE"``. This field +``environment`` + + An optional map of environment variables. The key is the variable name + (which may not be an empty string), and the value is either ``null`` or + a string representing the value of the variable. Each variable is set + regardless of whether or not a value was given to it by the process's + environment. This field supports macro expansion, and environment + variables in this map may reference each other, and may be listed in any + order, as long as such references do not cause a cycle (for example, if + ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) + + Environment variables are inherited through the ``inherits`` field, and + the preset's environment will be the union of its own ``environment`` + and the ``environment`` from all its parents. If multiple presets in + this union define the same variable, the standard rules of ``inherits`` + are applied. Setting a variable to ``null`` causes it to not be set, + even if a value was inherited from another preset. + +``configurePreset`` + + An optional string specifying the name of a configure preset to + associate with this test preset. If ``configurePreset`` is not + specified, it must be inherited from the inherits preset (unless this + preset is hidden). The build directory is inferred from the configure + preset, so tests will run in the same ``binaryDir`` that the + configuration did and build did. + +``inheritConfigureEnvironment`` + + An optional boolean that defaults to true. If true, the environment + variables from the associated configure preset are inherited after all + inherited test preset environments, but before environment variables + explicitly specified in this test preset. + +``configuration`` + + An optional string. Equivalent to passing ``--build-config`` on the + command line. + +``overwriteConfigurationFile`` + + An optional array of configuration options to overwrite options + specified in the CTest configuration file. Equivalent to passing + ``--overwrite`` for each value in the array. The array values + support macro expansion. + +``output`` + + An optional object specifying output options. The object may contain the + following fields. + + ``shortProgress`` + + An optional bool. If true, equivalent to passing ``--progress`` on the + command line. + + ``verbosity`` + + An optional string specifying verbosity level. Must be one of the + following: + + ``default`` + + Equivalent to passing no verbosity flags on the command line. + + ``verbose`` + + Equivalent to passing ``--verbose`` on the command line. + + ``extra`` + + Equivalent to passing ``--extra-verbose`` on the command line. + + ``debug`` + + An optional bool. If true, equivalent to passing ``--debug`` on the + command line. + + ``outputOnFailure`` + + An optional bool. If true, equivalent to passing + ``--output-on-failure`` on the command line. + + ``quiet`` + + An optional bool. If true, equivalent to passing ``--quiet`` on the + command line. + + ``outputLogFile`` + + An optional string specifying a path to a log file. Equivalent to + passing ``--output-log`` on the command line. This field supports + macro expansion. + + ``labelSummary`` + + An optional bool. If false, equivalent to passing + ``--no-label-summary`` on the command line. + + ``subprojectSummary`` + + An optional bool. If false, equivalent to passing + ``--no-subproject-summary`` on the command line. + + ``maxPassedTestOutputSize`` + + An optional integer specifying the maximum output for passed tests in + bytes. Equivalent to passing ``--test-output-size-passed`` on the + command line. + + ``maxFailedTestOutputSize`` + + An optional integer specifying the maximum output for failed tests in + bytes. Equivalent to passing ``--test-output-size-failed`` on the + command line. + + ``maxTestNameWidth`` + + An optional integer specifying the maximum width of a test name to + output. Equivalent to passing ``--max-width`` on the command line. + +``filter`` + + An optional object specifying how to filter the tests to run. The object + may contain the following fields. + + ``include`` + + An optional object specifying which tests to include. The object may + contain the following fields. + + ``name`` + + An optional string specifying a regex for test names. Equivalent to + passing ``--tests-regex`` on the command line. This field supports + macro expansion. + + + ``label`` + + An optional string specifying a regex for test labels. Equivalent to + passing ``--label-regex`` on the command line. This field supports + macro expansion. + + ``useUnion`` + + An optional bool. Equivalent to passing ``--union`` on the command + line. + + ``index`` + + An optional object specifying tests to include by test index. The + object may contain the following fields. Can also be an optional + string specifying a file with the command line syntax for + ``--tests-information``. If specified as a string, this field + supports macro expansion. + + ``start`` + + An optional integer specifying a test index to start testing at. + + ``end`` + + An optional integer specifying a test index to stop testing at. + + ``stride`` + + An optional integer specifying the increment. + + ``specificTests`` + + An optional array of integers specifying specific test indices to + run. + + ``exclude`` + + An optional object specifying which tests to exclude. The object may + contain the following fields. + + ``name`` + + An optional string specifying a regex for test names. Equivalent to + passing ``--exclude-regex`` on the command line. This field supports + macro expansion. + + ``label`` + + An optional string specifying a regex for test labels. Equivalent to + passing ``--label-exclude`` on the command line. This field supports + macro expansion. + + ``fixtures`` + + An optional object specifying which fixtures to exclude from adding + tests. The object may contain the following fields. + + ``any`` + + An optional string specifying a regex for text fixtures to exclude + from adding any tests. Equivalent to ``--fixture-exclude-any`` on + the command line. This field supports macro expansion. + + ``setup`` + + An optional string specifying a regex for text fixtures to exclude + from adding setup tests. Equivalent to ``--fixture-exclude-setup`` + on the command line. This field supports macro expansion. + + ``cleanup`` + + An optional string specifying a regex for text fixtures to exclude + from adding cleanup tests. Equivalent to + ``--fixture-exclude-cleanup`` on the command line. This field supports macro expansion. - Cache variables are inherited through the ``inherits`` field, and the - preset's variables will be the union of its own ``cacheVariables`` and - the ``cacheVariables`` from all its parents. If multiple presets in this - union define the same variable, the standard rules of ``inherits`` are - applied. Setting a variable to ``null`` causes it to not be set, even if - a value was inherited from another preset. +``execution`` + + An optional object specifying options for test execution. The object may + contain the following fields. + + ``stopOnFailure`` + + An optional bool. If true, equivalent to passing ``--stop-on-failure`` + on the command line. + + ``enableFailover`` + + An optional bool. If true, equivalent to passing ``-F`` on the command + line. + + ``jobs`` + + An optional integer. Equivalent to passing ``--parallel`` on the + command line. + + ``resourceSpecFile`` + + An optional string. Equivalent to passing ``--resource-spec-file`` on + the command line. This field supports macro expansion. + + ``testLoad`` - ``environment`` + An optional integer. Equivalent to passing ``--test-load`` on the + command line. - An optional map of environment variables. The key is the variable name - (which may not be an empty string), and the value is either ``null`` or - a string representing the value of the variable. Each variable is set - regardless of whether or not a value was given to it by the process's - environment. This field supports macro expansion, and environment - variables in this map may reference each other, and may be listed in any - order, as long as such references do not cause a cycle (for example, - if ``ENV_1`` is ``$env{ENV_2}``, ``ENV_2`` may not be ``$env{ENV_1}``.) + ``showOnly`` - Environment variables are inherited through the ``inherits`` field, and - the preset's environment will be the union of its own ``environment`` and - the ``environment`` from all its parents. If multiple presets in this - union define the same variable, the standard rules of ``inherits`` are - applied. Setting a variable to ``null`` causes it to not be set, even if - a value was inherited from another preset. + An optional string. Equivalent to passing ``--show-only`` on the + command line. The string must be one of the following values: - ``warnings`` + ``human`` - An optional object specifying the warnings to enable. The object may - contain the following fields: + ``json-v1`` - ``dev`` + ``repeat`` - An optional boolean. Equivalent to passing ``-Wdev`` or ``-Wno-dev`` - on the command line. This may not be set to ``false`` if ``errors.dev`` - is set to ``true``. + An optional object specifying how to repeat tests. Equivalent to + passing ``--repeat`` on the command line. The object must have the + following fields. - ``deprecated`` + ``mode`` - An optional boolean. Equivalent to passing ``-Wdeprecated`` or - ``-Wno-deprecated`` on the command line. This may not be set to - ``false`` if ``errors.deprecated`` is set to ``true``. + A required string. Must be one of the following values: - ``uninitialized`` + ``until-fail`` - An optional boolean. Setting this to ``true`` is equivalent to passing - ``--warn-uninitialized`` on the command line. + ``until-pass`` - ``unusedCli`` + ``after-timeout`` - An optional boolean. Setting this to ``false`` is equivalent to passing - ``--no-warn-unused-cli`` on the command line. + ``count`` - ``systemVars`` + A required integer. - An optional boolean. Setting this to ``true`` is equivalent to passing - ``--check-system-vars`` on the command line. + ``interactiveDebugging`` - ``errors`` + An optional bool. If true, equivalent to passing + ``--interactive-debug-mode 1`` on the command line. If false, + equivalent to passing ``--interactive-debug-mode 0`` on the command + line. - An optional object specifying the errors to enable. The object may - contain the following fields: + ``scheduleRandom`` - ``dev`` + An optional bool. If true, equivalent to passing ``--schedule-random`` + on the command line. - An optional boolean. Equivalent to passing ``-Werror=dev`` or - ``-Wno-error=dev`` on the command line. This may not be set to ``true`` - if ``warnings.dev`` is set to ``false``. + ``timeout`` - ``deprecated`` + An optional integer. Equivalent to passing ``--timeout`` on the + command line. - An optional boolean. Equivalent to passing ``-Werror=deprecated`` or - ``-Wno-error=deprecated`` on the command line. This may not be set to - ``true`` if ``warnings.deprecated`` is set to ``false``. + ``noTestsAction`` - ``debug`` + An optional string specifying the behavior if no tests are found. Must + be one of the following values: - An optional object specifying debug options. The object may contain the - following fields: + ``default`` - ``output`` + Equivalent to not passing any value on the command line. - An optional boolean. Setting this to ``true`` is equivalent to passing - ``--debug-output`` on the command line. + ``error`` - ``tryCompile`` + Equivalent to passing ``--no-tests=error`` on the command line. - An optional boolean. Setting this to ``true`` is equivalent to passing - ``--debug-trycompile`` on the command line. + ``ignore`` - ``find`` + Equivalent to passing ``--no-tests=ignore`` on the command line. - An optional boolean. Setting this to ``true`` is equivalent to passing - ``--debug-find`` on the command line. +Macro Expansion +^^^^^^^^^^^^^^^ - As mentioned above, some fields support macro expansion. Macros are - recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are - evaluated in the context of the preset being used, even if the macro is in a - field that was inherited from another preset. For example, if the ``Base`` - preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the - ``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to - ``Derived``. +As mentioned above, some fields support macro expansion. Macros are +recognized in the form ``$<macro-namespace>{<macro-name>}``. All macros are +evaluated in the context of the preset being used, even if the macro is in a +field that was inherited from another preset. For example, if the ``Base`` +preset sets variable ``PRESET_NAME`` to ``${presetName}``, and the +``Derived`` preset inherits from ``Base``, ``PRESET_NAME`` will be set to +``Derived``. - It is an error to not put a closing brace at the end of a macro name. For - example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by - anything other than a left curly brace (``{``) with a possible namespace is - interpreted as a literal dollar sign. +It is an error to not put a closing brace at the end of a macro name. For +example, ``${sourceDir`` is invalid. A dollar sign (``$``) followed by +anything other than a left curly brace (``{``) with a possible namespace is +interpreted as a literal dollar sign. - Recognized macros include: +Recognized macros include: - ``${sourceDir}`` +``${sourceDir}`` - Path to the project source directory. + Path to the project source directory. - ``${sourceParentDir}`` +``${sourceParentDir}`` - Path to the project source directory's parent directory. + Path to the project source directory's parent directory. - ``${sourceDirName}`` +``${sourceDirName}`` - The last filename component of ``${sourceDir}``. For example, if - ``${sourceDir}`` is ``/path/to/source``, this would be ``source``. + The last filename component of ``${sourceDir}``. For example, if + ``${sourceDir}`` is ``/path/to/source``, this would be ``source``. - ``${presetName}`` +``${presetName}`` - Name specified in the preset's ``name`` field. + Name specified in the preset's ``name`` field. - ``${generator}`` +``${generator}`` - Generator specified in the preset's ``generator`` field. + Generator specified in the preset's ``generator`` field. For build and + test presets, this will evaluate to the generator specified by + ``configurePreset``. - ``${dollar}`` +``${dollar}`` - A literal dollar sign (``$``). + A literal dollar sign (``$``). - ``$env{<variable-name>}`` +``$env{<variable-name>}`` - Environment variable with name ``<variable-name>``. The variable name may - not be an empty string. If the variable is defined in the ``environment`` - field, that value is used instead of the value from the parent environment. - If the environment variable is not defined, this evaluates as an empty - string. + Environment variable with name ``<variable-name>``. The variable name may + not be an empty string. If the variable is defined in the ``environment`` + field, that value is used instead of the value from the parent environment. + If the environment variable is not defined, this evaluates as an empty + string. - Note that while Windows environment variable names are case-insensitive, - variable names within a preset are still case-sensitive. This may lead to - unexpected results when using inconsistent casing. For best results, keep - the casing of environment variable names consistent. + Note that while Windows environment variable names are case-insensitive, + variable names within a preset are still case-sensitive. This may lead to + unexpected results when using inconsistent casing. For best results, keep + the casing of environment variable names consistent. - ``$penv{<variable-name>}`` +``$penv{<variable-name>}`` - Similar to ``$env{<variable-name>}``, except that the value only comes from - the parent environment, and never from the ``environment`` field. This - allows you to prepend or append values to existing environment variables. - For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will - prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This - is needed because ``$env{<variable-name>}`` does not allow circular - references. + Similar to ``$env{<variable-name>}``, except that the value only comes from + the parent environment, and never from the ``environment`` field. This + allows you to prepend or append values to existing environment variables. + For example, setting ``PATH`` to ``/path/to/ninja/bin:$penv{PATH}`` will + prepend ``/path/to/ninja/bin`` to the ``PATH`` environment variable. This + is needed because ``$env{<variable-name>}`` does not allow circular + references. - ``$vendor{<macro-name>}`` +``$vendor{<macro-name>}`` - An extension point for vendors to insert their own macros. CMake will not - be able to use presets which have a ``$vendor{<macro-name>}`` macro, and - effectively ignores such presets. However, it will still be able to use - other presets from the same file. + An extension point for vendors to insert their own macros. CMake will not + be able to use presets which have a ``$vendor{<macro-name>}`` macro, and + effectively ignores such presets. However, it will still be able to use + other presets from the same file. - CMake does not make any attempt to interpret ``$vendor{<macro-name>}`` - macros. However, to avoid name collisions, IDE vendors should prefix - ``<macro-name>`` with a very short (preferably <= 4 characters) vendor - identifier prefix, followed by a ``.``, followed by the macro name. For - example, the Example IDE could have ``$vendor{xide.ideInstallDir}``. + CMake does not make any attempt to interpret ``$vendor{<macro-name>}`` + macros. However, to avoid name collisions, IDE vendors should prefix + ``<macro-name>`` with a very short (preferably <= 4 characters) vendor + identifier prefix, followed by a ``.``, followed by the macro name. For + example, the Example IDE could have ``$vendor{xide.ideInstallDir}``. Schema ====== |