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

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.
+    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.
+    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``
 

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

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
 ----------

Source/cmBuildOptions.h

@@ -7,20 +7,20 @@
 /** \brief Defines how to resolve packages **/
 enum class PackageResolveMode
 {
-  /** \brief Defines behavior based on cache variable (e.g.
+  /** \brief Behavior is defined by preset or cache variable (e.g.
      CMAKE_VS_NUGET_PACKAGE_RESTORE). This is the default. **/
-  FromCacheVariable,
+  Default,
 
-  /** \brief Ignore behavior defined by cache variable and forces packages to
-     be resolved prior to build. **/
+  /** \brief Ignore behavior defined by preset or cache variable and forces
+     packages to be resolved prior to build. **/
   Force,
 
-  /** \brief Ignore behavior defined by cache variable and forces packages to
-     be resolved, but skip the actual build. **/
+  /** \brief Ignore behavior defined by preset or cache variable and forces
+     packages to be resolved, but skip the actual build. **/
   OnlyResolve,
 
-  /** \brief Ignore behavior defined by cache variable and dont resolve any
-     packages **/
+  /** \brief Ignore behavior defined by preset or cache variable and don't
+     resolve any packages **/
   Disable
 };
 
@@ -40,5 +40,5 @@ public:
 
   bool Clean = false;
   bool Fast = false;
-  PackageResolveMode ResolveMode = PackageResolveMode::FromCacheVariable;
+  PackageResolveMode ResolveMode = PackageResolveMode::Default;
 };

Source/cmGlobalVisualStudio10Generator.cxx

@@ -1222,7 +1222,7 @@ cmGlobalVisualStudio10Generator::GenerateBuildCommand(
               "Studio 2017 and later. You have to manually restore the "
               "packages using NuGet before building the project.");
             restorePackages = false;
-          } else if (restoreMode == PackageResolveMode::FromCacheVariable) {
+          } else if (restoreMode == PackageResolveMode::Default) {
             // Decide if a restore is performed, based on a cache variable.
             if (cmValue cached =
                   this->CMakeInstance->GetState()->GetCacheEntryValue(

Source/cmake.cxx

@@ -3356,7 +3356,8 @@ int cmake::Build(int jobs, std::string dir, std::vector<std::string> targets,
       buildOptions.Clean = *expandedPreset->CleanFirst;
     }
 
-    if (expandedPreset->ResolvePackageReferences) {
+    if (buildOptions.ResolveMode == PackageResolveMode::Default &&
+        expandedPreset->ResolvePackageReferences) {
       buildOptions.ResolveMode = *expandedPreset->ResolvePackageReferences;
     }
 

Source/cmakemain.cxx

@@ -447,7 +447,7 @@ int do_build(int ac, char const* const* av)
   bool cleanFirst = false;
   bool foundClean = false;
   bool foundNonClean = false;
-  PackageResolveMode resolveMode = PackageResolveMode::FromCacheVariable;
+  PackageResolveMode resolveMode = PackageResolveMode::Default;
   bool verbose = cmSystemTools::HasEnv("VERBOSE");
   std::string presetName;
   bool listPresets = false;