Merge topic 'cmake-presets-condition'

8bc5c8961e CMakePresets.json: Add the ability to conditionally disable presets
ce6ea7c927 Refactor: Move some common code into separate file
ebbd475e54 Refactor: Move cmCMakePresetsFile::ReadJSON into a separate file

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

4 files changed, 460 insertions, 9 deletions

diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index 5273236..cc72603 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -119,6 +119,11 @@ that may contain the following fields:
   This field can also be a string, which is equivalent to an array
   containing one string.
 
+``condition``
+
+  An optional `Condition`_ object. This is allowed in preset files specifying
+  version ``3`` or above.
+
 ``vendor``
 
   An optional map containing vendor-specific information. CMake does not
@@ -345,6 +350,11 @@ that may contain the following fields:
   This field can also be a string, which is equivalent to an array
   containing one string.
 
+``condition``
+
+  An optional `Condition`_ object. This is allowed in preset files specifying
+  version ``3`` or above.
+
 ``vendor``
 
   An optional map containing vendor-specific information. CMake does not
@@ -464,6 +474,11 @@ that may contain the following fields:
   This field can also be a string, which is equivalent to an array
   containing one string.
 
+``condition``
+
+  An optional `Condition`_ object. This is allowed in preset files specifying
+  version ``3`` or above.
+
 ``vendor``
 
   An optional map containing vendor-specific information. CMake does not
@@ -789,6 +804,87 @@ that may contain the following fields:
 
       Equivalent to passing ``--no-tests=ignore`` on the command line.
 
+Condition
+^^^^^^^^^
+
+The ``condition`` field of a preset, allowed in preset files specifying version
+``3`` or above, is used to determine whether or not the preset is enabled. For
+example, this can be used to disable a preset on platforms other than Windows.
+``condition`` may be either a boolean, ``null``, or an object. If it is a
+boolean, the boolean indicates whether the preset is enabled or disabled. If it
+is ``null``, the preset is enabled, but the ``null`` condition is not inherited
+by any presets that may inherit from the preset. Sub-conditions (for example in
+a ``not``, ``anyOf``, or ``allOf`` condition) may not be ``null``. If it is an
+object, it has the following fields:
+
+``type``
+
+  A required string with one of the following values:
+
+  ``"const"``
+
+    Indicates that the condition is constant. This is equivalent to using a
+    boolean in place of the object. The condition object will have the
+    following additional fields:
+
+    ``value``
+
+      A required boolean which provides a constant value for the condition's
+      evaluation.
+
+  ``"equals"``
+
+  ``"notEquals"``
+
+    Indicates that the condition compares two strings to see if they are equal
+    (or not equal). The condition object will have the following additional
+    fields:
+
+    ``lhs``
+
+      First string to compare. This field supports macro expansion.
+
+    ``rhs``
+
+      Second string to compare. This field supports macro expansion.
+
+  ``"inList"``
+
+  ``"notInList"``
+
+    Indicates that the condition searches for a string in a list of strings.
+    The condition object will have the following additional fields:
+
+    ``string``
+
+      A required string to search for. This field supports macro expansion.
+
+    ``list``
+
+      A required list of strings to search. This field supports macro
+      expansion, and uses short-circuit evaluation.
+
+  ``"anyOf"``
+
+  ``"allOf"``
+
+    Indicates that the condition is an aggregation of zero or more nested
+    conditions. The condition object will have the following additional fields:
+
+    ``conditions``
+
+      A required array of condition objects. These conditions use short-circuit
+      evaluation.
+
+  ``"not"``
+
+    Indicates that the condition is an inversion of another condition. The
+    condition object will have the following additional fields:
+
+    ``condition``
+
+      A required condition object.
+
 Macro Expansion
 ^^^^^^^^^^^^^^^
 
diff --git a/Help/manual/presets/example.json b/Help/manual/presets/example.json
index dfc2910..346f342 100644
--- a/Help/manual/presets/example.json
+++ b/Help/manual/presets/example.json
@@ -1,5 +1,5 @@
 {
-  "version": 2,
+  "version": 3,
   "cmakeMinimumRequired": {
     "major": 3,
     "minor": 20,
@@ -35,6 +35,17 @@
       "displayName": "Ninja Multi-Config",
       "description": "Default build using Ninja Multi-Config generator",
       "generator": "Ninja Multi-Config"
+    },
+    {
+      "name": "windows-only",
+      "inherits": "default",
+      "displayName": "Windows-only configuration",
+      "description": "This build is only available on Windows",
+      "condition": {
+        "type": "equals",
+        "lhs": "${hostSystemName}",
+        "rhs": "Windows"
+      }
     }
   ],
   "buildPresets": [
diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json
index e2b1d95..c3c3ca1 100644
--- a/Help/manual/presets/schema.json
+++ b/Help/manual/presets/schema.json
@@ -24,8 +24,8 @@
         "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
         "vendor": { "$ref": "#/definitions/vendor" },
         "configurePresets": { "$ref": "#/definitions/configurePresetsV1"},
-        "buildPresets": { "$ref": "#/definitions/buildPresets"},
-        "testPresets": { "$ref": "#/definitions/testPresets"}
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV2"},
+        "testPresets": { "$ref": "#/definitions/testPresetsV2"}
       },
       "additionalProperties": false
     },
@@ -38,8 +38,8 @@
         "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
         "vendor": { "$ref": "#/definitions/vendor" },
         "configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
-        "buildPresets": { "$ref": "#/definitions/buildPresets"},
-        "testPresets": { "$ref": "#/definitions/testPresets"}
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV3"},
+        "testPresets": { "$ref": "#/definitions/testPresetsV3"}
       },
       "additionalProperties": false
     }
@@ -82,7 +82,8 @@
           "installDir": {
             "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)."
-          }
+          },
+          "condition": { "$ref": "#/definitions/topCondition" }
         }
       }
     },
@@ -358,7 +359,8 @@
           "environment": {},
           "warnings": {},
           "errors": {},
-          "debug": {}
+          "debug": {},
+          "condition": {}
         },
         "required": [
           "name"
@@ -397,7 +399,17 @@
         "additionalProperties": false
       }
     },
-    "buildPresets": {
+    "buildPresetsItemsV3": {
+      "type": "array",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "condition": { "$ref": "#/definitions/topCondition" }
+        }
+      }
+    },
+    "buildPresetsItemsV2": {
       "type": "array",
       "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
       "items": {
@@ -515,11 +527,84 @@
         },
         "required": [
           "name"
+        ]
+      }
+    },
+    "buildPresetsV3": {
+      "type": "array",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+      "allOf": [
+        { "$ref": "#/definitions/buildPresetsItemsV3" },
+        { "$ref": "#/definitions/buildPresetsItemsV2" }
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {},
+          "hidden": {},
+          "inherits": {},
+          "configurePreset": {},
+          "vendor": {},
+          "displayName": {},
+          "description": {},
+          "inheritConfigureEnvironment": {},
+          "environment": {},
+          "jobs": {},
+          "targets": {},
+          "configuration": {},
+          "cleanFirst": {},
+          "verbose": {},
+          "nativeToolOptions": {},
+          "condition": {}
+        },
+        "required": [
+          "name"
         ],
         "additionalProperties": false
       }
     },
-    "testPresets": {
+    "buildPresetsV2": {
+      "type": "array",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+      "allOf": [
+        { "$ref": "#/definitions/buildPresetsItemsV2" }
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {},
+          "hidden": {},
+          "inherits": {},
+          "configurePreset": {},
+          "vendor": {},
+          "displayName": {},
+          "description": {},
+          "inheritConfigureEnvironment": {},
+          "environment": {},
+          "jobs": {},
+          "targets": {},
+          "configuration": {},
+          "cleanFirst": {},
+          "verbose": {},
+          "nativeToolOptions": {}
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "testPresetsItemsV3": {
+      "type": "array",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "condition": { "$ref": "#/definitions/topCondition" }
+        }
+      }
+    },
+    "testPresetsItemsV2": {
       "type": "array",
       "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
       "items": {
@@ -831,9 +916,264 @@
         },
         "required": [
           "name"
+        ]
+      }
+    },
+    "testPresetsV3": {
+      "type": "array",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+      "allOf": [
+        { "$ref": "#/definitions/testPresetsItemsV2" },
+        { "$ref": "#/definitions/testPresetsItemsV3" }
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {},
+          "hidden": {},
+          "inherits": {},
+          "configurePreset": {},
+          "vendor": {},
+          "displayName": {},
+          "description": {},
+          "inheritConfigureEnvironment": {},
+          "environment": {},
+          "configuration": {},
+          "overwriteConfigurationFile": {},
+          "output": {},
+          "filter": {},
+          "execution": {},
+          "condition": {}
+        },
+        "required": [
+          "name"
         ],
         "additionalProperties": false
       }
+    },
+    "testPresetsV2": {
+      "type": "array",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+      "allOf": [
+        { "$ref": "#/definitions/testPresetsItemsV2" }
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {},
+          "hidden": {},
+          "inherits": {},
+          "configurePreset": {},
+          "vendor": {},
+          "displayName": {},
+          "description": {},
+          "inheritConfigureEnvironment": {},
+          "environment": {},
+          "configuration": {},
+          "overwriteConfigurationFile": {},
+          "output": {},
+          "filter": {},
+          "execution": {}
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "condition": {
+      "anyOf": [
+        {
+          "type": "boolean",
+          "description": "A boolean which provides a constant value for the condition's evaluation."
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "A required string specifying the type of the condition.",
+              "const": "const"
+            },
+            "value": {
+              "type": "boolean",
+              "description": "A required boolean which provides a constant value for the condition's evaluation."
+            }
+          },
+          "required": [
+            "type",
+            "value"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "A required string specifying the type of the condition.",
+              "const": "equals"
+            },
+            "lhs": {
+              "type": "string",
+              "description": "First string to compare. This field supports macro expansion."
+            },
+            "rhs": {
+              "type": "string",
+              "description": "Second string to compare. This field supports macro expansion."
+            }
+          },
+          "required": [
+            "type",
+            "lhs",
+            "rhs"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "A required string specifying the type of the condition.",
+              "const": "notEquals"
+            },
+            "lhs": {
+              "type": "string",
+              "description": "First string to compare. This field supports macro expansion."
+            },
+            "rhs": {
+              "type": "string",
+              "description": "Second string to compare. This field supports macro expansion."
+            }
+          },
+          "required": [
+            "type",
+            "lhs",
+            "rhs"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "A required string specifying the type of the condition.",
+              "const": "inList"
+            },
+            "string": {
+              "type": "string",
+              "description": "A required string to search for. This field supports macro expansion."
+            },
+            "list": {
+              "type": "array",
+              "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": [
+            "type",
+            "string",
+            "list"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "A required string specifying the type of the condition.",
+              "const": "notInList"
+            },
+            "string": {
+              "type": "string",
+              "description": "A required string to search for. This field supports macro expansion."
+            },
+            "list": {
+              "type": "array",
+              "description": "A required list of strings to search. This field supports macro expansion, and uses short-circuit evaluation.",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "required": [
+            "type",
+            "string",
+            "list"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "A required string specifying the type of the condition.",
+              "const": "anyOf"
+            },
+            "conditions": {
+              "type": "array",
+              "description": "A required array of condition objects. These conditions use short-circuit evaluation.",
+              "items": { "$ref": "#/definitions/condition" }
+            }
+          },
+          "required": [
+            "type",
+            "conditions"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "A required string specifying the type of the condition.",
+              "const": "allOf"
+            },
+            "conditions": {
+              "type": "array",
+              "description": "A required array of condition objects. These conditions use short-circuit evaluation.",
+              "items": { "$ref": "#/definitions/condition" }
+            }
+          },
+          "required": [
+            "type",
+            "conditions"
+          ],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "A required string specifying the type of the condition.",
+              "const": "not"
+            },
+            "condition": { "$ref": "#/definitions/condition" }
+          },
+          "required": [
+            "type",
+            "condition"
+          ],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "topCondition": {
+      "anyOf": [
+        { "$ref": "#/definitions/condition" },
+        {
+          "type": "null",
+          "description": "Null indicates that the condition always evaluates to true and is not inherited."
+        }
+      ]
     }
   }
 }
diff --git a/Help/release/dev/cmake-presets-condition.rst b/Help/release/dev/cmake-presets-condition.rst
new file mode 100644
index 0000000..aa01bc1
--- /dev/null
+++ b/Help/release/dev/cmake-presets-condition.rst
@@ -0,0 +1,4 @@
+cmake-presets-condition
+-----------------------
+
+* :manual:`cmake-presets(7)` now support conditional enabling of presets.