Add README.md for win_toolchain

I started to build a package for setting up a VS2015 bot, and realized
I didn't really remember how the toolchain setup worked. So I wrote
a readme for this directory.

I see I will live to regret putting way too many "2013"s in various
places in these scripts. :/

R=dpranke@chromium.org
BUG=492774

Review URL: https://codereview.chromium.org/1150033010

git-svn-id: svn://svn.chromium.org/chrome/trunk/tools/depot_tools@295437 0039d316-1c4b-4281-b951-d872f2087c98

win_toolchain/README.md

@@ -0,0 +1,74 @@
+Automatic updates of the Windows toolchain
+==========================================
+
+## On the consumer side, e.g. in Chromium src.git:
+
+- `vs_toolchain.py update` is called early during `DEPS`. `Update()` asks
+  depot\_tools to put in place a particular version of the toolchain (whatever
+  src will currently build with). src provides an output .json file, where
+  `Update()` saves relevant information about the toolchain, the paths, version
+  numbers, etc.
+- Later in `DEPS`, `build/gyp_chromium` uses
+  `vs_toolchain:SetEnvironmentAndGetRuntimeDllDirs()`, which loads the .json
+  file, and uses it to set a few `GYP_` variables and update the `PATH` to
+  include CRT runtime directories (see below).
+- Then, `gyp_chromium` runs gyp generation.
+- Finally, it uses `vs_toolchain` again to copy runtime dlls to the output
+  directories.
+
+The reason the logic was split between `depot_tools` and `src` was because at
+some point, the bots had insufficient hard drive space and if there were > 1
+build directories (say, if a build machine handled the Release and Debug builds
+for a given configuration) then the duplication of the toolchain in both trees
+would cause the bot to run out of disk space.
+
+## On the depot\_tools side:
+
+`get_toolchain_if_necessary.py` takes an output .json file (per above) and an
+input SHA1. It tries to confirm that the user is probably a Google employee (or
+a bot) to encourage them to use the automatic toolchain rather than using a
+system installed one. It then uses gsutil to download the zip corresponding to
+the hash. This requires authentication with @google.com credentials, so it walks
+the user through that process if necessary.
+
+(Previously in the VS2010 and early VS2013 timeframe, we also supported building
+with Express editions of VS. Along with `toolchain2013.py` this script dealt
+with all the complexity of acquiring the Express ISO, SDK bits, patches, etc.
+and applying them all in the correct sequence. However, Express no longer works,
+and Community is not too hard to install properly, so we just let the user do
+that. The primary benefit of having an automatically updated toolchain is that
+it works for bots, allows changes to the toolchain to be tryjob'd, reduces
+Infra/Labs work, and ensures that devs match bots.)
+
+For the above convoluted reason `get_toolchain_if_necessary` uses
+`toolchain2013.py` to extract the zip file, but the majority of the code in
+there is no longer used and what remains should be inlined into
+`get_toolchain_if_necessary` in the future.
+
+When the zip file is extracted, the mtimes of all the files, and the sha1 of the
+entire tree are saved to a local file. This allows future updates to compare
+whether the bits of the toolchain currently on disk are different than expected
+(the passed in SHA1), and if so, replace it with a toolchain with the correct
+SHA1. This is probably a bit more complicated than necessary, and again dates
+back to when the toolchain was assembled from many pieces. It could probably
+just write a stamp file with the SHA1, or just a version number, and trust that
+on future runs.
+
+Finally, it copies the json file to the location that the caller requested (the
+json file is generated during the unzip/acquire process in `toolchain2013.py`).
+
+## Building a <sha1>.zip
+
+Ignoring the `toolchain2013.py` steps to acquire a toolchain automatically from
+bits for Express, the procedure is roughly:
+- Get a clean Windows VM,
+- Install Visual Studio 2013 with updates as you want it,
+- Install Windows 8.1 SDK,
+- Run `package_from_installed.py`,
+- Upload the resulting zip file to the chrome-wintoolchain GS bucket.
+
+That script first builds a zip file of the required pieces, including generating
+a batch file corresponding to `SetEnv.cmd` or `vcvarsall.bat`. It then extracts
+that zip to a temporary location and calculates the SHA1 in the same way that
+the `depot_tools` update procedure would do, so that it knows what to rename the
+zip file to.