Merge topic 'vs-package-restore'

9aa7831f05 Presets: add resolve packages setting to build presets.
b2f8f0bb87 cmGlobalVisualStudio10Generator: Auto restore NuGet packages.
193b8fca52 cmBuildOptions: Split build arguments into separate object.
6a10103493 Help: Update preset schema description for version 3 entries.

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

6 files changed, 152 insertions, 5 deletions

diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index e702d97..31bd9c0 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -474,6 +474,42 @@ that may contain the following fields:
   An optional bool. If true, equivalent to passing ``--clean-first`` on
   the command line.
 
+``resolvePackageReferences``
+
+  An optional string that specifies the package resolve mode. This is
+  allowed in preset files specifying version ``4`` or above.
+
+  This field overwrites the ``--resolve-package-references`` command line
+  parameter. 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.
+
+  ``off``
+
+    Package references will not be resolved. Note that this may cause
+    errors in some build environments, such as .NET SDK style projects.
+
+  ``only``
+
+    Only resolve package references, but do not perform a build.
+
+  .. note::
+
+    If this setting is not specified in a preset, CMake will instead
+    use the setting specified by the ``--resolve-package-references``
+    command line parameter. If the command line parameter is not
+    provided either, an environment-specific cache 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.
+
 ``verbose``
 
   An optional bool. If true, equivalent to passing ``--verbose`` on the
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 920bfe0..04c5a53 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -119,6 +119,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_DEVENV_COMMAND
    /variable/CMAKE_VS_MSBUILD_COMMAND
    /variable/CMAKE_VS_NsightTegra_VERSION
+   /variable/CMAKE_VS_NUGET_PACKAGE_RESTORE
    /variable/CMAKE_VS_PLATFORM_NAME
    /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT
    /variable/CMAKE_VS_PLATFORM_TOOLSET
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 04e2eda..1463f0a 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -463,6 +463,30 @@ following options:
   Build target ``clean`` first, then build.
   (To clean only, use ``--target clean``.)
 
+``--resolve-package-references=<on|off|only>``
+  .. versionadded:: 3.23
+
+  Resolve remote package references (e.g. NuGet packages) before build.
+  When set to ``on`` (default), packages will be restored before building a
+  target. When set to ``only``, the packages will be restored, but no build
+  will be performed. When set to ``off``, no packages will be restored.
+
+  If the target does not define any package references, this option does
+  nothing.
+
+  This setting can be specified in a build preset (using
+  ``resolvePackageReferences``). In this case, the command line option will
+  be ignored.
+
+  If the no command line parameter or preset option is not provided, an
+  environment-specific cache 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``.
+
 ``--use-stderr``
   Ignored.  Behavior is default in CMake >= 3.0.
 
diff --git a/Help/manual/presets/schema.json b/Help/manual/presets/schema.json
index 327291d..12f8b5e 100644
--- a/Help/manual/presets/schema.json
+++ b/Help/manual/presets/schema.json
@@ -52,7 +52,7 @@
         "cmakeMinimumRequired": { "$ref": "#/definitions/cmakeMinimumRequired"},
         "vendor": { "$ref": "#/definitions/vendor" },
         "configurePresets": { "$ref": "#/definitions/configurePresetsV3"},
-        "buildPresets": { "$ref": "#/definitions/buildPresetsV3"},
+        "buildPresets": { "$ref": "#/definitions/buildPresetsV4"},
         "testPresets": { "$ref": "#/definitions/testPresetsV3"},
         "include": { "$ref": "#/definitions/include"}
       },
@@ -427,9 +427,25 @@
         "additionalProperties": false
       }
     },
+    "buildPresetsItemsV4": {
+      "type": "array",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.",
+      "items": {
+        "type": "object",
+        "properties": {
+          "resolvePackageReferences": {
+            "type": "string",
+            "description": "An optional string specifying the package resolve behavior. Valid values are \"on\" (packages are resolved prior to the build), \"off\" (packages are not resolved prior to the build), and \"only\" (packages are resolved, but no build will be performed).",
+            "enum": [
+              "on", "off", "only"
+            ]
+          }
+        }
+      }
+    },
     "buildPresetsItemsV3": {
       "type": "array",
-      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.",
       "items": {
         "type": "object",
         "properties": {
@@ -558,9 +574,44 @@
         ]
       }
     },
+    "buildPresetsV4": {
+      "type": "array",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 4 and higher.",
+      "allOf": [
+        { "$ref": "#/definitions/buildPresetsItemsV4" },
+        { "$ref": "#/definitions/buildPresetsItemsV3" },
+        { "$ref": "#/definitions/buildPresetsItemsV2" }
+      ],
+      "items": {
+        "type": "object",
+        "properties": {
+          "name": {},
+          "hidden": {},
+          "inherits": {},
+          "configurePreset": {},
+          "vendor": {},
+          "displayName": {},
+          "description": {},
+          "inheritConfigureEnvironment": {},
+          "environment": {},
+          "jobs": {},
+          "targets": {},
+          "configuration": {},
+          "cleanFirst": {},
+          "resolvePackageReferences": {},
+          "verbose": {},
+          "nativeToolOptions": {},
+          "condition": {}
+        },
+        "required": [
+          "name"
+        ],
+        "additionalProperties": false
+      }
+    },
     "buildPresetsV3": {
       "type": "array",
-      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 2 and higher.",
+      "description": "An optional array of build preset objects. Used to specify arguments to cmake --build. Available in version 3 and higher.",
       "allOf": [
         { "$ref": "#/definitions/buildPresetsItemsV3" },
         { "$ref": "#/definitions/buildPresetsItemsV2" }
@@ -624,7 +675,7 @@
     },
     "testPresetsItemsV3": {
       "type": "array",
-      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
       "items": {
         "type": "object",
         "properties": {
@@ -949,7 +1000,7 @@
     },
     "testPresetsV3": {
       "type": "array",
-      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 2 and higher.",
+      "description": "An optional array of test preset objects. Used to specify arguments to ctest. Available in version 3 and higher.",
       "allOf": [
         { "$ref": "#/definitions/testPresetsItemsV2" },
         { "$ref": "#/definitions/testPresetsItemsV3" }
diff --git a/Help/release/dev/vs-package-restore.rst b/Help/release/dev/vs-package-restore.rst
new file mode 100644
index 0000000..e8b5f0c
--- /dev/null
+++ b/Help/release/dev/vs-package-restore.rst
@@ -0,0 +1,13 @@
+vs-package-restore
+------------------
+
+* Targets with :prop_tgt:`VS_PACKAGE_REFERENCES` will now automatically attempt
+  to restore the package references from NuGet. The cache variable
+  :variable:`CMAKE_VS_NUGET_PACKAGE_RESTORE` was added to toggle automatic
+  package restore off.
+
+* :manual:`cmake(1)` gained the ``--resolve-package-references=<on|off|only>``
+  command-line option to control automatic package restoration.
+
+* :manual:`cmake-presets(7)` gained support for specifying the
+  ``resolvePackageReferences`` command line option in a build preset.
diff --git a/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst b/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst
new file mode 100644
index 0000000..7160726
--- /dev/null
+++ b/Help/variable/CMAKE_VS_NUGET_PACKAGE_RESTORE.rst
@@ -0,0 +1,22 @@
+CMAKE_VS_NUGET_PACKAGE_RESTORE
+------------------------------
+
+.. versionadded:: 3.23
+
+When using a Visual Studio generator, this cache variable controls
+if msbuild should automatically attempt to restore NuGet packages
+prior to a build. NuGet packages can be defined using the
+:prop_tgt:`VS_PACKAGE_REFERENCES` property on a target. If no
+package references are defined, this setting will do nothing.
+
+The command line option ``--resolve-package-references`` can be used
+alternatively to control the resolve behavior globally. This option
+will take precedence over the cache variable.
+
+Targets that use the :prop_tgt:`DOTNET_SDK` are required to run a
+restore before building. Disabling this option may cause the build
+to fail in such projects.
+
+This setting is stored as a cache entry. Default value is ``ON``.
+
+See also the :prop_tgt:`VS_PACKAGE_REFERENCES` property.