diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst index 02195e1929..3a8618e114 100644 --- a/Help/manual/cmake-presets.7.rst +++ b/Help/manual/cmake-presets.7.rst @@ -44,6 +44,8 @@ key ``$comment`` at any level within the JSON object to provide documentation. The root object recognizes the following fields: +.. _`CMakePresets schema`: + ``$schema`` 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 @@ -51,41 +53,11 @@ The root object recognizes the following fields: 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. - This is allowed in preset files specifying version ``8`` or above. ``version`` - A required integer representing the version of the JSON schema. - The supported versions are: - - ``1`` - .. versionadded:: 3.19 - - ``2`` - .. versionadded:: 3.20 - - ``3`` - .. versionadded:: 3.21 - - ``4`` - .. versionadded:: 3.23 - - ``5`` - .. versionadded:: 3.24 - - ``6`` - .. versionadded:: 3.25 - - ``7`` - .. versionadded:: 3.27 - - ``8`` - .. versionadded:: 3.28 - - ``9`` - .. versionadded:: 3.30 - - ``10`` - .. versionadded:: 3.31 + 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`` An optional object representing the minimum version of CMake needed to @@ -217,6 +189,8 @@ that may contain the following fields: ``description`` An optional string with a human-friendly description of the preset. +.. _`CMakePresets generator`: + ``generator`` An optional string representing the generator to use for the preset. If ``generator`` is not specified, it must be inherited from the @@ -259,6 +233,8 @@ that may contain the following fields: 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"``. +.. _`CMakePresets toolchainFile`: + ``toolchainFile`` An optional string representing the path to the toolchain file. This field supports `macro expansion`_. If a relative path is specified, @@ -267,6 +243,8 @@ that may contain the following fields: :variable:`CMAKE_TOOLCHAIN_FILE` value. It is allowed in preset files specifying version ``3`` or above. +.. _`CMakePresets graphviz`: + ``graphviz`` An optional string representing the path to the graphviz input file, that will contain all the library and executable dependencies @@ -277,6 +255,8 @@ that may contain the following fields: it is calculated relative to the current working directory. It is allowed in preset files specifying version ``10`` or above. +.. _`CMakePresets binaryDir`: + ``binaryDir`` An optional string representing the path to the output binary directory. This field supports `macro expansion`_. If a relative path is specified, @@ -406,6 +386,8 @@ that may contain the following fields: An optional boolean. Setting this to ``true`` is equivalent to passing :option:`--debug-find ` on the command line. +.. _`CMakePresets trace`: + ``trace`` An optional object specifying trace options. This is allowed in preset files specifying version ``7``. The object may contain the following fields: @@ -576,6 +558,8 @@ that may contain the following fields: An optional bool. If true, equivalent to passing :option:`--clean-first ` on the command line. +.. _`CMakePresets resolvePackageReferences`: + ``resolvePackageReferences`` An optional string that specifies the package resolve mode. This is allowed in preset files specifying version ``4`` or above. @@ -720,6 +704,8 @@ that may contain the following fields: :option:`--overwrite ` for each value in the array. The array values support macro expansion. +.. _`CMakePresets output`: + ``output`` An optional object specifying output options. The object may contain the following fields. @@ -761,6 +747,8 @@ that may contain the following fields: passing :option:`--output-log ` on the command line. This field supports macro expansion. +.. _`CMakePresets outputJUnitFile`: + ``outputJUnitFile`` An optional string specifying a path to a JUnit file. Equivalent to passing :option:`--output-junit ` on the command line. @@ -789,6 +777,8 @@ that may contain the following fields: :option:`--test-output-size-failed ` on the command line. +.. _`CMakePresets testOutputTruncation`: + ``testOutputTruncation`` An optional string specifying the test output truncation mode. Equivalent to passing @@ -1278,11 +1268,15 @@ Recognized macros include: This is a preset-specific macro. +.. _`CMakePresets hostSystemName`: + ``${hostSystemName}`` The name of the host operating system. Contains the same value as :variable:`CMAKE_HOST_SYSTEM_NAME`. This is allowed in preset files specifying version ``3`` or above. +.. _`CMakePresets fileDir`: + ``${fileDir}`` Path to the directory containing the preset file which contains the macro. This is allowed in preset files specifying version ``4`` or above. @@ -1290,6 +1284,8 @@ Recognized macros include: ``${dollar}`` A literal dollar sign (``$``). +.. _`CMakePresets pathListSep`: + ``${pathListSep}`` Native character for separating lists of paths, such as ``:`` or ``;``. @@ -1333,6 +1329,114 @@ Recognized macros include: identifier prefix, followed by a ``.``, followed by the macro name. For example, the Example IDE could have ``$vendor{xide.ideInstallDir}``. +Versions +======== + +The JSON schema of ``CMakePresets.json`` and ``CMakeUserPresets.json`` +follows a version scheme where new versions are added and allowed in newer +versions of CMake. + +A list of the supported versions along with the version of CMake in which +they were added and a summary of the new features and changes is given below. + + ``1`` + .. versionadded:: 3.19 + + The initial version supports `Configure Presets `_ + and `Macro Expansion`_. + + ``2`` + .. versionadded:: 3.20 + + * `Build Presets `_ were added. + * `Test Presets `_ were added. + + ``3`` + .. versionadded:: 3.21 + + * The `Condition`_ object was added for `Configure `_, + `Build `_, and `Test Presets `_. + * Changes to `Configure Presets `_ + + * The `installDir `_ field was added. + * The `toolchainFile `_ field was added. + * The `binaryDir `_ field is now optional. + * The `generator `_ field is now optional. + + * Changes to `Macro Expansion`_ + + * The `${hostSystemName} `_ macro was + added. + + ``4`` + .. versionadded:: 3.23 + + * `Includes`_ were added to support including other JSON files in + ``CMakePresets.json`` and ``CMakeUserPresets.json``. + * Changes to `Build Presets `_ + + * The + `resolvePackageReferences `_ + field was added. + + * Changes to `Macro Expansion`_ + + * The `${fileDir} `_ macro was added. + + ``5`` + .. versionadded:: 3.24 + + * Changes to `Test Presets `_ + + * The `testOutputTruncation `_ + field was added to the `output `_ object. + + * Changes to `Macro Expansion`_ + + * The `${pathListSep} `_ macro was added. + + ``6`` + .. versionadded:: 3.25 + + * `Package Presets `_ were added. + * `Workflow Presets `_ were added. + * Changes to `Test Presets `_ + + * The `outputJUnitFile `_ field was added + to the `output `_ object. + + ``7`` + .. versionadded:: 3.27 + + * Changes to `Configure Presets `_ + + * The `trace `_ field was added. + + * Changes to `Includes`_ + + * The ``include`` field now supports ``$penv{}`` `macro expansion`_. + + ``8`` + .. versionadded:: 3.28 + + * The `$schema `_ field was added to the root object. + + ``9`` + .. versionadded:: 3.30 + + * Changes to `Includes`_ + + * The ``include`` field now supports other types of `macro expansion`_. + + ``10`` + .. versionadded:: 3.31 + + * The optional ``$comment`` field was added to support documentation + throughout ``CMakePresets.json`` and ``CMakeUserPresets.json``. + * Changes to `Configure Presets `_: + + * The `graphviz `_ field was added. + Schema ======