Help, Tests: Consolidate presets terminology and references

References to `CMake[User]Presets.json` should correspond to behavior pertaining to those files in particular, while references to presets files generally should be disambiguated from that. Re-spell "preset file" to "presets file" where applicable. Make a few references to `cmake-presets(7)` more consistent. Issue: #27329
2026-09-25 04:09:36 +03:00 · 2026-04-30 07:49:40 -04:00
parent c49ebb67da
commit 43f5fc8ac8
16 changed files with 54 additions and 52 deletions
@@ -40,7 +40,7 @@ CMake supports a file format called ``CMakePresets.json``, and its
 user-specific counterpart, ``CMakeUserPresets.json``. This file contains
 information on the various configure presets that a user may want. Each preset
 may have a different compiler, build flags, etc. The details of this format are
-explained in the :manual:`cmake(1)` manual.
+explained in the :manual:`cmake-presets(7)` manual.

 IDE vendors are encouraged to read and evaluate this file the same way CMake
 does, and present the user with the presets listed in the file. Users should be
@@ -71,12 +71,12 @@ them as :option:`-D <cmake -D>` flags would cause the command line length limit
 of the platform to be exceeded, the IDE should instead construct a temporary
 cache script and pass it with the :option:`-C <cmake -C>` flag.

-While reading, parsing, and evaluating the contents of ``CMakePresets.json`` is
+While reading, parsing, and evaluating the contents of CMake presets files is
 straightforward, it is not trivial. In addition to the documentation, IDE
 vendors may also wish to refer to the CMake source code and test cases for a
 better understanding of how to implement the format.
 :download:`This file <../../manual/presets/schema.json>` provides a
-machine-readable JSON schema for the ``CMakePresets.json`` format that IDE
+machine-readable JSON schema for the CMake presets file format that IDE
 vendors may find useful for validation and providing editing assistance.

 Configuring
@@ -557,7 +557,7 @@ All future configuration changes will be via the ``CMakePresets.json`` file.
 Build and Run
 -------------

-We can now use the preset file to manage our configuration.
+We can now use the presets file to manage our configuration.

 .. code-block:: console

@@ -425,7 +425,7 @@ saving presets for commonly-used configure settings. These
 presets can set the build directory, generator, cache
 variables, environment variables, and other command-line
 options. All of these options can be overridden by the
-user. The full details of the ``CMakePresets.json`` format
+user. The full details of the CMake preset format
 are listed in the :manual:`cmake-presets(7)` manual.

 Using presets on the command-line
@@ -1,4 +1,4 @@
-.. cmake-manual-description: CMakePresets.json
+.. cmake-manual-description: CMake Presets Reference

 cmake-presets(7)
 ****************
@@ -41,7 +41,7 @@ The files are a JSON document with an object as the root:

 .. presets-versionadded:: 10

-  Preset files may include comments using the key ``$comment`` at any level
+  Presets files may include comments using the key ``$comment`` at any level
  within the JSON object to provide documentation.

 The root object recognizes the following fields:
@@ -51,14 +51,13 @@ The root object recognizes the following fields:
 Includes
 ^^^^^^^^

-``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.
+CMake presets files 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,
+If a presets 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
@@ -268,12 +267,12 @@ Recognized macros include:
 ``${fileDir}``
  .. presets-versionadded:: 4

-  Path to the directory containing the preset file which defines the preset
+  Path to the directory containing the presets file which defines the preset
  being used.

  .. presets-versionchanged:: 12

-    This macro *always* expands to the directory of the current preset file
+    This macro *always* expands to the directory of the current presets file
    containing the macro, regardless of the preset being used.

    For example, consider the following scenario.
@@ -296,7 +295,7 @@ Recognized macros include:
    .. note::

      Since the ``${fileDir}`` macro in version 12 is expanded in the context
-      of the current preset file, it is the version of the current file, rather
+      of the current presets file, it is the version of the current file, rather
      than the version of the root file containing the preset being used, which
      enables this alternative behavior.

@@ -351,9 +350,8 @@ Recognized macros include:
 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.
+The JSON schema of CMake presets files 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.
@@ -477,7 +475,7 @@ they were added and a summary of the new features and changes is given below.
    * Changes to `Macro Expansion`_

      * The `${fileDir} <CMakePresets fileDir_>`_ macro now always expands to
-        the directory of preset file containing the ``${fileDir}`` macro,
+        the directory of presets file containing the ``${fileDir}`` macro,
        regardless of whether it is inherited by another preset in a different
        directory.

@@ -490,4 +488,4 @@ Schema
 ======

 :download:`This file </manual/presets/schema.json>` provides a machine-readable
-JSON schema for the ``CMakePresets.json`` format.
+JSON schema for the CMake presets file format.
@@ -716,8 +716,9 @@ Options
 Lists the available presets of the specified ``<type>``.  Valid values for
 ``<type>`` are ``configure``, ``build``, ``test``, ``package``, or ``all``.
 If ``<type>`` is omitted, ``configure`` is assumed.  The current working
- directory must contain CMake preset files unless the :cmake-option:`-S`
- option is used to specify a different top level source directory.
+ directory must contain ``CMakePresets.json`` and/or ``CMakeUserPresets.json``
+ unless the :cmake-option:`-S` option is used to specify a different top level
+ source directory.

 .. option:: --debugger

@@ -793,9 +794,9 @@ following options:

 .. option:: --preset <preset>, --preset=<preset>

-  Use a build preset to specify build options. The project binary directory
-  is inferred from the ``configurePreset`` key unless a directory is specified
-  after ``--build``.  See :manual:`preset <cmake-presets(7)>` for more details.
+  Use a build :manual:`preset <cmake-presets(7)>` to specify build options.
+  The project binary directory is inferred from the ``configurePreset`` key
+  unless a directory is specified after ``--build``.

  .. versionadded:: 4.3
    ``cmake --build`` now supports specifying a build directory and
@@ -803,7 +804,7 @@ following options:

  .. versionchanged:: 4.4
    ``cmake --build <dir> --preset`` no longer needs to be called from the
-    directory containing the CMake presets files.
+    directory containing ``CMakePresets.json`` or ``CMakeUserPresets.json``.

 .. option:: --list-presets

@@ -811,7 +812,7 @@ following options:

  .. versionchanged:: 4.4
    ``cmake --build <dir> --list-presets`` no longer needs to be called from
-    the directory containing the CMake presets files.
+    the directory containing ``CMakePresets.json`` or ``CMakeUserPresets.json``.

 .. option:: -j [<jobs>], --parallel [<jobs>]

@@ -1909,10 +1910,9 @@ The options are:

 .. option:: --preset <preset>, --preset=<preset>

-  Use a workflow preset to specify a workflow. The project binary directory
-  is inferred from the initial configure preset. The current working directory
-  must contain CMake preset files.
-  See :manual:`preset <cmake-presets(7)>` for more details.
+  Use a workflow :manual:`preset <cmake-presets(7)>` to specify a workflow.
+  The project binary directory is inferred from the initial configure preset.
+  The current working directory must contain CMake presets files.

  .. versionchanged:: 3.31
    When following immediately after the ``--workflow`` option,
@@ -1926,7 +1926,7 @@ The options are:
 .. option:: --list-presets

  Lists the available workflow presets. The current working directory must
-  contain CMake preset files.
+  contain ``CMakePresets.json`` and/or ``CMakeUserPresets.json``.

 .. option:: --fresh

@@ -120,13 +120,17 @@ Options

  Override/define :variable:`CPACK_PACKAGE_VENDOR`.

-.. option:: --preset <presetName>
+.. option:: --preset <preset>, --preset=<preset>

-  Use a preset from :manual:`cmake-presets(7)`.
+  Use a package :manual:`preset <cmake-presets(7)>` to specify package
+  options. The project binary directory is inferred from the
+  ``configurePreset`` key. The current working directory must contain
+  ``CMakePresets.json`` or ``CMakeUserPresets.json``.

 .. option:: --list-presets

-  List presets from :manual:`cmake-presets(7)`.
+  Lists the available package presets. The current working directory must
+  contain ``CMakePresets.json`` or ``CMakeUserPresets.json``.

 .. include:: include/OPTIONS_HELP.rst

@@ -69,10 +69,10 @@ The options for running tests are:

 .. option:: --preset <preset>, --preset=<preset>

- Use a test preset to specify test options. The project binary directory
- is inferred from the ``configurePreset`` key. The current working directory
- must contain CMake preset files.
- See :manual:`preset <cmake-presets(7)>` for more details.
+ Use a test :manual:`preset <cmake-presets(7)>` to specify test options. The
+ project binary directory is inferred from the ``configurePreset`` key. The
+ current working directory must contain ``CMakePresets.json`` and/or
+ ``CMakeUserPresets.json``.

 .. versionadded:: 3.30
   The ``--test-dir`` option may optionally be specified with a different
@@ -82,7 +82,7 @@ The options for running tests are:
 .. option:: --list-presets

 Lists the available test presets. The current working directory must contain
- CMake preset files.
+ ``CMakePresets.json`` and/or ``CMakeUserPresets.json``.

 .. option:: -C <cfg>, --build-config <cfg>

@@ -136,7 +136,7 @@
  .. versionchanged:: 4.3

    This field does not accept negative integer values, regardless of
-    the version in the preset file.
+    the version in the presets file.

 .. _`CMakePresets.buildPresets.targets`:

@@ -29,7 +29,7 @@
  .. versionchanged:: 4.3

    This field does not accept negative integer values,
-    regardless of the version in the preset file.
+    regardless of the version in the presets file.

 .. _`CMakePresets.testPresets.execution.resourceSpecFile`:

@@ -1033,7 +1033,7 @@ properties:
            .. versionchanged:: 4.3

              This field does not accept negative integer values, regardless of
-              the version in the preset file.
+              the version in the presets file.
          minimum: 0
        targets:
          anyOf:
@@ -1629,7 +1629,7 @@ properties:
                .. versionchanged:: 4.3

                  This field does not accept negative integer values,
-                  regardless of the version in the preset file.
+                  regardless of the version in the presets file.
              minimum: 0
            resourceSpecFile:
              type: string
@@ -19,7 +19,7 @@ Presets
  which allows the files to include other files.

 * :manual:`cmake-presets(7)` files now support a ``${fileDir}`` macro, which
-  contains the directory containing the preset file.
+  contains the directory containing the presets file.

 * :manual:`cmake-presets(7)` gained support for specifying the
  ``resolvePackageReferences`` command line option in a build preset to control
@@ -3,5 +3,5 @@ presets-fileDir

 * :manual:`cmake-presets(7)` files now support schema version 12. The
  :ref:`${fileDir} <CMakePresets fileDir>` macro now always expands to the
-  directory of the preset file containing the ``${fileDir}`` macro, regardless
+  directory of the presets file containing the ``${fileDir}`` macro, regardless
  of whether it is inherited by another preset in a different directory.
@@ -111,7 +111,7 @@ public slots:
                           cmDiagnostics::DiagnosticAction);
  /// check if project IDE open is possible and emit openPossible signal
  void checkOpenPossible();
-  /// Reload the preset files and tree
+  /// Reload the presets files and tree
  void loadPresets();

 public:
@@ -197,7 +197,7 @@ void PASSTHROUGH_ARGS_UNSUPPORTED(cmJSONState* state)

 void CYCLIC_INCLUDE(std::string const& file, cmJSONState* state)
 {
-  state->AddError(cmStrCat("Cyclic include among preset files: ", file));
+  state->AddError(cmStrCat("Cyclic include among presets files: ", file));
 }

 void TEST_OUTPUT_TRUNCATION_UNSUPPORTED(cmJSONState* state)
@@ -1,4 +1,4 @@
 ^CMake Error: Could not read presets from [^
 ]*/Tests/RunCMake/CMakePresets/IncludeCycle:
-Cyclic include among preset files: [^
+Cyclic include among presets files: [^
 ]*/CMakeUserPresets\.json$
@@ -1,4 +1,4 @@
 CMake Error: Could not read presets from [^
 ]*/Tests/RunCMake/CMakePresets/IncludeCycle3Files:
-Cyclic include among preset files: [^
+Cyclic include among presets files: [^
 ]*/CMakePresets\.json