VS: Add a variable to report the Visual Studio version build number

VS 2017 and above come with a Visual Studio Installer tool that tracks
four-component Visual Studio version numbers.  We already detect the VS
version number because it is needed to make some generation decisions.
Provide the number to projects in a `CMAKE_VS_VERSION_BUILD_NUMBER`
variable so they can use it similarly.

Fixes: #24230

8 files changed, 38 insertions, 0 deletions

diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 2a1e017..23d8256 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -131,6 +131,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_TARGET_FRAMEWORK_IDENTIFIER
    /variable/CMAKE_VS_TARGET_FRAMEWORK_TARGETS_VERSION
    /variable/CMAKE_VS_TARGET_FRAMEWORK_VERSION
+   /variable/CMAKE_VS_VERSION_BUILD_NUMBER
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
    /variable/CMAKE_XCODE_BUILD_SYSTEM
diff --git a/Help/release/dev/vs-version-var.rst b/Help/release/dev/vs-version-var.rst
new file mode 100644
index 0000000..09daab7
--- /dev/null
+++ b/Help/release/dev/vs-version-var.rst
@@ -0,0 +1,6 @@
+vs-version-var
+--------------
+
+* A :variable:`CMAKE_VS_VERSION_BUILD_NUMBER` variable is now set by
+  :ref:`Visual Studio Generators` for VS 2017 and above to report the
+  four-component Visual Studio version number.
diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
index 0607843..4317622 100644
--- a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
+++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
@@ -59,3 +59,6 @@ to hold the value persistently.  If an environment variable of the form
 is set and points to the ``Common7/Tools`` directory within one of the
 VS instances, that instance will be used.  Otherwise, if more than one
 VS instance is installed we do not define which one is chosen by default.
+
+The VS version build number of the selected VS instance is provided in
+the :variable:`CMAKE_VS_VERSION_BUILD_NUMBER` variable.
diff --git a/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst
new file mode 100644
index 0000000..f86ed7c
--- /dev/null
+++ b/Help/variable/CMAKE_VS_VERSION_BUILD_NUMBER.rst
@@ -0,0 +1,14 @@
+CMAKE_VS_VERSION_BUILD_NUMBER
+-----------------------------
+
+.. versionadded:: 3.26
+
+Visual Studio version.
+
+:ref:`Visual Studio Generators` for VS 2017 and above set this
+variable to the Visual Studio version build number in the format
+``<major>.<minor>.<date>.<build>``.
+
+.. include:: CMAKE_VS_VERSION_BUILD_NUMBER_COMPONENTS.txt
+
+See also the :variable:`CMAKE_GENERATOR_INSTANCE` variable.
diff --git a/Source/cmGlobalVisualStudioVersionedGenerator.cxx b/Source/cmGlobalVisualStudioVersionedGenerator.cxx
index 59f1dc2..415eb7c 100644
--- a/Source/cmGlobalVisualStudioVersionedGenerator.cxx
+++ b/Source/cmGlobalVisualStudioVersionedGenerator.cxx
@@ -521,6 +521,7 @@ bool cmGlobalVisualStudioVersionedGenerator::SetGeneratorInstance(
 {
   if (this->LastGeneratorInstanceString &&
       i == *(this->LastGeneratorInstanceString)) {
+    this->SetVSVersionVar(mf);
     return true;
   }
 
@@ -592,6 +593,8 @@ bool cmGlobalVisualStudioVersionedGenerator::SetGeneratorInstance(
                                        cmStateEnums::INTERNAL);
   }
 
+  this->SetVSVersionVar(mf);
+
   // The selected instance may have a different MSBuild than previously found.
   this->MSBuildCommandInitialized = false;
 
@@ -672,6 +675,13 @@ bool cmGlobalVisualStudioVersionedGenerator::ParseGeneratorInstance(
   return true;
 }
 
+void cmGlobalVisualStudioVersionedGenerator::SetVSVersionVar(cmMakefile* mf)
+{
+  if (cm::optional<std::string> vsVer = this->GetVSInstanceVersion()) {
+    mf->AddDefinition("CMAKE_VS_VERSION_BUILD_NUMBER", *vsVer);
+  }
+}
+
 bool cmGlobalVisualStudioVersionedGenerator::ProcessGeneratorInstanceField(
   std::string const& key, std::string const& value)
 {
diff --git a/Source/cmGlobalVisualStudioVersionedGenerator.h b/Source/cmGlobalVisualStudioVersionedGenerator.h
index 4c69aeb..45aca74 100644
--- a/Source/cmGlobalVisualStudioVersionedGenerator.h
+++ b/Source/cmGlobalVisualStudioVersionedGenerator.h
@@ -93,6 +93,7 @@ private:
   mutable cmVSSetupAPIHelper vsSetupAPIHelper;
 
   bool ParseGeneratorInstance(std::string const& is, cmMakefile* mf);
+  void SetVSVersionVar(cmMakefile* mf);
 
   std::string GeneratorInstance;
   std::string GeneratorInstanceVersion;
diff --git a/Tests/RunCMake/GeneratorInstance/DefaultInstance-stdout.txt b/Tests/RunCMake/GeneratorInstance/DefaultInstance-stdout.txt
new file mode 100644
index 0000000..078d96e
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/DefaultInstance-stdout.txt
@@ -0,0 +1 @@
+-- CMAKE_VS_VERSION_BUILD_NUMBER='[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+'
diff --git a/Tests/RunCMake/GeneratorInstance/DefaultInstance.cmake b/Tests/RunCMake/GeneratorInstance/DefaultInstance.cmake
index 9761f0c..5c5ec56 100644
--- a/Tests/RunCMake/GeneratorInstance/DefaultInstance.cmake
+++ b/Tests/RunCMake/GeneratorInstance/DefaultInstance.cmake
@@ -12,3 +12,5 @@ elseif(NOT IS_DIRECTORY "${CMAKE_GENERATOR_INSTANCE}")
     "which is not an existing directory.")
 endif()
 file(WRITE "${CMAKE_BINARY_DIR}/instance.txt" "${CMAKE_GENERATOR_INSTANCE}")
+
+message(STATUS "CMAKE_VS_VERSION_BUILD_NUMBER='${CMAKE_VS_VERSION_BUILD_NUMBER}'")