Update Windows toolchain documentation

Make some documentation relating to our Windows toolchain clearer. This
primarily involves updating the top-level comment of vs_toolchain.py
to better explain what each area does, and adjusting the formatting so
it's easier to read. Also fix some line lengths in the Windows build
instructions and add a better description of possible errors.

Bug: 362650376
Change-Id: Id97c7b1f9e3a0996f7a0e01ab698c91661bd454e
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5948186
Reviewed-by: Hans Wennborg <hans@chromium.org>
Commit-Queue: Devon Loehr <dloehr@google.com>
Reviewed-by: Nico Weber <thakis@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1371522}

build/vs_toolchain.py

@@ -18,38 +18,56 @@ import sys
 from gn_helpers import ToGNString
 
 # VS 2022 17.9.2 with 10.0.26100.1742 SDK with ARM64 libraries and UWP support.
-# See go/chromium-msvc-toolchain for instructions about how to update the
+# See go/win-toolchain-reference for instructions about how to update the
 # toolchain.
 #
 # When updating the toolchain, consider the following areas impacted by the
 # toolchain version:
 #
-# * //base/win/windows_version.cc NTDDI preprocessor check
-#   Triggers a compiler error if the available SDK is older than the minimum.
-# * SDK_VERSION in this file
-#   Must match the packaged/required SDK version.
-# * SDK_VERSION in build/toolchain/win/setup_toolchain.py.
-# * //build/config/win/BUILD.gn NTDDI_VERSION value
-#   Affects the availability of APIs in the toolchain headers.
-# * //docs/windows_build_instructions.md mentions of VS or Windows SDK.
-#   Keeps the document consistent with the toolchain version.
-# * //tools/win/setenv.py
+# * This file -- SDK_VERSION and TOOLCHAIN_HASH
+#   Determines which version of the toolchain is used by gclient. The hash
+#   is the name of the toolchain package (minus the zip) in gcloud, and
+#   SDK_VERSION should match the SDK version in that package.
+#
+# * This file -- MSVS_VERSIONS
+#   Records the supported versions of Visual Studio, in priority order.
+#
+# * This file -- MSVC_TOOLSET_VERSION
+#   Determines the expected MSVC toolset for each version of Visual Studio.
+#   The packaged toolset version can be seen at <package>/VC/redist/MSVC;
+#   there will be a folder named `v143` or similar.
+#
+# * build/toolchain/win/setup_toolchain.py -- SDK_VERSION
+#   Secondary specification of the SDK Version, to make sure we're loading the
+#   right one. Should always match SDK_VERSION in this file.
+#
+# * base/win/windows_version.cc -- NTDDI preprocessor check
+#   Forces developers to have a specific SDK version (or newer). Triggers a
+#   compiler error if the available SDK is older than the minimum.
+#
+# * build/config/win/BUILD.gn -- NTDDI_VERSION
+#   Specifies which SDK/WDK version is installed. Some of the toolchain headers
+#   check this macro to conditionally compile code.
+#
+# * build/config/win/BUILD.gn -- WINVER and _WIN32_WINNT
+#   Specify the minimum supported Windows version. These very rarely need to
+#   be changed.
+#
+# * tools/win/setenv.py -- list of accepted `vs_version`s
 #   Add/remove VS versions when upgrading to a new VS version.
-# * MSVC_TOOLSET_VERSION in this file
-#   Maps between Visual Studio version and MSVC toolset
-# * MSVS_VERSIONS in this file
-#   Records the packaged and default version of Visual Studio
+#
+# * docs/windows_build_instructions.md
+#   Make sure any version numbers in the documentation match the code.
+#
 TOOLCHAIN_HASH = '698eb5635a'
 SDK_VERSION = '10.0.26100.0'
 
-script_dir = os.path.dirname(os.path.realpath(__file__))
-json_data_file = os.path.join(script_dir, 'win_toolchain.json')
-
-# VS versions are listed in descending order of priority (highest first).
+# Visual Studio versions are listed in descending order of priority.
 # The first version is assumed by this script to be the one that is packaged,
 # which makes a difference for the arm64 runtime.
+# The second number is an alternate version number, only used in an error string
 MSVS_VERSIONS = collections.OrderedDict([
-    ('2022', '17.0'),  # Default and packaged version of Visual Studio.
+    ('2022', '17.0'),  # The VS version in our packaged toolchain.
     ('2019', '16.0'),
     ('2017', '15.0'),
 ])
@@ -62,6 +80,10 @@ MSVC_TOOLSET_VERSION = {
     '2017': 'VC141',
 }
 
+script_dir = os.path.dirname(os.path.realpath(__file__))
+json_data_file = os.path.join(script_dir, 'win_toolchain.json')
+
+
 def _HostIsWindows():
   """Returns True if running on a Windows host (including under cygwin)."""
   return sys.platform in ('win32', 'cygwin')

docs/windows_build_instructions.md

@@ -23,8 +23,8 @@ Are you a Google employee? See
 
 ### Visual Studio
 
-Chromium requires [Visual Studio 2022](https://learn.microsoft.com/en-us/visualstudio/releases/2022/release-notes) (>=17.0.0)
-to build. Visual Studio can also be used to debug Chromium.
+Chromium requires [Visual Studio 2022](https://learn.microsoft.com/en-us/visualstudio/releases/2022/release-notes)
+(>=17.0.0) to build. Visual Studio can also be used to debug Chromium.
 The clang-cl compiler is used but Visual Studio's header files, libraries, and
 some tools are required. Visual Studio Community Edition should work if its
 license is appropriate for you. You must install the "Desktop development with
@@ -54,23 +54,26 @@ Required
 * [Windows 11 SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/)
 version 10.0.26100.1742. This can be installed separately or by checking the
 appropriate box in the Visual Studio Installer.
-* (Windows 11) SDK Debugging Tools 10.0.26100.1742 or higher. This version of the
-Debugging tools is needed in order to support reading the large-page PDBs that
-Chrome uses to allow greater-than 4 GiB PDBs. This can be installed after the
-matching Windows SDK version is installed, from: Control Panel -> Programs and
-Features
+* (Windows 11) SDK Debugging Tools 10.0.26100.1742 or higher. This version of
+the Debugging tools is needed in order to support reading the large-page PDBs
+that Chrome uses to allow greater-than 4 GiB PDBs. This can be installed after
+the matching Windows SDK version is installed, from: Control Panel -> Programs
+and Features
 -> Windows Software Development Kit [version] -> Change -> Debugging Tools for
 Windows. If building on ARM64 Windows then you will need to manually copy the
 Debuggers\x64 directory from another machine because it does not get installed
 on ARM64 and is needed, whether you are building Chromium for x64 or ARM64 on
 ARM64.
 
-WARNING: On sufficiently old versions of Windows (1909 or earlier), dawn (or related
-components) may fail with a D3d-related error when using the 26100 SDK. This is because the
-d3dcompiler_47.dll file in the new SDK attempts to dynamically link versions of the Universal
-C Runtime which are not present by default on older systems. If you experience these errors,
-you can either update the UCRT on your system, or install the 22612 SDK and use the
-d3dcompiler_47.dll file included there, which statically links the UCRT.
+WARNING: On sufficiently old versions of Windows (1909 or earlier), dawn (or
+related components) may fail with a D3d-related error when using the 26100 SDK.
+This is because the d3dcompiler_47.dll file in the new SDK attempts to
+dynamically link versions of the Universal C Runtime which are not present by
+default on older systems. If you experience these errors, you can either update
+the UCRT on your system, or install the 22612 SDK and use the d3dcompiler_47.dll
+file included there, which statically links the UCRT.
+
+This problem may also manifest as a DLL failure to load `__CxxFrameHandler4`.
 
 ## git installation
 
@@ -158,9 +161,10 @@ skip this step.
   * `C:\Program Files\Git\usr\bin`
 ***
 
-Also, add a DEPOT_TOOLS_WIN_TOOLCHAIN environment variable in the same way, and set
-it to 0. This tells depot_tools to use your locally installed version of Visual
-Studio (by default, depot_tools will try to use a google-internal version).
+Also, add a DEPOT_TOOLS_WIN_TOOLCHAIN environment variable in the same way, and
+set it to 0. This tells depot_tools to use your locally installed version of
+Visual Studio (by default, depot_tools will try to use a google-internal
+version).
 
 You may also have to set variable `vs2022_install` to your installation path of
 Visual Studio 2022, like
@@ -316,8 +320,8 @@ binaries as well.
 
 #### Use Reclient
 
-In addition, Google employees should use Reclient, a distributed compilation system.
-Detailed information is available internally but the relevant gn arg is:
+In addition, Google employees should use Reclient, a distributed compilation
+system. Detailed information is available internally but the relevant gn arg is:
 * `use_remoteexec = true`
 
 Google employees can visit
@@ -395,7 +399,8 @@ will have a weighted time that is the same or similar to its elapsed time. A
 compile that runs in parallel with 999 other compiles will have a weighted time
 that is tiny.
 
-You can also generate these reports by manually running the script after a build:
+You can also generate these reports by manually running the script after a
+build:
 
 ```shell
 $ python depot_tools\post_build_ninja_summary.py -C out\Default