Merge topic 'preset-schema-refactor'

3373abf901 presets: Require valid CMake cache variable type in schema
c5862fee8f Help/presets: Improve formatting of some references
eee0bd2f6a presets: Factor out additional fields in schema
a9ad31820b presets: Refactor JSON schema
4e1dfc5194 Tests: Print concise error in JSON schema validation

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

Help/manual/cmake-presets.7.rst

@@ -140,7 +140,7 @@ that may contain the following fields:
 
 ``name``
   A required string representing the machine-friendly name of the preset.
-  This identifier is used in the :ref:`cmake --preset <CMake Options>` option.
+  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,
@@ -148,11 +148,12 @@ that may contain the following fields:
 
 ``hidden``
   An optional boolean specifying whether or not a preset should be hidden.
-  If a preset is hidden, it cannot be used in the ``--preset=`` argument,
-  will not show up in the :manual:`CMake GUI <cmake-gui(1)>`, and does not
-  have to have a valid ``generator`` or ``binaryDir``, even from
-  inheritance. ``hidden`` presets are intended to be used as a base for
-  other presets to inherit via the ``inherits`` field.
+  If a preset is hidden, it cannot be used in the
+  :option:`--preset <cmake --preset>` argument, will not show up in the
+  :manual:`CMake GUI <cmake-gui(1)>`, and does not have to have a valid
+  ``generator`` or ``binaryDir``, even from inheritance. ``hidden`` presets are
+  intended to be used as a base for other presets to inherit via the
+  ``inherits`` field.
 
 ``inherits``
   An optional array of strings representing the names of presets to inherit
@@ -192,13 +193,13 @@ that may contain the following fields:
 .. _`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
-  ``inherits`` preset (unless this preset is ``hidden``). In version ``3``
-  or above, this field may be omitted to fall back to regular generator
-  discovery procedure.
+  An optional string representing the :manual:`generator <cmake-generators(7)>`
+  to use for the preset. If ``generator`` is not specified, it must be
+  inherited from the ``inherits`` preset (unless this preset is ``hidden``).
+  In version ``3`` or above, this field may be omitted to fall back to regular
+  generator discovery procedure.
 
-  Note that for Visual Studio generators, unlike in the command line
+  Note that for :ref:`Visual Studio generators`, unlike in the command line
   :option:`-G <cmake -G>` argument, you cannot include the platform name
   in the generator name. Use the ``architecture`` field instead.
 
@@ -443,7 +444,7 @@ that may contain the following fields:
 ``name``
   A required string representing the machine-friendly name of the preset.
   This identifier is used in the
-  :ref:`cmake --build --preset <Build Tool Mode>` option.
+  :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,
@@ -452,7 +453,7 @@ that may contain the following fields:
 ``hidden``
   An optional boolean specifying whether or not a preset should be hidden.
   If a preset is hidden, it cannot be used in the
-  :option:`--preset <cmake --preset>` argument
+  :option:`--preset <cmake--build --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.
@@ -515,16 +516,16 @@ that may contain the following fields:
 
   .. note::
 
-    For a CMake project using ExternalProject with a configuration preset
-    having environment variables needed in the ExternalProject, use a build
-    preset that inherits that configuration preset or the ExternalProject
+    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 ``CC`` and ``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.
+    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.
 
 ``configurePreset``
   An optional string specifying the name of a configure preset to
@@ -566,8 +567,8 @@ that may contain the following fields:
 
   Package references are used to define dependencies to packages from
   external package managers. Currently only NuGet in combination with the
-  Visual Studio generator is supported. If there are no targets that define
-  package references, this option does nothing. Valid values are:
+  :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.
@@ -588,11 +589,11 @@ that may contain the following fields:
     variable will be evaluated to decide, if package restoration should be
     performed.
 
-    When using the Visual Studio generator, 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
-    ``CMAKE_VS_NUGET_PACKAGE_RESTORE`` variable to ``OFF``. This can also be
-    done from within a configure preset.
+    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``
   An optional bool. If true, equivalent to passing
@@ -1113,8 +1114,8 @@ fields:
 ``name``
   A required string representing the machine-friendly name of the preset.
   This identifier is used in the
-  :ref:`cmake --workflow --preset <Workflow Mode>` option. There must not be
-  two workflow presets in the union of ``CMakePresets.json`` and
+  :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.

Tests/RunCMake/CMakePresets/validate_schema.cmake

@@ -6,13 +6,11 @@ function(validate_schema file expected_result)
   execute_process(
     COMMAND "${Python_EXECUTABLE}" "${CMakePresets_VALIDATE_SCRIPT_PATH}" "${file}"
     RESULT_VARIABLE _result
-    OUTPUT_VARIABLE _output
     ERROR_VARIABLE _error
     )
   if(NOT _result STREQUAL expected_result)
-    string(REPLACE "\n" "\n  " _output_p "${_output}")
     string(REPLACE "\n" "\n  " _error_p "${_error}")
-    string(APPEND RunCMake_TEST_FAILED "Expected result of validating ${file}: ${expected_result}\nActual result: ${_result}\nOutput:\n  ${_output_p}\nError:\n  ${_error_p}\n")
+    string(APPEND RunCMake_TEST_FAILED "Expected result of validating ${file}: ${expected_result}\nActual result: ${_result}\nError:\n  ${_error_p}")
   endif()
 
   set(RunCMake_TEST_FAILED "${RunCMake_TEST_FAILED}" PARENT_SCOPE)

Tests/RunCMake/CMakePresets/validate_schema.py

@@ -13,4 +13,8 @@ schema_file = os.path.join(
 with open(schema_file, "r", encoding="utf-8") as f:
     schema = json.load(f)
 
-jsonschema.validate(contents, schema)
+try:
+    jsonschema.validate(contents, schema)
+except (jsonschema.ValidationError, jsonschema.SchemaError) as e:
+    sys.stderr.write(e.message)
+    sys.exit(1)