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

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

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.

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.

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.

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

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;

Tests/RunCMake/GeneratorInstance/DefaultInstance-stdout.txt

@@ -0,0 +1 @@
+-- CMAKE_VS_VERSION_BUILD_NUMBER='[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+'

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}'")