Merge topic 'doc-presets-v4' into release-3.23

6404751176 Help: Improve wording and structure related to preset includes

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !7028

2 files changed, 69 insertions, 43 deletions

diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index 69d0543..4620984 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -19,28 +19,16 @@ supports files included with the ``include`` field.
 
 ``CMakePresets.json`` and ``CMakeUserPresets.json`` live in the project's root
 directory. They both have exactly the same format, and both are optional
-(though at least one must be present if ``--preset`` is specified.)
-``CMakePresets.json`` is meant to save project-wide builds, while
-``CMakeUserPresets.json`` is meant for developers to save their own local
-builds. ``CMakePresets.json`` may be checked into a version control system, and
-``CMakeUserPresets.json`` should NOT be checked in. For example, if a project
-is using Git, ``CMakePresets.json`` may be tracked, and
+(though at least one must be present if ``--preset`` is specified).
+``CMakePresets.json`` is meant to specify project-wide build details, while
+``CMakeUserPresets.json`` is meant for developers to specify their own local
+build details.
+
+``CMakePresets.json`` may be checked into a version control system, and
+``CMakeUserPresets.json`` should NOT be checked in. For example, if a
+project is using Git, ``CMakePresets.json`` may be tracked, and
 ``CMakeUserPresets.json`` should be added to the ``.gitignore``.
 
-``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files
-with the ``include`` field in file version ``4`` and later. Files included by
-these files can also include other files. If a preset file contains presets
-that inherit from presets in another file, the file must include the other file
-either directly or indirectly. Include cycles are not allowed among files (if
-``a.json`` includes ``b.json``, ``b.json`` cannot include ``a.json``). However,
-a file may be included multiple times from the same file or from different
-files. If ``CMakePresets.json`` and ``CMakeUserPresets.json`` are both present,
-``CMakeUserPresets.json`` implicitly includes ``CMakePresets.json``, even with
-no ``include`` field, in all versions of the format. Files directly or
-indirectly included from ``CMakePresets.json`` should be guaranteed to be
-provided by the project. ``CMakeUserPresets.json`` may include files from
-anywhere.
-
 Format
 ======
 
@@ -73,6 +61,13 @@ The root object recognizes the following fields:
 
     An optional integer representing the patch version.
 
+``include``
+
+  An optional array of strings representing files to include. If the filenames
+  are not absolute, they are considered relative to the current file.
+  This is allowed in preset files specifying version ``4`` or above.
+  See `Includes`_ for discussion of the constraints on included files.
+
 ``vendor``
 
   An optional map containing vendor-specific information. CMake does not
@@ -97,11 +92,25 @@ The root object recognizes the following fields:
   An optional array of `Test Preset`_ objects.
   This is allowed in preset files specifying version ``2`` or above.
 
-``include``
+Includes
+^^^^^^^^
 
-  An optional array of strings representing files to include. If the filenames
-  are not absolute, they are considered relative to the current file.
-  This is allowed in preset files specifying version ``4`` or above.
+``CMakePresets.json`` and ``CMakeUserPresets.json`` can include other files
+with the ``include`` field in file version ``4`` and later. Files included
+by these files can also include other files. If ``CMakePresets.json`` and
+``CMakeUserPresets.json`` are both present, ``CMakeUserPresets.json``
+implicitly includes ``CMakePresets.json``, even with no ``include`` field,
+in all versions of the format.
+
+If a preset file contains presets that inherit from presets in another file,
+the file must include the other file either directly or indirectly.
+Include cycles are not allowed among files. If ``a.json`` includes
+``b.json``, ``b.json`` cannot include ``a.json``. However, a file may be
+included multiple times from the same file or from different files.
+
+Files directly or indirectly included from ``CMakePresets.json`` should be
+guaranteed to be provided by the project. ``CMakeUserPresets.json`` may
+include files from anywhere.
 
 Configure Preset
 ^^^^^^^^^^^^^^^^
@@ -129,16 +138,20 @@ that may contain the following fields:
 ``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``
+  from. 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`` list will be
-  preferred. Presets in ``CMakePresets.json`` may not inherit from presets
-  in ``CMakeUserPresets.json``.
+  preferred.
 
-  This field can also be a string, which is equivalent to an array
-  containing one string.
+  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``.
 
 ``condition``
 
@@ -371,17 +384,21 @@ that may contain the following fields:
 
 ``inherits``
 
-  An optional array of strings representing the names of presets to
-  inherit from. The preset will inherit all of the fields from the
+  An optional array of strings representing the names of presets to inherit
+  from. 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`` list
-  will be preferred. Presets in ``CMakePresets.json`` may not inherit from
-  presets in ``CMakeUserPresets.json``.
+  will be preferred.
 
-  This field can also be a string, which is equivalent to an array
-  containing one string.
+  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``.
 
 ``condition``
 
@@ -544,17 +561,21 @@ that may contain the following fields:
 
 ``inherits``
 
-  An optional array of strings representing the names of presets to
-  inherit from. The preset will inherit all of the fields from the
+  An optional array of strings representing the names of presets to inherit
+  from. 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`` list
-  will be preferred. Presets in ``CMakePresets.json`` may not inherit from
-  presets in ``CMakeUserPresets.json``.
+  will be preferred.
 
-  This field can also be a string, which is equivalent to an array
-  containing one string.
+  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``.
 
 ``condition``
 
@@ -1004,7 +1025,8 @@ Recognized macros include:
 
 ``${sourceDir}``
 
-  Path to the project source directory.
+  Path to the project source directory (i.e. the same as
+  :variable:`CMAKE_SOURCE_DIR`).
 
 ``${sourceParentDir}``
 
diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json
index a7ec10e..873c4ad 100644
--- a/Help/manual/presets/example.json
+++ b/Help/manual/presets/example.json
@@ -2,9 +2,13 @@
   "version": 4,
   "cmakeMinimumRequired": {
     "major": 3,
-    "minor": 21,
+    "minor": 23,
     "patch": 0
   },
+  "include": [
+    "otherThings.json",
+    "moreThings.json"
+  ],
   "configurePresets": [
     {
       "name": "default",