Windows: Clarify custom toolchain env variable requirements (issue #1403)

tools/gclient_hook.py

@@ -54,23 +54,60 @@ if platform == 'windows':
   # By default GN/GYP+Ninja on Windows expects Visual Studio to be installed on
   # the local machine. To build when Visual Studio is extracted to a directory
   # but not installed (e.g. via a custom toolchain):
+  #
+  # o Enable use of a custom toolchain on Windows.
+  #
   #   set WIN_CUSTOM_TOOLCHAIN=1
+  #
+  # o Used by tools/msvs_env.bat to configure the MSVS tools environment.
+  #   Should be set to "none" because VC variables for CEF will be set via
+  #   INCLUDE/LIB/PATH.
+  #   TODO(cef): Make INCLUDE/LIB/PATH values optional when
+  #   "%VS_ROOT%\VC\vcvarsall.bat" exists (use those values instead).
+  #
   #   set CEF_VCVARS=none
+  #
+  # o Used by the following scripts:
+  #   (a) build/vs_toolchain.py SetEnvironmentAndGetRuntimeDllDirs when
+  #   determining whether to copy VS runtime binaries to the output directory.
+  #   If GYP_MSVS_OVERRIDE_PATH exists then binaries will not be copied and
+  #   should instead be discoverable via the PATH env variable.
+  #   (b) build/toolchain/win/setup_toolchain.py _LoadToolchainEnv when
+  #   writing environment.* files that specify INCLUDE/LIB/PATH values. If
+  #   "%GYP_MSVS_OVERRIDE_PATH%\VC\vcvarsall.bat" exists then environment
+  #   variables will be derived from there and the specified INCLUDE/LIB/PATH
+  #   values, if any, will be ignored by Chromium. If this file does not exist
+  #   then the INCLUDE/LIB/PATH values are also required by Chromium.
+  #   TODO(cef): Rename to VS_PATH and VS_VERSION after Chromium cleans up GYP
+  #   dependencies.
+  #
+  #   set GYP_MSVS_OVERRIDE_PATH=<VS root directory>
   #   set GYP_MSVS_VERSION=<VS version>
-  #   set VS_ROOT=<VS root directory>
+  #
+  # o Used to configure GN and GYP arguments in this script.
+  #
   #   set VS_CRT_ROOT=<VS CRT root directory> (GN only)
   #   set SDK_ROOT=<Platform SDK root directory>
+  #
+  # o Used by various scripts as described above.
+  #
   #   set INCLUDE=<VS include paths>
-  #   set PATH=<VS executable paths>
   #   set LIB=<VS library paths>
+  #   set PATH=<VS executable paths>
+  #
+  # See tools/depot_tools/win_toolchain/package_from_installed.py for an example
+  # packaging script along with required directory contents and INCLUDE/LIB/PATH
+  # values.
+  #
   if bool(int(os.environ.get('WIN_CUSTOM_TOOLCHAIN', '0'))):
     required_vars = [
+      'CEF_VCVARS',
+      'GYP_MSVS_OVERRIDE_PATH',
       'GYP_MSVS_VERSION',
-      'VS_ROOT',
       'SDK_ROOT',
       'INCLUDE',
-      'PATH',
       'LIB',
+      'PATH',
     ]
     if use_gn:
       required_vars.append('VS_CRT_ROOT')
@@ -80,16 +117,9 @@ if platform == 'windows':
 
     custom_toolchain = True
 
-    # VC variables will be set via INCLUDE/PATH/LIB.
-    os.environ['CEF_VCVARS'] = 'none'
-
-    # Necessary to return correct VS version information via GetVSVersion in
-    # src/tools/gyp/pylib/gyp/msvs_emulation.py.
-    os.environ['GYP_MSVS_OVERRIDE_PATH'] = os.environ['VS_ROOT']
-
     if use_gn:
       # Windows custom toolchain requirements. See comments in gn_args.py.
-      gn_args['visual_studio_path'] = os.environ['VS_ROOT']
+      gn_args['visual_studio_path'] = os.environ['GYP_MSVS_OVERRIDE_PATH']
       gn_args['visual_studio_version'] = os.environ['GYP_MSVS_VERSION']
       gn_args['visual_studio_runtime_dirs'] = os.environ['VS_CRT_ROOT']
       gn_args['windows_sdk_path'] = os.environ['SDK_ROOT']

tools/gn_args.py

@@ -211,15 +211,12 @@ def ValidateArgs(args):
         msg('is_official_build=false + is_debug=true recommends is_win_fastlink=true')
 
     # Windows custom toolchain requirements.
-    # See tools/depot_tools/win_toolchain/package_from_installed.py for an
-    # example packaging script along with required directory contents and
-    # PATH/LIB/INCLUDE values.
     #
     # Required GN arguments:
     #   visual_studio_path="<path to VS root>"
     #     The directory that contains Visual Studio. For example, a subset of
     #     "C:\Program Files (x86)\Microsoft Visual Studio 14.0".
-    #   visual_studio_version="<vs version>"
+    #   visual_studio_version="<VS version>"
     #     The VS version. For example, "2015".
     #   visual_studio_runtime_dirs="<path to VS CRT>"
     #     The directory that contains the VS CRT. For example, the contents of
@@ -231,24 +228,46 @@ def ValidateArgs(args):
     #
     # Required environment variables:
     #   DEPOT_TOOLS_WIN_TOOLCHAIN=0
+    #   GYP_MSVS_OVERRIDE_PATH=<path to VS root, must match visual_studio_path>
+    #   GYP_MSVS_VERSION=<VS version, must match visual_studio_version>
     #   CEF_VCVARS=none
-    #   GYP_MSVS_OVERRIDE_PATH=<path to VS root>
-    #   PATH=<VS executable paths>
-    #   LIB=<VS library paths>
     #   INCLUDE=<VS include paths>
+    #   LIB=<VS library paths>
+    #   PATH=<VS executable paths>
+    #
+    # See comments in gclient_hook.py for environment variable usage.
+    #
     if visual_studio_path != '':
       assert visual_studio_version != '', 'visual_studio_path requires visual_studio_version'
       assert visual_studio_runtime_dirs != '', 'visual_studio_path requires visual_studio_runtime_dirs'
       assert windows_sdk_path != '', 'visual_studio_path requires windows_sdk_path'
+
       assert os.environ.get('DEPOT_TOOLS_WIN_TOOLCHAIN', '') == '0', \
         "visual_studio_path requires DEPOT_TOOLS_WIN_TOOLCHAIN=0 env variable"
+
+      msvs_path = os.environ.get('GYP_MSVS_OVERRIDE_PATH', '')
+      assert msvs_path == visual_studio_path and os.path.exists(msvs_path), \
+        "visual_studio_path requires matching GYP_MSVS_OVERRIDE_PATH env variable"
+
+      msvs_version = os.environ.get('GYP_MSVS_VERSION', '')
+      assert msvs_version == visual_studio_version, \
+        "visual_studio_version requires matching GYP_MSVS_VERSION env variable"
+
       assert os.environ.get('CEF_VCVARS', '') == 'none', \
         "visual_studio_path requires CEF_VCVARS=none env variable"
-      assert 'GYP_MSVS_OVERRIDE_PATH' in os.environ \
+
-        and 'PATH' in os.environ \
+      assert 'INCLUDE' in os.environ \
         and 'LIB' in os.environ \
-        and 'INCLUDE' in os.environ, \
+        and 'PATH' in os.environ, \
-        "visual_studio_path requires GYP_MSVS_OVERRIDE_PATH, PATH, LIB and INCLUDE env variables"
+        "visual_studio_path requires INCLUDE, LIB and PATH env variables"
+
+      # If "%VS_ROOT%\VC\vcvarsall.bat" exists then environment variables will
+      # be derived from there and the specified INCLUDE/LIB/PATH values, if any,
+      # will be ignored by Chromium. If this file does not exist then the
+      # INCLUDE/LIB/PATH values are also required by Chromium.
+      vcvars_path = os.path.join(msvs_path, 'VC', 'vcvarsall.bat')
+      if (os.path.exists(vcvars_path)):
+        msg('INCLUDE/LIB/PATH values will be derived from %s' % vcvars_path)
 
 def GetConfigArgs(args, is_debug, is_x64):
   """