18 files changed, 221 insertions, 20 deletions
diff --git a/Help/command/string.rst b/Help/command/string.rst
index 29ad082..9b707eb 100644
--- a/Help/command/string.rst
+++ b/Help/command/string.rst
@@ -490,6 +490,9 @@ specifiers:
 ``%S``
   The second of the current minute.  60 represents a leap second. (00-60)
 
+``%f``
+  The microsecond of the current second (000000-999999).
+
 ``%U``
   The week number of the current year (00-53).
 
diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst
index 3e53b2e..3fc7926 100644
--- a/Help/command/target_include_directories.rst
+++ b/Help/command/target_include_directories.rst
@@ -27,9 +27,8 @@ The following arguments specify include directories.
 .. versionadded:: 3.11
   Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
 
-Specified include directories may be absolute paths or relative paths.
-Repeated calls for the same <target> append items in the order called.  If
-``SYSTEM`` is specified, the compiler will be told the
+Repeated calls for the same ``<target>`` append items in the order called.
+If ``SYSTEM`` is specified, the compiler will be told the
 directories are meant as system include directories on some platforms
 (signalling this setting might achieve effects such as the compiler
 skipping warnings, or these fixed-install system files not being
@@ -43,12 +42,22 @@ with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
+Specified include directories may be absolute paths or relative paths.
+A relative path will be interpreted as relative to the current source
+directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an
+absolute path before storing it in the associated target property.
+If the path starts with a generator expression, it will always be assumed
+to be an absolute path (with one exception noted below) and will be used
+unmodified.
+
 Include directories usage requirements commonly differ between the build-tree
-and the install-tree.  The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
-generator expressions can be used to describe separate usage requirements
-based on the usage location.  Relative paths are allowed within the
-``INSTALL_INTERFACE`` expression and are interpreted relative to the
-installation prefix.  For example:
+and the install-tree.  The :genex:`BUILD_INTERFACE` and
+:genex:`INSTALL_INTERFACE` generator expressions can be used to describe
+separate usage requirements based on the usage location.  Relative paths
+are allowed within the :genex:`INSTALL_INTERFACE` expression and are
+interpreted as relative to the installation prefix.  Relative paths should not
+be used in :genex:`BUILD_INTERFACE` expressions because they will not be
+converted to absolute.  For example:
 
 .. code-block:: cmake
 
diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
index a54d728..73e1907 100644
--- a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
+++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
@@ -1,11 +1,11 @@
 
-Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
-|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
+Note that it is not advisable to populate the :genex:`INSTALL_INTERFACE` of
+the |INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
 directories of dependencies.  That would hard-code into installed packages
 the include directory paths for dependencies
 **as found on the machine the package was made on**.
 
-The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
+The :genex:`INSTALL_INTERFACE` of the |INTERFACE_PROPERTY_LINK| is only
 suitable for specifying the required include directories for headers
 provided with the target itself, not those provided by the transitive
 dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target
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/prop_tgt/LINKER_LANGUAGE.rst b/Help/prop_tgt/LINKER_LANGUAGE.rst
index b0a572b..f47b488 100644
--- a/Help/prop_tgt/LINKER_LANGUAGE.rst
+++ b/Help/prop_tgt/LINKER_LANGUAGE.rst
@@ -7,8 +7,10 @@ For executables, shared libraries, and modules, this sets the language
 whose compiler is used to link the target (such as "C" or "CXX").  A
 typical value for an executable is the language of the source file
 providing the program entry point (main).  If not set, the language
-with the highest linker preference value is the default.  See
-documentation of :variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables.
+with the highest linker preference value is the default.  Details of
+the linker preferences are considered internal, but some limited
+discussion can be found under the internal
+:variable:`CMAKE_<LANG>_LINKER_PREFERENCE` variables.
 
 If this property is not set by the user, it will be calculated at
 generate-time by CMake.
diff --git a/Help/release/3.22.rst b/Help/release/3.22.rst
index fcb655d..a82d396 100644
--- a/Help/release/3.22.rst
+++ b/Help/release/3.22.rst
@@ -142,3 +142,16 @@ Other Changes
   This became available as of VS 16.10 (toolchain version 14.29.30037).
 
 * The :cpack_gen:`CPack NSIS Generator` now requires NSIS 3.03 or later.
+
+3.22.1
+------
+
+This version made no changes to documented features or interfaces.
+Some implementation updates were made to support ecosystem changes
+and/or fix regressions.
+
+3.22.2
+------
+
+* The ``OLD`` behavior of :policy:`CMP0128` was fixed to add flags even when
+  the specified standard matches the compiler default.
diff --git a/Help/release/dev/cuda-compiler-detection-robustness.rst b/Help/release/dev/cuda-compiler-detection-robustness.rst
new file mode 100644
index 0000000..cc49a8d
--- /dev/null
+++ b/Help/release/dev/cuda-compiler-detection-robustness.rst
@@ -0,0 +1,11 @@
+cuda-compiler-detection-robustness
+----------------------------------
+
+* CUDA compiler detection now issues an error in all cases when it's unable to
+  compute the default architecture(s) if required (see :policy:`CMP0104`).
+
+* CUDA compiler detection now correctly handles ``OFF`` for
+  :variable:`CMAKE_CUDA_ARCHITECTURES` on Clang.
+
+* CUDA compiler detection now supports the theoretical case of multiple default
+  architectures.
diff --git a/Help/release/dev/cuda-invalid-architectures.rst b/Help/release/dev/cuda-invalid-architectures.rst
new file mode 100644
index 0000000..3313dbb
--- /dev/null
+++ b/Help/release/dev/cuda-invalid-architectures.rst
@@ -0,0 +1,5 @@
+cuda-invalid-architectures
+--------------------------
+
+* CUDA compiler detection now tries to detect invalid architectures and issue
+  an error.
diff --git a/Help/release/dev/ibmclang-compiler.rst b/Help/release/dev/ibmclang-compiler.rst
new file mode 100644
index 0000000..2a9b5ad
--- /dev/null
+++ b/Help/release/dev/ibmclang-compiler.rst
@@ -0,0 +1,5 @@
+ibmclang-compiler
+-----------------
+
+* The IBM Open XL C/C++ compiler, based on LLVM, is now supported with
+  compiler id ``IBMClang``.
diff --git a/Help/release/dev/timestamp-microseconds.rst b/Help/release/dev/timestamp-microseconds.rst
new file mode 100644
index 0000000..0c95eb4
--- /dev/null
+++ b/Help/release/dev/timestamp-microseconds.rst
@@ -0,0 +1,5 @@
+timestamp-microseconds
+----------------------
+
+* The :command:`string(TIMESTAMP)` and :command:`file(TIMESTAMP)` commands now
+  support the ``%f`` specifier for microseconds.
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_CURRENT_BINARY_DIR.rst b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst
index 40496b5..8fc85ee 100644
--- a/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst
+++ b/Help/variable/CMAKE_CURRENT_BINARY_DIR.rst
@@ -3,7 +3,7 @@ CMAKE_CURRENT_BINARY_DIR
 
 The path to the binary directory currently being processed.
 
-This the full path to the build directory that is currently being
+This is the full path to the build directory that is currently being
 processed by cmake.  Each directory added by :command:`add_subdirectory` will
 create a binary directory in the build tree, and as it is being
 processed this variable will be set.  For in-source builds this is the
diff --git a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst
index c1b755a..1a25efc 100644
--- a/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst
+++ b/Help/variable/CMAKE_CURRENT_SOURCE_DIR.rst
@@ -3,7 +3,7 @@ CMAKE_CURRENT_SOURCE_DIR
 
 The path to the source directory currently being processed.
 
-This the full path to the source directory that is currently being
+This is the full path to the source directory that is currently being
 processed by cmake.
 
 When run in -P script mode, CMake sets the variables
diff --git a/Help/variable/CMAKE_LANG_COMPILER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_ID.rst
index 1db42c7..cd7d5cd 100644
--- a/Help/variable/CMAKE_LANG_COMPILER_ID.rst
+++ b/Help/variable/CMAKE_LANG_COMPILER_ID.rst
@@ -41,6 +41,7 @@ include:
   TinyCC = Tiny C Compiler (tinycc.org)
   XL, VisualAge, zOS = IBM XL (ibm.com)
   XLClang = IBM Clang-based XL (ibm.com)
+  IBMClang = IBM LLVM-based Compiler (ibm.com)
 
 This variable is not guaranteed to be defined for all compilers or
 languages.
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.