| --- |
| version: 12 |
| types: |
| - id: condition |
| type: variant |
| items: |
| - type: boolean |
| description: |
| A boolean which provides a constant value for the condition's |
| evaluation. |
| # 'const' condition |
| - type: object |
| unevaluatedProperties: false |
| properties: |
| type: |
| type: string |
| required: true |
| const: const |
| description: |
| A required string specifying the type of the condition. |
| value: |
| type: boolean |
| required: true |
| description: |
| A required boolean which provides a constant value for the |
| condition's evaluation. |
| # 'equals', 'notEquals' condition |
| - type: object |
| unevaluatedProperties: false |
| properties: |
| type: |
| type: string |
| required: true |
| enum: |
| - equals |
| - notEquals |
| description: |
| A required string specifying the type of the condition. |
| lhs: |
| type: string |
| required: true |
| description: |
| First string to compare. This field supports macro expansion. |
| rhs: |
| type: string |
| required: true |
| description: |
| Second string to compare. This field supports macro expansion. |
| # 'inList', 'notInList' condition |
| - type: object |
| properties: |
| type: |
| type: string |
| required: true |
| enum: |
| - inList |
| - notInList |
| description: |
| A required string specifying the type of the condition. |
| string: |
| type: string |
| required: true |
| description: |
| A required string to search for. This field supports macro |
| expansion. |
| list: |
| type: array |
| required: true |
| items: |
| type: string |
| description: |
| A required array of strings to search. This field supports macro |
| expansion, and uses short-circuit evaluation. |
| unevaluatedProperties: false |
| # 'matches', 'notMatches' condition |
| - type: object |
| properties: |
| type: |
| type: string |
| required: true |
| enum: |
| - matches |
| - notMatches |
| description: |
| A required string specifying the type of the condition. |
| string: |
| type: string |
| required: true |
| description: |
| A required string to search. This field supports macro expansion. |
| regex: |
| type: string |
| required: true |
| description: |
| A required regular expression to search for. This field supports |
| macro expansion. |
| unevaluatedProperties: false |
| # 'anyOf', 'allOf' condition |
| - type: object |
| properties: |
| type: |
| type: string |
| required: true |
| enum: |
| - anyOf |
| - allOf |
| description: |
| A required string specifying the type of the condition. |
| conditions: |
| type: array |
| required: true |
| description: |
| A required array of condition objects. These conditions use |
| short-circuit evaluation. |
| items: |
| type: ref |
| target: condition |
| unevaluatedProperties: false |
| # 'not' condition |
| - type: object |
| properties: |
| type: |
| type: string |
| required: true |
| const: not |
| description: |
| A required string specifying the type of the condition. |
| condition: |
| type: ref |
| required: true |
| target: condition |
| unevaluatedProperties: false |
| definitions: |
| inherits: &preset-inherits |
| anyOf: |
| - type: string |
| minLength: 1 |
| description: |
| An optional string representing the name of the preset from which to |
| inherit. |
| - type: array |
| description: |
| An optional array of strings representing the names of presets from |
| which to inherit. 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 must not inherit from presets in |
| CMakeUserPresets.json. |
| items: |
| type: string |
| minLength: 1 |
| description: |
| An optional string representing the name of the preset from which |
| to inherit. |
| sphinxDescription: | |
| An optional array of strings representing the names of presets from which |
| to inherit. This field can also be a string, which is equivalent to an |
| array containing one string. |
| |
| 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`` array will be preferred. |
| |
| A preset can only inherit from another preset that is defined in the same |
| file or in one of the files it includes (directly or indirectly). Presets |
| in ``CMakePresets.json`` may not inherit from presets in |
| ``CMakeUserPresets.json``. |
| vendor: &preset-vendor |
| type: object |
| minLength: 1 |
| description: |
| 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. |
| sphinxDescription: | |
| 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. |
| properties: {} |
| displayName: &preset-displayName |
| type: string |
| description: |
| An optional string with a human-friendly name of the preset. |
| description: &preset-description |
| type: string |
| description: |
| An optional string with a human-friendly description of the preset. |
| environment: &preset-environment |
| type: object |
| description: &environment-description |
| An optional map of environment variables. The key is the variable name |
| (which must not be an empty string). 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. |
| sphinxDescription: &environment-sphinx-description | |
| 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}``). ``$penv{NAME}`` |
| allows one to prepend or append values to existing environment variables |
| by accessing only values from the parent environment. |
| |
| 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. |
| properties: {} |
| propertyNames: |
| pattern: '^.+$' |
| additionalProperties: &environment-additional-properties |
| anyOf: |
| - type: 'null' |
| description: |
| Setting a variable to null causes it to not be set, even if a value |
| was inherited from another preset. |
| - type: string |
| description: |
| A string representing the value of the variable. |
| architecture-or-toolset: &architecture-or-toolset-properties |
| value: |
| type: string |
| description: An optional string representing the value. |
| strategy: |
| type: string |
| enum: |
| - set |
| - external |
| description: ' |
| An optional string telling CMake how to handle the 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. |
| ' |
| sphinxDescription: | |
| An optional string telling CMake how to handle the 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. |
| |
| If no ``strategy`` field is given, or if the field uses the string form |
| rather than the object form, the behavior is the same as ``"set"``. |
| condition: &condition |
| since: 3 |
| anyOf: |
| - type: ref |
| target: condition |
| - type: 'null' |
| description: |
| Null indicates that the condition always evaluates to true and is not |
| inherited. |
| sphinxDescription: | |
| An optional `Condition`_ object. |
| description: |
| The presets specify the generator and the build directory, and optionally an |
| array of variables and other arguments to pass to CMake. |
| properties: |
| $schema: |
| since: 8 |
| type: string |
| format: uri-reference |
| description: |
| An optional string that provides a URI to the JSON schema that describes |
| the structure of this JSON document. This field is used for validation |
| and autocompletion in editors that support JSON schema. It doesn't affect |
| the behavior of the document itself. If this field is not specified, the |
| JSON document will still be valid, but tools that use JSON schema for |
| validation and autocompletion may not function correctly. |
| version: |
| type: integer |
| required: true |
| description: |
| A required integer representing the version of the JSON schema. |
| sphinxDescription: | |
| A required integer representing the version of the JSON schema. See |
| `Versions`_ for discussion of the supported versions and the |
| corresponding version of CMake in which they were added. |
| cmakeMinimumRequired: |
| type: object |
| description: |
| An optional object representing the minimum version of CMake |
| needed to build this project. |
| sphinxDescription: | |
| An optional object representing the minimum version of CMake |
| needed to build this project. This object consists of the following |
| fields: |
| |
| .. include:: presets/cmakeMinimumRequired-properties.rst |
| properties: |
| major: |
| type: integer |
| description: An optional integer representing the major version. |
| minor: |
| type: integer |
| description: An optional integer representing the minor version. |
| patch: |
| type: integer |
| description: An optional integer representing the patch version. |
| unevaluatedProperties: false |
| include: |
| since: 4 |
| type: array |
| items: |
| type: string |
| description: |
| An optional array of strings representing files to include. If the |
| filenames are not absolute, they are considered relative to the current |
| file. |
| sphinxDescription: | |
| An optional array of strings representing files to include. If the |
| filenames are not absolute, they are considered relative to the current |
| file. See `Includes`_ for discussion of the constraints on included |
| files. |
| vendor: |
| type: object |
| description: |
| 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. |
| sphinxDescription: | |
| 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. |
| properties: {} |
| configurePresets: |
| type: array |
| description: |
| An optional array of configure preset objects. |
| sphinxDescription: | |
| An optional array of `Configure Preset`_ objects. |
| items: |
| type: object |
| description: |
| A configure preset object. |
| properties: |
| name: |
| type: string |
| required: true |
| minLength: 1 |
| description: |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the cmake --preset 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, test, package, or workflow preset. |
| sphinxDescription: | |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the :option:`cmake --preset` |
| 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, test, package, or workflow preset. |
| hidden: |
| type: boolean |
| description: |
| 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 CMake GUI, 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. |
| sphinxDescription: | |
| An optional boolean specifying whether or not a preset should be |
| hidden. If a preset is hidden, it cannot be used in the |
| :cmake-option:`--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: *preset-inherits |
| condition: *condition |
| vendor: *preset-vendor |
| displayName: *preset-displayName |
| description: *preset-description |
| generator: |
| revisions: |
| - until: 3 |
| type: string |
| description: |
| 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. |
| - since: 3 |
| type: string |
| description: |
| An optional string representing the generator to use for the |
| preset. If generator is not specified, the normal generator |
| discovery procedure is used. 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. |
| sphinxDescription: | |
| An optional string representing the |
| :manual:`generator <cmake-generators(7)>` to use for the preset. |
| |
| .. presets-versionchanged:: 3 |
| |
| If omitted, CMake will fall back to regular generator discovery |
| procedure. In previous versions, if not specified, this field |
| must be inherited from the ``inherits`` preset (unless this |
| preset is ``hidden``). |
| |
| Note that for :ref:`Visual Studio generators`, unlike in the |
| command line :cmake-option:`-G` argument, you cannot include the |
| platform name in the generator name. Use the ``architecture`` |
| field instead. |
| architecture: |
| anyOf: |
| - type: string |
| description: &architectureDescription |
| An optional string representing the platform for generators |
| that support it. |
| - type: object |
| description: *architectureDescription |
| properties: *architecture-or-toolset-properties |
| unevaluatedProperties: false |
| sphinxDescription: | |
| Optional field representing the platform for |
| :manual:`generators <cmake-generators(7)>` that support it. |
| |
| See :option:`cmake -A` for possible values. |
| |
| ``architecture`` may be either a string or an object with the |
| following fields: |
| |
| .. include:: presets/architecture-properties.rst |
| toolset: |
| anyOf: |
| - type: string |
| description: &toolsetDescription |
| An optional string representing the toolset for generators that |
| support it. |
| - type: object |
| description: *toolsetDescription |
| properties: *architecture-or-toolset-properties |
| unevaluatedProperties: false |
| sphinxDescription: | |
| Optional field representing the toolset for |
| :manual:`generators <cmake-generators(7)>` that support it. |
| |
| See :option:`cmake -T` for possible values. |
| |
| ``toolset`` may be either a string or an object with the following |
| fields: |
| |
| .. include:: presets/toolset-properties.rst |
| toolchainFile: |
| since: 3 |
| type: string |
| description: |
| An optional string representing the path to the toolchain file. |
| This field supports macro expansion. If a relative path is |
| specified, it is calculated relative to the build directory, and if |
| not found, relative to the source directory. |
| sphinxDescription: | |
| An optional string representing the path to the toolchain file. |
| This field supports `macro expansion`_. If a relative path is |
| specified, it is calculated relative to the build directory, and if |
| not found, relative to the source directory. This field takes |
| precedence over any :variable:`CMAKE_TOOLCHAIN_FILE` value. |
| graphviz: |
| since: 10 |
| type: string |
| description: |
| An optional string specifying the path to the graphviz dot file. |
| sphinxDescription: | |
| An optional string representing the path to the graphviz input |
| file, that will contain all the library and executable dependencies |
| in the project. See the documentation for |
| :option:`cmake --graphviz` for more details. |
| |
| This field supports `macro expansion`_. If a relative path is |
| specified, it is calculated relative to the current working |
| directory. |
| binaryDir: |
| revisions: |
| - until: 3 |
| type: string |
| description: |
| 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). |
| - since: 3 |
| type: string |
| description: |
| 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, the path is |
| calculated using regular methods. |
| sphinxDescription: | |
| 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. |
| |
| .. presets-versionchanged:: 3 |
| |
| If omitted, CMake will calculate the path using regular methods. |
| In previous versions, if not specified, this field must be |
| inherited from the ``inherits`` preset (unless this preset is |
| ``hidden``). |
| installDir: |
| since: 3 |
| type: string |
| description: |
| An optional string representing the path to the installation |
| directory, which will be used as the CMAKE_INSTALL_PREFIX variable. |
| This field supports macro expansion. If a relative path is |
| specified, it is calculated relative to the source directory. |
| sphinxDescription: | |
| An optional string representing the path to the installation |
| directory, which will be used as the |
| :variable:`CMAKE_INSTALL_PREFIX` variable. This field supports |
| `macro expansion`_. If a relative path is specified, it is |
| calculated relative to the source directory. |
| cmakeExecutable: |
| type: string |
| description: |
| 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: |
| type: object |
| description: |
| An optional map of cache variables. The key is the variable name |
| (which must not be an empty string). 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. |
| sphinxDescription: | |
| 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. |
| properties: {} |
| propertyNames: |
| pattern: '^.+$' |
| additionalProperties: |
| anyOf: |
| - type: 'null' |
| description: |
| Setting a variable to null causes it to not be set, even if a |
| value was inherited from another preset. |
| - type: boolean |
| description: |
| A boolean representing the value of the variable. Equivalent |
| to "TRUE" or "FALSE" |
| - type: string |
| description: |
| A string representing the value of the variable (which |
| supports macro expansion). |
| - type: object |
| description: |
| An optional object representing the cache variables for |
| generators that support it. |
| properties: |
| type: |
| type: string |
| enum: |
| - BOOL |
| - FILEPATH |
| - PATH |
| - STRING |
| - INTERNAL |
| description: |
| An optional string representing the type of the variable. |
| It should be BOOL, FILEPATH, PATH, STRING, or INTERNAL. |
| value: |
| required: true |
| anyOf: |
| - type: boolean |
| description: |
| A boolean representing the value of the variable. |
| Equivalent to "TRUE" or "FALSE". |
| - type: string |
| description: |
| A string representing the value of the variable |
| (which supports macro expansion). |
| unevaluatedProperties: false |
| environment: *preset-environment |
| warnings: |
| type: object |
| description: |
| An optional object specifying the warnings to enable. |
| sphinxDescription: | |
| An optional object specifying the warnings to enable. |
| The object may contain the following fields: |
| |
| .. include:: presets/warnings-properties.rst |
| properties: |
| # This should ONLY have diagnostics whose definitions require |
| # special handling (i.e. anything from preset version < 12). Others |
| # will be generated from cmDiagnostics.h. |
| deprecated: |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| An optional boolean. Equivalent to passing |
| :option:`-Wdeprecated <cmake -W>` or |
| :option:`-Wno-deprecated <cmake -Wno->` |
| on the command line. |
| This may not be set to ``false`` |
| if ``errors.deprecated`` is set to ``true``. |
| dev: |
| until: 12 |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| An optional boolean. Equivalent to passing |
| :option:`-Wdev <cmake -W>` or |
| :option:`-Wno-dev <cmake -Wno->` |
| on the command line. |
| This may not be set to ``false`` |
| if ``errors.dev`` is set to ``true``. |
| uninitialized: |
| type: boolean |
| description: |
| An optional boolean. Equivalent to passing -Wuninitialized or |
| -Wno-uninitialized on the command line. This may not be set |
| to false if errors.uninitialized is set to true. |
| sphinxDescription: | |
| An optional boolean. Equivalent to passing |
| :option:`-Wuninitialized <cmake -W>` or |
| :option:`-Wno-uninitialized <cmake -Wno->` |
| on the command line. |
| This may not be set to ``false`` |
| if ``errors.uninitialized`` is set to ``true``. |
| unusedCli: |
| type: boolean |
| description: |
| An optional boolean. Equivalent to passing -Wunused-cli or |
| -Wno-unused-cli on the command line. This may not be set |
| to false if errors.unusedCli is set to true. |
| sphinxDescription: | |
| An optional boolean. Equivalent to passing |
| :option:`-Wunused-cli <cmake -W>` or |
| :option:`-Wno-unused-cli <cmake -Wno->` |
| on the command line. |
| This may not be set to ``false`` |
| if ``errors.unusedCli`` is set to ``true``. |
| systemVars: |
| sort: false |
| type: boolean |
| description: |
| An optional boolean. Setting this to true is equivalent to |
| passing --check-system-vars on the command line. |
| sphinxDescription: | |
| An optional boolean. Setting this to ``true`` is equivalent to |
| passing :cmake-option:`--check-system-vars` on the command |
| line. |
| unevaluatedProperties: false |
| errors: |
| type: object |
| description: |
| An optional object specifying the errors to enable. |
| sphinxDescription: | |
| An optional object specifying the errors to enable. |
| The object may contain the following fields: |
| |
| .. include:: presets/errors-properties.rst |
| properties: |
| # This should ONLY have diagnostics whose definitions require |
| # special handling (i.e. anything from preset version < 12). Others |
| # will be generated from cmDiagnostics.h. |
| deprecated: |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| An optional boolean. Equivalent to passing |
| :cmake-option:`-Werror=deprecated` or |
| :cmake-option:`-Wno-error=deprecated` |
| on the command line. |
| This may not be set to ``true`` |
| if ``warnings.deprecated`` is set to ``false``. |
| dev: |
| until: 12 |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| An optional boolean. Equivalent to passing |
| :cmake-option:`-Werror=dev` or |
| :cmake-option:`-Wno-error=dev` |
| on the command line. |
| This may not be set to ``true`` |
| if ``warnings.dev`` is set to ``false``. |
| uninitialized: |
| since: 12 |
| type: boolean |
| description: |
| An optional boolean. Equivalent to passing |
| -Werror=uninitialized or -Wno-error=uninitialized |
| on the command line. This may not be set |
| to true if warnings.uninitialized is set to false. |
| sphinxDescription: | |
| An optional boolean. Equivalent to passing |
| :cmake-option:`-Werror=uninitialized` or |
| :cmake-option:`-Wno-error=uninitialized` |
| on the command line. |
| This may not be set to ``true`` |
| if ``warnings.uninitialized`` is set to ``false``. |
| unusedCli: |
| since: 12 |
| type: boolean |
| description: |
| An optional boolean. Equivalent to passing |
| -Werror=unused-cli or -Wno-error=unused-cli |
| on the command line. This may not be set |
| to true if warnings.unusedCli is set to false. |
| sphinxDescription: | |
| An optional boolean. Equivalent to passing |
| :cmake-option:`-Werror=unused-cli` or |
| :cmake-option:`-Wno-error=unused-cli` |
| on the command line. |
| This may not be set to ``true`` |
| if ``warnings.unusedCli`` is set to ``false``. |
| unevaluatedProperties: false |
| debug: |
| type: object |
| description: |
| An optional object specifying debug options. |
| sphinxDescription: | |
| An optional object specifying debug options. |
| The object may contain the following fields: |
| |
| .. include:: presets/debug-properties.rst |
| properties: |
| output: |
| type: boolean |
| description: |
| An optional boolean. Setting this to true is equivalent to |
| passing --debug-output on the command line. |
| sphinxDescription: | |
| An optional boolean. Setting this to ``true`` is equivalent to |
| passing :cmake-option:`--debug-output` on the command line. |
| tryCompile: |
| type: boolean |
| description: |
| An optional boolean. Setting this to true is equivalent to |
| passing --debug-trycompile on the command line. |
| sphinxDescription: | |
| An optional boolean. Setting this to ``true`` is equivalent to |
| passing :cmake-option:`--debug-trycompile` on the command line. |
| find: |
| type: boolean |
| description: |
| An optional boolean. Setting this to true is equivalent to |
| passing --debug-find on the command line. |
| sphinxDescription: | |
| An optional boolean. Setting this to ``true`` is equivalent to |
| passing :cmake-option:`--debug-find` on the command line. |
| unevaluatedProperties: false |
| trace: |
| since: 7 |
| type: object |
| description: |
| An optional object specifying trace options. |
| sphinxDescription: | |
| An optional object specifying trace options. |
| The object may contain the following fields: |
| |
| .. include:: presets/trace-properties.rst |
| properties: |
| mode: |
| type: string |
| enum: |
| - 'on' |
| - 'off' |
| - 'expand' |
| description: |
| An optional string that specifies the trace mode. |
| sphinxDescription: | |
| An optional string that specifies the trace mode. |
| Valid values are: |
| |
| ``on`` |
| Causes a trace of all calls made and from where to be |
| printed. Equivalent to passing :cmake-option:`--trace` |
| on the command line. |
| |
| ``off`` |
| A trace of all calls will not be printed. |
| |
| ``expand`` |
| Causes a trace with variables expanded of all calls made |
| and from where to be printed. Equivalent to passing |
| :cmake-option:`--trace-expand` on the command line. |
| format: |
| type: string |
| enum: |
| - human |
| - json-v1 |
| description: |
| An optional string that specifies the trace output format. |
| sphinxDescription: | |
| An optional string that specifies the format output of the |
| trace. Valid values are: |
| |
| ``human`` |
| Prints each trace line in a human-readable format. |
| This is the default format. Equivalent to passing |
| :cmake-option:`--trace-format=human` |
| on the command line. |
| |
| ``json-v1`` |
| Prints each line as a separate JSON document. Equivalent |
| to passing :cmake-option:`--trace-format=json-v1` |
| on the command line. |
| source: |
| anyOf: |
| - type: string |
| minLength: 1 |
| description: |
| An optional string representing the path to one source file |
| to be traced. |
| - type: array |
| description: |
| An optional array of strings representing the paths to source |
| files to be traced. |
| items: |
| type: string |
| minLength: 1 |
| description: |
| A string representing the path to one source file to be |
| traced. |
| sphinxDescription: | |
| An optional array of strings representing the paths of source |
| files to be traced. This field can also be a string, which is |
| equivalent to an array containing one string. Equivalent to |
| passing :cmake-option:`--trace-source` on the command line. |
| redirect: |
| type: string |
| description: |
| An optional string specifying a path to a trace output file. |
| sphinxDescription: | |
| An optional string specifying a path to a trace output file. |
| Equivalent to passing :cmake-option:`--trace-redirect` on the |
| command line. |
| unevaluatedProperties: false |
| unevaluatedProperties: false |
| buildPresets: |
| since: 2 |
| type: array |
| description: |
| An optional array of build preset objects. |
| sphinxDescription: | |
| An optional array of `Build Preset`_ objects. |
| items: |
| type: object |
| description: |
| A build preset object. |
| properties: |
| name: |
| type: string |
| required: true |
| minLength: 1 |
| description: |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the cmake --build --preset |
| 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, test, package, or workflow preset. |
| sphinxDescription: | |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the |
| :option:`cmake --build --preset <cmake--build --preset>` 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, test, package, or workflow preset. |
| hidden: |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| An optional boolean specifying whether or not a preset should be |
| hidden. If a preset is hidden, it cannot be used in the |
| :cmake-build-option:`--preset` argument and does not have to have a |
| valid :preset:`buildPresets.configurePreset`, even from |
| inheritance. ``hidden`` presets are intended to be used as a base |
| for other presets to inherit via the |
| :preset:`buildPresets.inherits` field. |
| inherits: *preset-inherits |
| condition: *condition |
| vendor: *preset-vendor |
| displayName: *preset-displayName |
| description: *preset-description |
| environment: |
| type: object |
| description: *environment-description |
| sphinxDescription: *environment-sphinx-description |
| sphinxNote: | |
| For a CMake project using :module:`ExternalProject` with a |
| configuration preset having environment variables needed in the |
| ExternalProject, use a build preset that inherits that |
| configuration preset or the ExternalProject will not have the |
| environment variables set in the configuration preset. Example: |
| suppose the host defaults to one compiler (say Clang) and the user |
| wishes to use another compiler (say GCC). Set configuration preset |
| environment variables :envvar:`CC` and :envvar:`CXX` and use a |
| build preset that inherits that configuration preset. Otherwise the |
| ExternalProject may use a different (system default) compiler than |
| the top-level CMake project. |
| properties: {} |
| additionalProperties: *environment-additional-properties |
| configurePreset: |
| type: string |
| minLength: 1 |
| description: |
| 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 tree directory is inferred from |
| the configure preset. |
| sphinxDescription: | |
| 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. |
| inheritConfigureEnvironment: |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| 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. |
| jobs: |
| type: integer |
| description: |
| An optional non-negative integer. Equivalent to passing --parallel |
| or -j on the command line. |
| sphinxDescription: | |
| An optional integer. Equivalent to passing |
| :cmake-build-option:`--parallel` or ``-j`` on the command line. |
| If the value is ``0``, it is equivalent to passing ``--parallel`` |
| with ``<jobs>`` omitted; alternatively, one can define the |
| environment variable :envvar:`CMAKE_BUILD_PARALLEL_LEVEL` as an |
| empty string using the ``environment`` field. |
| |
| .. versionchanged:: 4.3 |
| |
| This field does not accept negative integer values, regardless of |
| the version in the presets file. |
| minimum: 0 |
| targets: |
| anyOf: |
| - type: string |
| description: |
| An optional string. Equivalent to passing --target or -t on the |
| command line. Vendors may ignore the targets property or hide |
| build presets that explicitly specify targets. |
| - type: array |
| items: |
| type: string |
| description: |
| An optional 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. |
| sphinxDescription: | |
| An optional string or array of strings. Equivalent to passing |
| :cmake-build-option:`--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`_. |
| configuration: |
| type: string |
| description: |
| An optional string. Equivalent to passing --config on the command |
| line. |
| sphinxDescription: | |
| An optional string. Equivalent to passing |
| :cmake-build-option:`--config` on the command line. |
| cleanFirst: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing --clean-first |
| on the command line. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :cmake-build-option:`--clean-first` on the command line. |
| resolvePackageReferences: |
| since: 4 |
| type: string |
| enum: |
| - 'on' |
| - 'off' |
| - 'only' |
| description: |
| An optional string specifying the package resolve behavior. Valid |
| values are "on" (packages are resolved prior to the build), "off" |
| (packages are not resolved prior to the build), and "only" |
| (packages are resolved, but no build will be performed). |
| sphinxDescription: | |
| An optional string that specifies the package resolve mode. |
| |
| Package references are used to define dependencies to packages from |
| external package managers. Currently only NuGet in combination with |
| the :ref:`Visual Studio generators` is supported. If there are no |
| targets that define package references, this option does nothing. |
| Valid values are: |
| |
| ``on`` |
| Causes package references to be resolved before attempting a |
| build. |
| |
| ``off`` |
| Package references will not be resolved. Note that this may cause |
| errors in some build environments, such as .NET SDK style |
| projects. |
| |
| ``only`` |
| Only resolve package references, but do not perform a build. |
| |
| .. note:: |
| |
| The command line parameter |
| :cmake-build-option:`--resolve-package-references` |
| will take priority over this setting. If the command line |
| parameter is not provided and this setting is not specified, an |
| environment-specific cache variable will be evaluated to decide, |
| if package restoration should be performed. |
| |
| When using the :ref:`Visual Studio generators`, |
| package references are defined using the |
| :prop_tgt:`VS_PACKAGE_REFERENCES` property. Package references |
| are restored using NuGet. It can be disabled by setting the |
| :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` variable to ``OFF``. |
| This can also be done from within a configure preset. |
| verbose: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing --verbose on |
| the command line. |
| sphinxDescription: | |
| An optional boolean. If ``true``, equivalent to passing |
| :cmake-build-option:`--verbose` on the command line. |
| nativeToolOptions: |
| type: array |
| items: |
| type: string |
| description: |
| An optional array of strings. Equivalent to passing options after |
| -- on the command line. |
| sphinxDescription: | |
| An optional array of strings. Equivalent to passing options after |
| :cmake-build-option:`--` on the command line. The array values |
| support `macro expansion`_. |
| unevaluatedProperties: false |
| testPresets: |
| since: 2 |
| type: array |
| description: |
| An optional array of test preset objects. Used to specify arguments to |
| ctest. |
| sphinxDescription: | |
| An optional array of `Test Preset`_ objects. |
| items: |
| type: object |
| description: |
| A test preset object. |
| properties: |
| name: |
| type: string |
| required: true |
| minLength: 1 |
| description: |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the ctest --preset 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, |
| build, package, or workflow preset. |
| sphinxDescription: | |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the :option:`ctest --preset` |
| 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, build, package, or workflow preset. |
| hidden: |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| An optional boolean specifying whether or not a preset should be |
| hidden. If a preset is hidden, it cannot be used in the |
| :ctest-option:`--preset` argument and does not have to have a valid |
| :preset:`testPresets.configurePreset`, even from |
| inheritance. ``hidden`` presets are intended to be used as a base |
| for other presets to inherit via the |
| :preset:`testPresets.inherits` field. |
| inherits: *preset-inherits |
| condition: *condition |
| vendor: *preset-vendor |
| displayName: *preset-displayName |
| description: *preset-description |
| environment: *preset-environment |
| configurePreset: |
| type: string |
| minLength: 1 |
| description: |
| 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. |
| sphinxDescription: | |
| 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 and build used. |
| inheritConfigureEnvironment: |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| 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: |
| type: string |
| description: |
| An optional string. Equivalent to passing --build-config on the |
| command line. |
| sphinxDescription: | |
| An optional string. Equivalent to passing |
| :ctest-option:`--build-config` on the command line. |
| overwriteConfigurationFile: |
| type: array |
| description: |
| 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. |
| sphinxDescription: | |
| An optional array of configuration options to overwrite options |
| specified in the CTest configuration file. Equivalent to passing |
| :ctest-option:`--overwrite` for each value in the array. The array |
| values support `macro expansion`_. |
| items: |
| type: string |
| description: |
| An option written as a key-value pair in the form "key=value". |
| output: |
| id: testOutput |
| type: object |
| description: |
| An optional object specifying output options. |
| sphinxDescription: | |
| An optional object specifying output options. |
| The object may contain the following fields: |
| |
| .. include:: presets/testOutput-properties.rst |
| properties: |
| shortProgress: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing --progress |
| on the command line. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :ctest-option:`--progress` on the command line. |
| verbosity: |
| type: string |
| enum: |
| - default |
| - verbose |
| - extra |
| description: ' |
| An optional string specifying verbosity level. Valid values are |
| "default" (equivalent to passing no verbosity flags on the |
| command line), "verbose" (equivalent to passing --verbose on |
| the command line), and "extra" (equivalent to passing |
| --extra-verbose on the command line). |
| ' |
| sphinxDescription: | |
| 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 :ctest-option:`--verbose` on the |
| command line. |
| |
| ``extra`` |
| Equivalent to passing :ctest-option:`--extra-verbose` on the |
| command line. |
| debug: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing --debug on |
| the command line. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :ctest-option:`--debug` on the command line. |
| outputOnFailure: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing |
| --output-on-failure on the command line. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :ctest-option:`--output-on-failure` on the command line. |
| quiet: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing --quiet on |
| the command line. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :ctest-option:`--quiet` on the command line. |
| outputLogFile: |
| type: string |
| description: |
| An optional string specifying a path to a log file. Equivalent |
| to passing --output-log on the command line. |
| sphinxDescription: | |
| An optional string specifying a path to a log file. Equivalent |
| to passing :ctest-option:`--output-log` on the command line. |
| This field supports `macro expansion`_. |
| outputJUnitFile: |
| since: 6 |
| type: string |
| description: |
| An optional string specifying a path to a JUnit file. |
| Equivalent to passing --output-junit on the command line. |
| sphinxDescription: | |
| An optional string specifying a path to a JUnit file. |
| Equivalent to passing :ctest-option:`--output-junit` on the |
| command line. This field supports `macro expansion`_. |
| labelSummary: |
| type: boolean |
| description: |
| An optional boolean. If false, equivalent to passing |
| --no-label-summary on the command line. |
| sphinxDescription: | |
| An optional bool. If ``false``, equivalent to passing |
| :ctest-option:`--no-label-summary` on the command line. |
| subprojectSummary: |
| type: boolean |
| description: |
| An optional boolean. If false, equivalent to passing |
| --no-subproject-summary on the command line. |
| sphinxDescription: | |
| An optional bool. If ``false``, equivalent to passing |
| :ctest-option:`--no-subproject-summary` on the command line. |
| maxPassedTestOutputSize: |
| type: integer |
| description: |
| An optional integer specifying the maximum output for passed |
| tests in bytes. Equivalent to passing --test-output-size-passed |
| on the command line. |
| sphinxDescription: | |
| An optional integer specifying the maximum output for passed |
| tests in bytes. Equivalent to passing |
| :ctest-option:`--test-output-size-passed` on the command line. |
| maxFailedTestOutputSize: |
| type: integer |
| description: |
| An optional integer specifying the maximum output for failed |
| tests in bytes. Equivalent to passing --test-output-size-failed |
| on the command line. |
| sphinxDescription: | |
| An optional integer specifying the maximum output for failed |
| tests in bytes. Equivalent to passing |
| :ctest-option:`--test-output-size-failed` on the command line. |
| testOutputTruncation: |
| since: 5 |
| type: string |
| enum: |
| - tail |
| - middle |
| - head |
| description: ' |
| An optional string specifying the test output truncation mode. |
| Equivalent to passing --test-output-truncation on the command |
| line. Must be one of the following values: "tail", "middle", or |
| "head". |
| ' |
| sphinxDescription: | |
| An optional string specifying the test output truncation mode. |
| Equivalent to passing :ctest-option:`--test-output-truncation` |
| on the command line. Must be one of the following values: |
| |
| * ``tail`` |
| |
| * ``middle`` |
| |
| * ``head`` |
| maxTestNameWidth: |
| type: integer |
| description: |
| An optional integer specifying the maximum width of a test name |
| to output. Equivalent to passing --max-width on the command |
| line. |
| sphinxDescription: | |
| An optional integer specifying the maximum width of a test name |
| to output. Equivalent to passing :ctest-option:`--max-width` on |
| the command line. |
| unevaluatedProperties: false |
| filter: |
| type: object |
| description: |
| An optional object specifying how to filter the tests to run. |
| sphinxDescription: | |
| An optional object specifying how to filter the tests to run. |
| The object may contain the following fields: |
| |
| .. include:: presets/filter-properties.rst |
| properties: |
| include: |
| type: object |
| description: |
| An optional object specifying which tests to include. |
| sphinxDescription: | |
| An optional object specifying which tests to include. |
| The object may contain the following fields: |
| |
| .. include:: presets/include-properties.rst |
| properties: |
| name: |
| type: string |
| description: |
| An optional string specifying a regex for test names. |
| Equivalent to passing --tests-regex on the command line. |
| sphinxDescription: | |
| An optional string specifying a regex for test names. |
| Equivalent to passing :ctest-option:`--tests-regex` on the |
| command line. This field supports `macro expansion`_. |
| |
| CMake regex syntax is described under |
| :ref:`string(REGEX) <Regex Specification>`. |
| label: |
| type: string |
| description: |
| An optional string specifying a regex for test labels. |
| Equivalent to passing --label-regex on the command line. |
| sphinxDescription: | |
| An optional string specifying a regex for test labels. |
| Equivalent to passing :ctest-option:`--label-regex` on the |
| command line. This field supports `macro expansion`_. |
| useUnion: |
| type: boolean |
| description: |
| An optional boolean. Equivalent to passing --union on the |
| command line. |
| sphinxDescription: | |
| An optional bool. Equivalent to passing |
| :ctest-option:`--union` on the command line. |
| index: |
| anyOf: |
| - type: string |
| description: |
| An optional string specifying a file with the command |
| line syntax for --tests-information. Available in |
| version 2 and higher. |
| - type: object |
| description: |
| An optional object specifying test preset filters. |
| Available in version 2 and higher. |
| properties: |
| start: |
| type: integer |
| description: |
| An optional integer specifying a test index at |
| which to start testing. |
| end: |
| type: integer |
| description: |
| An optional integer specifying a test index at |
| which to stop testing. |
| stride: |
| type: integer |
| description: |
| An optional integer specifying the increment. |
| specificTests: |
| type: array |
| description: |
| An optional array of integers specifying specific |
| test indices to run. |
| items: |
| type: integer |
| description: |
| An integer specifying the test to run by index. |
| unevaluatedProperties: false |
| sphinxDescription: | |
| 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 |
| :ctest-option:`--tests-information`. If specified as a |
| string, this field supports `macro expansion`_. |
| |
| .. include:: presets/index-properties.rst |
| exclude: |
| type: object |
| description: |
| An optional object specifying which tests to exclude. |
| sphinxDescription: | |
| An optional object specifying which tests to exclude. |
| The object may contain the following fields: |
| |
| .. include:: presets/exclude-properties.rst |
| properties: |
| name: |
| type: string |
| description: |
| An optional string specifying a regex for test names. |
| Equivalent to passing --exclude-regex on the command line. |
| sphinxDescription: | |
| An optional string specifying a regex for test names. |
| Equivalent to passing :ctest-option:`--exclude-regex` on |
| the command line. This field supports `macro expansion`_. |
| label: |
| type: string |
| description: |
| An optional string specifying a regex for test labels. |
| Equivalent to passing --label-exclude on the command line. |
| sphinxDescription: | |
| An optional string specifying a regex for test labels. |
| Equivalent to passing :ctest-option:`--label-exclude` on |
| the command line. This field supports `macro expansion`_. |
| fixtures: |
| type: object |
| description: |
| An optional object specifying which fixtures to exclude |
| from adding tests. |
| sphinxDescription: | |
| An optional object specifying which fixtures to exclude |
| from adding tests. The object may contain the following |
| fields: |
| |
| .. include:: presets/fixtures-properties.rst |
| properties: |
| any: |
| type: string |
| description: |
| An optional string specifying a regex for text fixtures |
| to exclude from adding any tests. Equivalent to passing |
| --fixture-exclude-any on the command line. |
| sphinxDescription: | |
| An optional string specifying a regex for text fixtures |
| to exclude from adding any tests. Equivalent to passing |
| :ctest-option:`--fixture-exclude-any` on the command |
| line. This field supports `macro expansion`_. |
| setup: |
| type: string |
| description: |
| An optional string specifying a regex for text fixtures |
| to exclude from adding setup tests. Equivalent to |
| passing --fixture-exclude-setup on the command line. |
| sphinxDescription: | |
| An optional string specifying a regex for text fixtures |
| to exclude from adding setup tests. Equivalent to |
| passing :ctest-option:`--fixture-exclude-setup` on the |
| command line. This field supports `macro expansion`_. |
| cleanup: |
| type: string |
| description: |
| An optional string specifying a regex for text fixtures |
| to exclude from adding cleanup tests. Equivalent to |
| passing --fixture-exclude-cleanup on the command line. |
| sphinxDescription: | |
| An optional string specifying a regex for text fixtures |
| to exclude from adding cleanup tests. Equivalent to |
| passing :ctest-option:`--fixture-exclude-cleanup` on |
| the command line. |
| This field supports `macro expansion`_. |
| execution: |
| type: object |
| description: |
| An optional object specifying options for test execution. |
| sphinxDescription: | |
| An optional object specifying options for test execution. |
| The object may contain the following fields: |
| |
| .. include:: presets/execution-properties.rst |
| properties: |
| stopOnFailure: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing |
| --stop-on-failure on the command line. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :ctest-option:`--stop-on-failure` on the command line. |
| enableFailover: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing -F on the |
| command line. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :ctest-option:`-F` on the command line. |
| jobs: |
| revisions: |
| - until: 11 |
| type: integer |
| minimum: 0 |
| description: |
| An optional non-negative integer. Equivalent to passing |
| --parallel or -j on the command line. |
| - since: 11 |
| anyOf: |
| - type: integer |
| minimum: 0 |
| description: |
| An optional non-negative integer. Equivalent to passing |
| --parallel or -j on the command line. |
| - type: string |
| minLength: 0 |
| maxLength: 0 |
| description: |
| An optional string. Equivalent to passing --parallel or |
| -j on the command line with the number of jobs omitted. |
| sphinxDescription: | |
| An optional integer. Equivalent to passing |
| :ctest-option:`--parallel` on the command line. If the value is |
| ``0``, it is equivalent to unbounded parallelism. |
| |
| .. presets-versionchanged:: 11 |
| |
| This field can also be a string, in which case it must be |
| empty, and is equivalent to passing ``--parallel`` with |
| ``<jobs>`` omitted. |
| |
| .. versionchanged:: 4.3 |
| |
| This field does not accept negative integer values, |
| regardless of the version in the presets file. |
| minimum: 0 |
| resourceSpecFile: |
| type: string |
| description: |
| An optional string. Equivalent to passing --resource-spec-file |
| on the command line. |
| sphinxDescription: | |
| An optional string. Equivalent to passing |
| :ctest-option:`--resource-spec-file` on the command line. This |
| field supports `macro expansion`_. |
| testLoad: |
| type: integer |
| description: |
| An optional integer. Equivalent to passing --test-load on the |
| command line. |
| sphinxDescription: | |
| An optional integer. Equivalent to passing |
| :ctest-option:`--test-load` on the command line. |
| showOnly: |
| type: string |
| enum: |
| - human |
| - json-v1 |
| description: |
| An optional string. Equivalent to passing --show-only on the |
| command line. Value must be "human" or "json-v1". |
| sphinxDescription: | |
| An optional string. Equivalent to passing |
| :ctest-option:`--show-only` on the command line. The string |
| must be one of the following values: |
| |
| * ``human`` |
| |
| * ``json-v1`` |
| repeat: |
| type: object |
| description: |
| An optional object specifying how to repeat tests. Equivalent |
| to passing --repeat on the command line. |
| sphinxDescription: | |
| An optional object specifying how to repeat tests. Equivalent |
| to passing :ctest-option:`--repeat` on the command line. |
| The object must have the following fields: |
| |
| .. include:: presets/repeat-properties.rst |
| properties: |
| mode: |
| type: string |
| required: true |
| enum: |
| - until-fail |
| - until-pass |
| - after-timeout |
| description: ' |
| A required string. Must be one of the following values: |
| "until-fail", "until-pass", or "after-timeout". |
| ' |
| sphinxDescription: | |
| A required string. Must be one of the following values: |
| |
| * ``until-fail`` |
| |
| * ``until-pass`` |
| |
| * ``after-timeout`` |
| count: |
| type: integer |
| required: true |
| description: |
| A required integer. |
| unevaluatedProperties: false |
| interactiveDebugging: |
| type: boolean |
| description: |
| An optional boolean. 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. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :ctest-option:`--interactive-debug-mode 1` on the command line. |
| If ``false``, equivalent to passing |
| :ctest-option:`--interactive-debug-mode 0` on the command line. |
| scheduleRandom: |
| type: boolean |
| description: |
| An optional boolean. If true, equivalent to passing |
| --schedule-random on the command line. |
| sphinxDescription: | |
| An optional bool. If ``true``, equivalent to passing |
| :ctest-option:`--schedule-random` on the command line. |
| timeout: |
| type: integer |
| description: |
| An optional integer. Equivalent to passing --timeout on the |
| command line. |
| sphinxDescription: | |
| An optional integer. Equivalent to passing |
| :ctest-option:`--timeout` on the command line. |
| noTestsAction: |
| type: string |
| enum: |
| - default |
| - error |
| - ignore |
| description: ' |
| An optional string specifying the behavior if no tests are |
| found. Must be one of the following values: "default" |
| (equivalent to not passing any value on the command line), |
| "error" (equivalent to passing --no-tests=error on the command |
| line), or "ignore" (equivalent to passing --no-tests-ignore on |
| the command line). |
| ' |
| sphinxDescription: | |
| An optional string specifying the behavior if no tests are |
| found. Must be one of the following values: |
| |
| ``default`` |
| Equivalent to not passing any value on the command line. |
| |
| ``error`` |
| Equivalent to passing :ctest-option:`--no-tests=error` |
| on the command line. |
| |
| ``ignore`` |
| Equivalent to passing :ctest-option:`--no-tests=ignore` |
| on the command line. |
| testPassthroughArguments: |
| since: 12 |
| type: array |
| items: |
| type: string |
| description: |
| An optional array of strings. Each element is forwarded as an |
| argument to every test executable. Equivalent to passing |
| arguments after -- on the ctest command line. |
| sphinxDescription: | |
| An optional array of strings. Each element is forwarded as an |
| argument to every test executable, equivalent to passing |
| arguments after :option:`ctest --` on the command line. |
| |
| When both preset and command-line passthrough arguments are |
| specified, preset arguments appear first, followed by |
| command-line arguments. |
| unevaluatedProperties: false |
| unevaluatedProperties: false |
| packagePresets: |
| since: 6 |
| type: array |
| description: |
| An optional array of package preset objects. Used to specify arguments to |
| cpack. |
| sphinxDescription: | |
| An optional array of `Package Preset`_ objects. |
| items: |
| type: object |
| description: |
| A package preset object. |
| properties: |
| name: |
| type: string |
| required: true |
| minLength: 1 |
| description: |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the cpack --preset option. There |
| must not be two package presets in the union of CMakePresets.json |
| and CMakeUserPresets.json in the same directory with the same name. |
| However, a package preset may have the same name as a configure, |
| build, test, or workflow preset. |
| sphinxDescription: | |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the :option:`cpack --preset` |
| option. There must not be two package presets in the union of |
| ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same |
| directory with the same name. However, a package preset may have |
| the same name as a configure, build, test, or workflow preset. |
| hidden: |
| type: boolean |
| description: |
| 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. |
| sphinxDescription: | |
| An optional boolean specifying whether or not a preset should be |
| hidden. If a preset is hidden, it cannot be used in the |
| :cpack-option:`--preset` argument and does not have to have a valid |
| :preset:`packagePresets.configurePreset`, even from |
| inheritance. ``hidden`` presets are intended to be used as a base |
| for other presets to inherit via the |
| :preset:`packagePresets.inherits` field. |
| inherits: *preset-inherits |
| condition: *condition |
| vendor: *preset-vendor |
| displayName: *preset-displayName |
| description: *preset-description |
| environment: *preset-environment |
| configurePreset: |
| type: string |
| minLength: 1 |
| description: |
| An optional string specifying the name of a configure preset to |
| associate with this package preset. If configurePreset is not |
| specified, it must be inherited from the inherits preset (unless |
| this preset is hidden). The build tree directory is inferred from |
| the configure preset. |
| sphinxDescription: | |
| An optional string specifying the name of a configure preset to |
| associate with this package 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 packaging will run in the same ``binaryDir`` |
| that the configuration did and build did. |
| inheritConfigureEnvironment: |
| type: boolean |
| description: |
| An optional boolean that defaults to true. If true, the environment |
| variables from the associated configure preset are inherited after |
| all inherited package preset environments, but before environment |
| variables explicitly specified in this package preset. |
| sphinxDescription: | |
| An optional boolean that defaults to ``true``. If ``true``, the |
| environment variables from the associated configure preset are |
| inherited after all inherited package preset environments, but |
| before environment variables explicitly specified in this package |
| preset. |
| generators: |
| type: array |
| description: |
| An optional array of strings representing generators for CPack to |
| use. |
| items: |
| type: string |
| description: |
| An optional string representing the name of a CPack generator |
| to use. |
| configurations: |
| type: array |
| description: |
| An optional array of strings representing build configurations for |
| CPack to package. |
| items: |
| type: string |
| description: |
| An optional string representing the name of a configuration to |
| package. |
| variables: |
| type: object |
| description: |
| An optional map of variables to pass to CPack, equivalent to -D |
| arguments. Each key is the name of a variable, and the value is the |
| string to assign to that variable. |
| sphinxDescription: | |
| An optional map of variables to pass to CPack, equivalent to |
| :cpack-option:`-D` arguments. Each key is the name of a variable, |
| and the value is the string to assign to that variable. |
| properties: {} |
| propertyNames: |
| pattern: '^.+$' |
| additionalProperties: |
| type: string |
| description: |
| An optional string representing the value of the variable. |
| configFile: |
| type: string |
| description: |
| An optional string representing the config file for CPack to use. |
| output: |
| id: packageOutput |
| type: object |
| description: |
| An optional object specifying output options. |
| sphinxDescription: | |
| An optional object specifying output options. Valid keys are: |
| |
| .. include:: presets/packageOutput-properties.rst |
| properties: |
| debug: |
| type: boolean |
| description: |
| An optional boolean specifying whether or not to print debug |
| information. A value of true is equivalent to passing --debug |
| on the command line. |
| sphinxDescription: | |
| An optional boolean specifying whether or not to print debug |
| information. A value of ``true`` is equivalent to passing |
| :cpack-option:`--debug` on the command line. |
| verbose: |
| type: boolean |
| description: |
| An optional boolean specifying whether or not to print |
| verbosely. A value of true is equivalent to passing --verbose |
| on the command line. |
| sphinxDescription: | |
| An optional boolean specifying whether or not to print |
| verbosely. A value of ``true`` is equivalent to passing |
| :cpack-option:`--verbose` on the command line. |
| unevaluatedProperties: false |
| packageName: |
| type: string |
| description: |
| An optional string representing the package name. |
| sphinxNote: &package-naming-note | |
| Due to problems with the implementation, this field does not affect |
| the name of the final package file produced. However, other aspects |
| of the package may use the value, leading to inconsistencies. A |
| future CMake release may address this problem, but until then, it |
| is recommended that this field not be used. |
| packageVersion: |
| type: string |
| description: |
| An optional string representing the package version. |
| sphinxNote: *package-naming-note |
| packageDirectory: |
| type: string |
| description: |
| An optional string representing the directory in which to place the |
| package. |
| vendorName: |
| type: string |
| description: |
| An optional string representing the vendor name. |
| unevaluatedProperties: false |
| workflowPresets: |
| since: 6 |
| type: array |
| description: |
| An optional array of workflow preset objects. Used to execute configure, |
| build, test, and package presets in order. |
| sphinxDescription: | |
| An optional array of `Workflow Preset`_ objects. |
| items: |
| type: object |
| description: |
| A workflow preset object. |
| properties: |
| name: |
| type: string |
| required: true |
| minLength: 1 |
| description: |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the cmake --workflow --preset |
| option. There must not be two presets (configure, build, test, |
| package, or workflow) in the union of CMakePresets.json and |
| CMakeUserPresets.json in the same directory with the same name. |
| However, a workflow preset may have the same name as a configure, |
| build, test, or package preset. |
| sphinxDescription: | |
| A required string representing the machine-friendly name of the |
| preset. This identifier is used in the |
| :option:`cmake --workflow --preset <cmake--workflow --preset>` |
| option. There must not be two workflow presets in the union of |
| ``CMakePresets.json`` and ``CMakeUserPresets.json`` in the same |
| directory with the same name. However, a workflow preset may have |
| the same name as a configure, build, test, or package preset. |
| vendor: *preset-vendor |
| displayName: *preset-displayName |
| description: *preset-description |
| steps: |
| type: array |
| required: true |
| description: |
| A required array of objects describing the steps of the workflow. |
| The first step must be a configure preset, and all subsequent steps |
| must be non-configure presets whose configurePreset field matches |
| the starting configure preset. |
| sphinxDescription: | |
| A required array of objects describing the steps of the workflow. |
| The first step must be a configure preset, and all subsequent steps |
| must be non-configure presets whose ``configurePreset`` field |
| matches the starting configure preset. Each object may contain the |
| following fields: |
| |
| .. include:: presets/steps-properties.rst |
| items: |
| type: object |
| properties: |
| type: |
| type: string |
| enum: |
| - configure |
| - build |
| - test |
| - package |
| description: |
| A required string. The first step must be configure. |
| Subsequent steps must be either build, test, or package. |
| sphinxDescription: | |
| A required string. The first step must be ``configure``. |
| Subsequent steps must be either ``build``, ``test``, or |
| ``package``. |
| name: |
| type: string |
| minLength: 1 |
| description: |
| A required string representing the name of the configure, |
| build, test, or package preset to run as this workflow step. |
| unevaluatedProperties: false |
| unevaluatedProperties: false |
| additionalProperties: false |
