docs: rewrite Windows install and bootstrap guide

Simplify the installation and bootstrapping
instruction for Windows.

Fixes https://github.com/bazelbuild/bazel/issues/4784

Change-Id: I564cd6136ac5b2f0661665765b9bb488e23fe6b0

Closes #5152.

Change-Id: I564cd6136ac5b2f0661665765b9bb488e23fe6b0
PiperOrigin-RevId: 195382164

2 files changed, 113 insertions, 84 deletions

diff --git a/site/docs/install-compile-source.md b/site/docs/install-compile-source.md
index 31d63eddf2..8bdb85a4be 100644
--- a/site/docs/install-compile-source.md
+++ b/site/docs/install-compile-source.md
@@ -5,19 +5,44 @@ title: Compiling Bazel from Source
 
 # <a name="compiling-from-source"></a>Compiling Bazel from Source (bootstrapping)
 
-You can build Bazel from source without using an existing Bazel binary by
-doing the following:
+You can build Bazel from source without using an existing Bazel binary.
 
-### 1.  Ensure that JDK 8, Python, Bash, zip, and the usual C++ build toolchain are installed on your system.
+### 1.  Install the prerequisites
 
-*   On systems based on Debian packages (Debian, Ubuntu): you can install
-OpenJDK 8 and Python by running the following command in a terminal:
+#### Debian-based Unix systems
+
+To compile Bazel on Debian-based systems such as Ubuntu or Debian, ensure that
+JDK 8, Python, bash, zip, and the usual C++ build toolchain components are
+installed on your system.
+
+For example, you can install them using the following command:
 
 ```sh
-   sudo apt-get install build-essential openjdk-8-jdk python zip
+sudo apt-get install build-essential openjdk-8-jdk python zip
 ```
-*   On Windows: you need additional software and the right OS version.
-See the [Windows page](windows.html).
+
+#### Windows
+
+To compile Bazel on Windows, install the following supporting software:
+
+*   [MSYS2 shell](https://msys2.github.io/)
+
+*   **The required MSYS2 packages.** Run the following command in the MSYS2
+    shell:
+    ```sh
+    pacman -Syu zip unzip
+    ```
+
+*   **The Visual C++ compiler.** Install the Visual C++ compiler either as part
+    of Visual Studio 2015 or newer, or by installing the latest [Build Tools
+    for Visual Studio 2017](https://aka.ms/BuildTools).
+
+*   **JDK 8.** You must install version 8 of the JDK. Versions other than 8 are
+    *not* supported.
+
+*   **Python**. Versions 2 and 3 are supported. You *must* install the
+    Windows-native version (downloadable from https://www.python.org). Versions
+    installed via pacman in MSYS2 will not work.
 
 ### 2.  Download and unpack Bazel's distribution archive.
 
@@ -29,33 +54,66 @@ We recommend to also verify the signature made by our [release key](https://baze
 
 The distribution archive contains generated files in addition to the versioned sources, so this step _cannot_ be short cut by checking out the source tree.
 
-### 3.  Build Bazel using `./compile.sh`.
-*   On Unix-like systems (e.g. Ubuntu, macOS), do the following steps in a shell session:
-    1.  `cd` into the directory where you unpacked the distribution archive
-    2.  run `bash ./compile.sh`
-*   On Windows, do following steps in the MSYS2 shell:
-    1.  `cd` into the directory where you unpacked the distribution archive
-    2.  run `./compile.sh`
+### 3.  Bootstrap Bazel
 
-Once you have a Bazel binary, you no longer need to use the MSYS2 shell.
-You can run Bazel from the Command Prompt (`cmd.exe`) or PowerShell.
+#### Unix-like systems
 
-The output will be `output/bazel` on Unix-like systems (e.g. Ubuntu, macOS)
-and `output/bazel.exe` on Windows. This is a self-contained Bazel binary.
-You can copy it to a directory on the `PATH` (such as `/usr/local/bin` on
-Linux) or use it in-place.
+On Unix-like systems such as Ubuntu or macOS, do the following:
 
-### (on Windows): set the `JAVA_HOME` environment variable to the JDK's directory.
+1.  Open a shell or Terminal window.
 
-For example in the Windows Command Prompt (`cmd.exe`):
+2.  Change into the directory where you unpacked the distribution archive.
 
-```
-set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_112
-```
+3.  Run the compilation script: `bash ./compile.sh`.
+
+The compiled output is placed into `output/bazel`. This is a self-contained
+Bazel binary, without an embedded JDK. You can copy it to a directory in the
+`PATH` variable (such as `/usr/local/bin` on Linux) or use it in-place.
+
+#### Windows
+
+1.  Open the MSYS2 shell.
+
+2.  Set the following environment variables:
+
+    *   `BAZEL_VS` or `BAZEL_VC`: Set to the path to the Visual Studio directory
+         or to the Visual C++ directory, respectively. Setting one of them is
+         enough.
+
+    *   `BAZEL_SH`: Set to the path of the MSYS2 `bash.exe`.
+
+        Do not set this to `C:\Windows\System32\bash.exe`. (You have that file
+        if you installed Windows Subsystem for Linux.) Bazel does not support
+        this version of `bash.exe`.
+
+    *   `PATH`: Add the Python directory.
+
+    *   `JAVA_HOME`: Set to the JDK directory.
+
+    For example:
+    ```sh
+    export BAZEL_VS="C:/Program Files (x86)/Microsoft Visual Studio/2017/BuildTools"
+    export BAZEL_SH="C:/msys64/usr/bin/bash.exe"
+    export PATH="/c/python27:$PATH"
+    export JAVA_HOME="C:/Program Files/Java/jdk1.8.0_112"
+    ```
+
+    or
+
+    ```sh
+    export BAZEL_VC="C:/Program Files (x86)/Microsoft Visual Studio/2017/BuildTools/VC"
+    export BAZEL_SH="c:/msys64/usr/bin/bash.exe"
+    export PATH="/c/python27:$PATH"
+    export JAVA_HOME="C:/Program Files/Java/jdk1.8.0_112"
+    ```
+
+3.  Change into the directory where you unpacked the distribution archive.
+
+4.  Run the compilation script: `./compile.sh`
 
-**Note**: do not use quotes (") around the path like you would on Unix.
-Windows doesn't need them and they may confuse Bazel.
+The compiled output is placed into `output/bazel.exe`. This is a self-contained
+Bazel binary, without an embedded JDK. You can copy it to a directory within the
+`%PATH%` variable or use it in-place.
 
-This step is not required if you downloaded a binary distribution of Bazel
-or installed Bazel using Chocolatey. See [installing Bazel on
-Windows](install-windows.html).
+You don't need to run Bazel from the MSYS2 shell. You can run Bazel from the
+Command Prompt (`cmd.exe`) or PowerShell.
diff --git a/site/docs/install-windows.md b/site/docs/install-windows.md
index 18cc589e29..ca8f1bd47a 100644
--- a/site/docs/install-windows.md
+++ b/site/docs/install-windows.md
@@ -5,69 +5,40 @@ title: Installing Bazel on Windows
 
 # <a name="windows"></a>Installing Bazel on Windows
 
-Supported Windows platforms:
+### Prerequisites
 
-*   64 bit Windows 7 or higher, or equivalent Windows Server versions.
+*   64 bit Windows 7 or newer, or <a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724832(v=vs.85).aspx">equivalent Windows Server versions</a>
 
-_Check
-<a href="https://msdn.microsoft.com/en-us/library/windows/desktop/ms724832(v=vs.85).aspx">Microsoft's
-Operating System Version table</a> to see if your OS is supported._
-
-### 1. Install prerequisites (if not already installed)
-
-*   Python 2.7 or later.
-
-    Use the Windows-native Python version. Do not use Python that comes with the
-    MSYS2 shell or that you installed in MSYS using Pacman because it doesn't
-    work with Bazel.
-
-*   [MSYS2 shell](https://msys2.github.io/).
-
-    You also need to set the `BAZEL_SH` environment variable to point to
-    `bash.exe`. For example in the Windows Command Prompt (`cmd.exe`):
-
-    ```
-    set BAZEL_SH=C:\tools\msys64\usr\bin\bash.exe
-    ```
-
-    **Note**: do not use quotes (") around the path like you would on Unixes.
-    Windows doesn't need them and it may confuse Bazel.
-
-*   Several MSYS2 packages.
-
-    Run the following command in the MSYS2 shell to install them:
-
-    ```bash
-    pacman -Syuu git curl zip unzip
-    ```
+*   [MSYS2 shell](https://msys2.github.io/)
 
 *   [Microsoft Visual C++ Redistributable for Visual Studio 2015](https://www.microsoft.com/en-us/download/details.aspx?id=48145)
 
-    This may already be installed on your system.
+    These are common DLLs that Bazel needs. You may already have them installed.
 
-### 2. Install Bazel on Windows using one of the following methods:
+### Getting Bazel
 
-*   [Download the binary (recommended)](#download-the-binary-recommended)
-*   [Install using Chocolatey](#install-using-chocolatey)
-*   [Compile Bazel from source](install-compile-source.html)
+Download Bazel for Windows from our
+[GitHub releases page](https://github.com/bazelbuild/bazel/releases).
+Look for `bazel-<version>-windows-x86_64.exe`, e.g. `bazel-0.13.0-windows-x86_64.exe`.
 
-#### Download the binary (recommended)
+**Tip:** For convenience, rename the downloaded binary to `bazel.exe` and move it to a directory
+that's on your `%PATH%` or add its directory to your `%PATH%`. This way you can run Bazel by
+typing `bazel` in any directory, without typing out the full path.
 
-Go to Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases)
-and download the Windows binary<sup>1</sup>: `bazel-<version>-installer-windows-x86_64.sh`.
-
-For convenience, move the binary to a directory that's on your `%PATH%`. This
-way you can run Bazel by typing `bazel` in any directory, without typing out the
-full path. That said, you may put the binary anywhere on your filesystem.
+**Note:** Bazel includes an embedded JDK so you don't need to install one separately. If you want
+to download Bazel without an embedded JDK, look for `bazel-<version>-without-jdk-windows-x86_64.exe`
+on the release page. To use it, you must install JDK 8 separately (older or newer versions are not
+supported), and set the `JAVA_HOME` environment variable, e.g.:
+```
+set JAVA_HOME=c:\Program Files\Java\jdk1.8.0_171
+```
+Pay attention not to use quotes (") around the path (like you would on Unixes).
 
-After you download the binary, you'll need additional
-software and some setup in your environment to run Bazel. For details, see the
-[Windows requirements](windows.html).
+### Other ways to get Bazel
 
-**Note:** Bazel includes an embedded JDK, which can be used even if a JDK is already
-installed. `bazel-<version>-without-jdk-installer-linux-x86_64.sh` is a version of the installer
-without an embedded JDK. Only use this installer if you already have JDK 8 installed. Later JDK
-versions are not supported.
+You can also get Bazel by:
+*   [Installing Bazel using Chocolatey](#install-using-chocolatey)
+*   [Compiling Bazel from source](install-compile-source.html)
 
 #### Install using Chocolatey
 
@@ -78,7 +49,7 @@ package manager:
 choco install bazel
 ```
 
-This command will install the latest available version of Bazel and most of
+This command will install the latest available version of Bazel and
 its dependencies, such as the MSYS2 shell. This will not install Visual C++
 though.