Merge topic 'vs-package-restore-docs' into release-3.23

d92469e572 Help: Clarify how package resolve mode is intended to be used
f320a31087 cmake --build: prioritize --resolve-package-references over preset

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

3 files changed, 28 insertions, 26 deletions

diff --git a/Help/manual/cmake-presets.7.rst b/Help/manual/cmake-presets.7.rst
index 31bd9c0..69d0543 100644
--- a/Help/manual/cmake-presets.7.rst
+++ b/Help/manual/cmake-presets.7.rst
@@ -479,9 +479,10 @@ that may contain the following fields:
   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:
+  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:
 
   ``on``
 
@@ -498,17 +499,16 @@ that may contain the following fields:
 
   .. 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.
+    The command line parameter ``--resolve-package-references`` will take
+    priority over this setting. If the command line parameter is not provided
+    and this setting is not specified, 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``
 
diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst
index 7eb7dec..f7d4f6b 100644
--- a/Help/manual/cmake.1.rst
+++ b/Help/manual/cmake.1.rst
@@ -467,21 +467,20 @@ following options:
 ``--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.
+  Resolve remote package references from external package managers (e.g. NuGet)
+  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.
+  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.
+  ``resolvePackageReferences``). The preset setting will be ignored, if this
+  command line option is specified.
 
-  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.
+  If no command line parameter or preset option are 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
diff --git a/Help/release/3.23.rst b/Help/release/3.23.rst
index cce936b..b2928db 100644
--- a/Help/release/3.23.rst
+++ b/Help/release/3.23.rst
@@ -19,7 +19,10 @@ Presets
   which allows the files to include other files.
 
 * :manual:`cmake-presets(7)` gained support for specifying the
-  ``resolvePackageReferences`` command line option in a build preset.
+  ``resolvePackageReferences`` command line option in a build preset to control
+  restoration behavior of package references from external package managers.
+  Currently this is only supported by the Visual Studio generator to support
+  restoring packages from NuGet. Other generators ignore this option.
 
 Generators
 ----------