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
+# * This file -- SDK_VERSION and TOOLCHAIN_HASH
-#   Triggers a compiler error if the available SDK is older than the minimum.
+#   Determines which version of the toolchain is used by gclient. The hash
-# * SDK_VERSION in this file
+#   is the name of the toolchain package (minus the zip) in gcloud, and
-#   Must match the packaged/required SDK version.
+#   SDK_VERSION should match the SDK version in that package.
-# * SDK_VERSION in build/toolchain/win/setup_toolchain.py.
+#
-# * //build/config/win/BUILD.gn NTDDI_VERSION value
+# * This file -- MSVS_VERSIONS
-#   Affects the availability of APIs in the toolchain headers.
+#   Records the supported versions of Visual Studio, in priority order.
-# * //docs/windows_build_instructions.md mentions of VS or Windows SDK.
+#
-#   Keeps the document consistent with the toolchain version.
+# * This file -- MSVC_TOOLSET_VERSION
-# * //tools/win/setenv.py
+#   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
+# * docs/windows_build_instructions.md
-# * MSVS_VERSIONS in this file
+#   Make sure any version numbers in the documentation match the code.
-#   Records the packaged and default version of Visual Studio
+#
 TOOLCHAIN_HASH = '698eb5635a'
 SDK_VERSION = '10.0.26100.0'
 
-script_dir = os.path.dirname(os.path.realpath(__file__))
+# Visual Studio versions are listed in descending order of priority.
-json_data_file = os.path.join(script_dir, 'win_toolchain.json')
-
-# VS versions are listed in descending order of priority (highest first).
 # 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)
+Chromium requires [Visual Studio 2022](https://learn.microsoft.com/en-us/visualstudio/releases/2022/release-notes)
-to build. Visual Studio can also be used to debug Chromium.
+(>=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
+* (Windows 11) SDK Debugging Tools 10.0.26100.1742 or higher. This version of
-Debugging tools is needed in order to support reading the large-page PDBs that
+the Debugging tools is needed in order to support reading the large-page PDBs
-Chrome uses to allow greater-than 4 GiB PDBs. This can be installed after the
+that Chrome uses to allow greater-than 4 GiB PDBs. This can be installed after
-matching Windows SDK version is installed, from: Control Panel -> Programs and
+the matching Windows SDK version is installed, from: Control Panel -> Programs
-Features
+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
+WARNING: On sufficiently old versions of Windows (1909 or earlier), dawn (or
-components) may fail with a D3d-related error when using the 26100 SDK. This is because the
+related components) may fail with a D3d-related error when using the 26100 SDK.
-d3dcompiler_47.dll file in the new SDK attempts to dynamically link versions of the Universal
+This is because the d3dcompiler_47.dll file in the new SDK attempts to
-C Runtime which are not present by default on older systems. If you experience these errors,
+dynamically link versions of the Universal C Runtime which are not present by
-you can either update the UCRT on your system, or install the 22612 SDK and use the
+default on older systems. If you experience these errors, you can either update
-d3dcompiler_47.dll file included there, which statically links the UCRT.
+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
+Also, add a DEPOT_TOOLS_WIN_TOOLCHAIN environment variable in the same way, and
-it to 0. This tells depot_tools to use your locally installed version of Visual
+set it to 0. This tells depot_tools to use your locally installed version of
-Studio (by default, depot_tools will try to use a google-internal version).
+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.
+In addition, Google employees should use Reclient, a distributed compilation
-Detailed information is available internally but the relevant gn arg is:
+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