docs,Windows: update installation docs

In this change:
- Reword text in windows.md to use active voice
  instead of passive voice (so it's clear who the
  actor is).
- Update Bash script examples to use cmd.exe
  syntax.
- Remove outdated information, such as Bazel being
  an msys2 binary.
- Restructure list of requirements to be clearer
  and simpler.

RELNOTES: none
PiperOrigin-RevId: 166476459

3 files changed, 243 insertions, 134 deletions

diff --git a/site/docs/install-compile-source.md b/site/docs/install-compile-source.md
index 5ff5f7f4ff..7ff2baddc8 100644
--- a/site/docs/install-compile-source.md
+++ b/site/docs/install-compile-source.md
@@ -5,42 +5,80 @@ title: Compile Bazel from Source
 
 # <a name="compiling-from-source"></a>Compile Bazel from source
 
-## <a name="unix"></a> On Linux or macOS
+You can build Bazel from source following these steps:
 
-1. Ensure that you have OpenJDK 8 and python installed on your system.
-   For a system based on debian packages (e.g. Debian, Ubuntu), install
-   OpenJDK 8 and python by running the command `sudo apt-get install
-   openjdk-8-jdk python`.
+1.  Ensure that JDK 8 and Python are installed on your system.
+    *   On systems based on Debian packages (Debian, Ubuntu): you can install
+        OpenJDK 8 and Python by running the following command in a terminal:
 
-2. The standard way of compiling a release version of Bazel from source is to
-   use a distribution archive. Download `bazel-<VERSION>-dist.zip` from the
-   [release page](https://github.com/bazelbuild/bazel/releases) for the desired
-   version. We recommend to also verify the signature made by our
-   [release key](https://bazel.build/bazel-release.pub.gpg) 48457EE0.
-   The distribution archive also contains generated files in addition to the
-   versioned sources, so this step _cannot_ be short cut by using a checkout
-   of the source tree.
+        ```sh
+        sudo apt-get install openjdk-8-jdk python
+        ```
+    *   On Windows: you need additional software. See the [requirements
+        page](windows.html#requirements).
 
-3. Unzip the archive and call `bash ./compile.sh`; this will create a bazel
-   binary in `output/bazel`. This binary is self-contained, so it can be copied
-   to a directory on the PATH (such as `/usr/local/bin`) or used in-place.
+2.  Download and unpack Bazel's distribution archive.
 
-## <a name="windows"></a> On Windows
+    Download `bazel-<VERSION>-dist.zip` from the [release
+    page](https://github.com/bazelbuild/bazel/releases). We recommend to also
+    verify the signature made by our [release
+    key](https://bazel.build/bazel-release.pub.gpg) 48457EE0.
 
-Windows support is in beta. Known issues are [marked with label
-"Windows"](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3A%22category%3A+multi-platform+%3E+windows%22)
-on github issues.
+    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.
 
-Prerequisites:
+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`
 
-*    Follow the [Windows requirements](windows.md#requirements).
-*    Install [Visual C++ Build Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools)
-     or the full [Visual C++](https://www.visualstudio.com/) (as part of Visual
-     Studio; Community Edition is fine) with Windows SDK installed.
+    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.
 
-To build Bazel on Windows:
+## Note to Windows users
 
-*    Open the msys2 shell.
-*    Clone the [Bazel git repository](https://github.com/bazelbuild/bazel) as normal.
-*    Run ``compile.sh`` in Bazel directory.
-*    If all works fine, Bazel will be built at ``output\bazel.exe``.
+Make sure your machine meets the [requirements](windows.html).
+
+Depending on the Bazel version you compile:
+
+*   `bazel-0.5.4-dist.zip` and newer:
+
+    The compilation script uses Visual C++ to compile Bazel's C++ code. The
+    resulting Bazel binary is a native Windows binary and it's not linked to
+    `msys-2.0.dll`.
+
+*   `bazel-0.5.0-dist.zip` through `bazel-0.5.3-dist.zip`:
+
+    The compilation script uses GCC to build Bazel's C++ code. The resulting
+    Bazel binary is an msys binary so it is linked to `msys-2.0.dll`.
+
+    You can patch the compilation script to build Bazel using Visual C++ instead
+    of GCC, and avoid linking it to `msys-2.0.dll`. The patch is to replace
+    these lines in `./compile.sh`:
+
+    ```sh
+    if [[ $PLATFORM == "windows" ]]; then
+      EXTRA_BAZEL_ARGS="${EXTRA_BAZEL_ARGS-} --cpu=x64_windows_msys --host_cpu=x64_windows_msys"
+    fi
+    ```
+
+    with these lines:
+
+    ```sh
+    if [[ $PLATFORM == "windows" ]]; then
+      EXTRA_BAZEL_ARGS="${EXTRA_BAZEL_ARGS-} --cpu=x64_windows_msvc --host_cpu=x64_windows_msvc"
+    fi
+    ```
+
+*   `bazel-0.4.5-dist.zip` and earlier:
+
+    The compilation script uses GCC to compile Bazel's C++ code. The resulting
+    Bazel binary is an msys binary so it is linked to `msys-2.0.dll`. Bazel
+    cannot be built using Visual C++.
diff --git a/site/docs/install-windows.md b/site/docs/install-windows.md
index 2228e2b683..a9a83e3105 100644
--- a/site/docs/install-windows.md
+++ b/site/docs/install-windows.md
@@ -5,43 +5,43 @@ title: Installing Bazel on Windows
 
 # <a name="windows"></a>Install Bazel on Windows
 
-Windows support is in beta. Known issues are [marked with label "Windows"](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3A%22category%3A+multi-platform+%3E+windows%22)
-on GitHub.
+Bazel runs on 64 bit Windows 7 or higher.
 
-We currently support only 64 bit Windows 7 or higher and we compile Bazel as a
-MSYS2 binary.
+Known issues are [marked with label
+"Windows"](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3A%22category%3A+multi-platform+%3E+windows%22)
+on GitHub issues.
 
-Install Bazel on Windows using one of the following methods:
+To run Bazel on Windows, make sure your system meets the
+[requirements](windows.html#requirements).
 
-  * [Use Chocolatey](#install-on-windows-chocolatey)
-  * [Use the binary distribution](#download-binary-windows)
-  * [Compile Bazel from source](install-compile-source.md) -- make sure
-    your machine meets the [requirements](windows.md#requirements)
+You can get Bazel for Windows using one of the following methods:
 
+*   Download the binary distribution (recommended).
 
-## <a name="install-on-windows-chocolatey"></a>Install using Chocolatey
+    We provide binary versions on our [GitHub releases
+    page](https://github.com/bazelbuild/bazel/releases).
 
-You can install the unofficial package using the
-[chocolatey](https://chocolatey.org) package manager:
+    The installer contains only the Bazel binary. You'll need additional
+    software (e.g. msys2 shell) and some setup in your environment to run Bazel.
+    You can find these on the [Windows requirements page](windows.html).
 
-```sh
-choco install bazel
-```
+*   Use Chocolatey.
 
-This will install the latest available version of Bazel, and dependencies.
+    You can install the Bazel package using the
+    [Chocolatey](https://chocolatey.org) package manager:
 
-This package is experimental. Please provide feedback to `@petemounce` in GitHub
-issue tracker. See the [Chocolatey installation and package
-maintenance](https://bazel.build/windows-chocolatey-maintenance.html) guide for
-more information.
+    ```sh
+    choco install bazel
+    ```
 
+    This command will install the latest available version of Bazel and most of
+    its dependencies, such as the msys2 shell. This will not install Visual C++
+    though.
 
-## <a name="download-binary-windows"></a>Install using the binary distribution
+    See [Chocolatey installation and package maintenance
+    guide](https://bazel.build/windows-chocolatey-maintenance.html) for more
+    information about the Chocolatey package.
 
-We provide binary versions on our
-<a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a>
+*   [Compile Bazel from source](install-compile-source.html).
 
-The installer contains only the Bazel binary. You'll need additional software
-(e.g. msys2 shell of the right version) and some setup in your environment to
-run Bazel. See these requirements on our
-[Windows page](windows.md#requirements).
+## Next: see [Using Bazel on Windows](windows.html#using)
diff --git a/site/docs/windows.md b/site/docs/windows.md
index a93de21924..9f05f33a03 100644
--- a/site/docs/windows.md
+++ b/site/docs/windows.md
@@ -5,113 +5,184 @@ title: Windows
 
 # Using Bazel on Windows
 
-Windows support is in beta. Known issues are [marked with label
+Bazel runs on 64 bit Windows 7 or higher. Known issues are [marked with label
 "Windows"](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3A%22category%3A+multi-platform+%3E+windows%22)
-on github issues.
+on GitHub issues.
 
-We currently support only 64 bit Windows 7 or higher and we compile Bazel as a
-msys2 binary.
+Bazel is a native Windows binary. Run it from the Windows Command Prompt
+(`cmd.exe`) or from PowerShell.
 
 ## <a name="requirements"></a>Requirements
 
-Before you can compile or run Bazel, you will need to set some environment
-variables:
+*   Python 2.7 or later.
+*   [msys2 shell](https://msys2.github.io/).
 
-```bash
-export JAVA_HOME="$(ls -d C:/Program\ Files/Java/jdk* | sort | tail -n 1)"
-export BAZEL_SH=c:/msys64/usr/bin/bash.exe
-```
+    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:\msys64\usr\bin\bash.exe
+    ```
+
+*   Several msys2 packages.
+
+    Run the following command in the msys2 shell to install them:
+
+    ```bash
+    pacman -Syuu git curl zip unzip
+    ```
+
+*   Java JDK 8.
 
-If you have another tool that vendors msys2 (such as msysgit), then
-``c:\msys64\usr\bin`` must appear in your ``PATH`` *before* entries for
-those tools.
+    JDK 7 and 9 are not supported.
 
-Similarly, if you have [bash on Ubuntu on
-Windows](https://msdn.microsoft.com/en-gb/commandline/wsl/about) installed, you
-should make sure ``c:\msys64\usr\bin`` appears in ``PATH`` *before*
-``c:\windows\system32``, because otherwise Windows' ``bash.exe`` is used before
-msys2's.
+    If you downloaded a binary distribution of Bazel (see [installing Bazel on
+    Windows](install-windows.html)), the binary has JDK 8 embedded by default.
 
-To **run** Bazel (even pre-built binaries), you will need:
+*   If you built Bazel from source: set the `JAVA_HOME` environment variable to
+    the JDK's directory.
 
-*    Java JDK 8 or later.
-*    Python 2.7 or later.
-*    [msys2 shell](https://msys2.github.io/).
-*    Several msys2 packages. Use the ``pacman`` command to install them:
+    For example in the Windows Command Prompt (`cmd.exe`):
 
-     ```
-     pacman -Syuu git curl zip unzip
-     ```
+    ```
+    set JAVA_HOME=C:\Program Files\Java\jdk1.8.0_112
+    ```
+
+    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).
+
+Environment variables you set in the Windows Command Prompt (`cmd.exe`) are only
+set in that command prompt session. If you start a new `cmd.exe`, you need to
+set the variables again. To always set the variables when `cmd.exe` starts, you
+can add them to the User variables or System variables in the `Control Panel >
+System Properties > Advanced > Environment Variables...` dialog box.
 
 ## <a name="install"></a>Installation
 
-See [Install Bazel on Windows](install-windows.md) for installation instructions.
+See [Install Bazel on Windows](install-windows.html) for installation
+instructions.
 
 ## <a name="using"></a>Using Bazel on Windows
 
-Bazel now supports building C++, Java and Python targets on Windows.
+The first time you build any target, Bazel auto-configures the location of
+Python and the Visual C++ compiler. If you need to auto-configure again, run
+`bazel clean` then build a target.
 
 ### Build C++
 
-To build C++ targets, you will need:
-
-* [Visual Studio](https://www.visualstudio.com/)
-<br/>We are using MSVC as the native C++ toolchain, so please ensure you have Visual
-Studio installed with the `Visual C++ > Common Tools for Visual C++` and
-`Visual C++ > Microsoft Foundation Classes for C++` features.
-(which is NOT the default installation type of Visual Studio).
-You can set `BAZEL_VS` environment variable to tell Bazel
-where Visual Studio is, otherwise Bazel will try to find the latest version installed.
-<br/>For example: `export BAZEL_VS="C:/Program Files (x86)/Microsoft Visual Studio 14.0"`
-
-* [Python](https://www.python.org/downloads/)
-<br/>Both Python 2 and Python 3 are supported.
-Currently, we use Python wrapper scripts to call the actual MSVC compiler, so
-please make sure Python is installed and its location is added into PATH.
-It's also a good idea to set `BAZEL_PYTHON` environment variable to tell Bazel
-where Python is.
-<br/>For example: `export BAZEL_PYTHON=C:/Python27/python.exe`
-
-Bazel will auto-configure the location of Visual Studio and Python at the first
-time you build any target.
-If you need to auto-configure again, just run `bazel clean` then build a target.
-
-If everything is set up, you can build C++ target now!
-
-```bash
-bazel build examples/cpp:hello-world
-./bazel-bin/examples/cpp/hello-world.exe
-bazel run examples/cpp:hello-world
-```
+To build C++ targets, you need:
+
+*   The Visual C++ compiler.
+
+    You can install it in one of the following ways:
+
+    *   Install [Visual Studio](https://www.visualstudio.com/) (Community
+        Edition is enough) with Visual C++.
+
+        Make sure to also install the `Visual C++ > Common Tools for Visual C++`
+        and `Visual C++ > Microsoft Foundation Classes for C++` features. These
+        features are not installed by default.
+
+    *   Install the [Visual C++ Build
+        Tools](http://landinghub.visualstudio.com/visual-cpp-build-tools).
+
+*   The `BAZEL_VS` or `BAZEL_VC` environment variable.
+
+    Bazel tries to locate the C++ compiler the first time you build any
+    target. To tell Bazel where the compiler is, you can set one of the
+    following environment variables:
+
+    *   `BAZEL_VS` storing the Visual Studio installation directory
+
+    *   `BAZEL_VC` storing the Visual C++ Build Tools installation directory
+
+    Setting one of these variables is enough. For example:
+
+    ```
+    set BAZEL_VS=C:\Program Files (x86)\Microsoft Visual Studio 14.0
+    ```
+
+    or
+
+    ```
+    set BAZEL_VC=C:\Program Files (x86)\Microsoft Visual Studio\2017\BuildTools\VC
+    ```
 
-However, with Bazel version prior to 0.5.0, MSVC
-toolchain is not default on Windows, you should use flag
-`--cpu=x64_windows_msvc` to enable it like this:
+*   The [Windows
+    SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-10-sdk).
+
+    The Windows SDK contains header files and libraries you need when building
+    Windows applications, including Bazel itself.
+
+If everything is set up, you can build a C++ target now!
+
+Try building a target from one of our [sample
+projects](https://github.com/bazelbuild/bazel/tree/master/examples):
 
-```bash
-bazel build --cpu=x64_windows_msvc examples/cpp:hello-world
+```
+C:\projects\bazel> bazel build //examples/cpp:hello-world
+
+C:\projects\bazel> bazel-bin\examples\cpp\hello-world.exe
 ```
 
 ### Build Java
 
-Building Java targets works well on Windows, no special configuration is needed.
-Just try:
+There's no setup necessary.
+
+On Windows, Bazel builds three output files for `java_binary` rules:
+
+*   a `.jar` file
+*   a shell script that can set up the environment for the JVM and run the
+    binary
+*   a `.cmd` file (a batch script) that can call Bash with the aforementioned
+    shell script.
+
+Try building a target from one of our [sample
+projects](https://github.com/bazelbuild/bazel/tree/master/examples):
 
-```bash
-bazel build examples/java-native/src/main/java/com/example/myproject:hello-world
-./bazel-bin/examples/java-native/src/main/java/com/example/myproject/hello-world
-bazel run examples/java-native/src/main/java/com/example/myproject:hello-world
+```
+C:\projects\bazel> bazel build //examples/java-native/src/main/java/com/example/myproject:hello-world
+
+C:\projects\bazel> bazel-bin\examples\java-native\src\main\java\com\example\myproject\hello-world.cmd
 ```
 
 ### Build Python
 
-On Windows, we build a self-extracting zip file for executable Python targets, you can even use
-`python ./bazel-bin/path/to/target` to run it in native Windows command line (cmd.exe).
-See more details in this [design doc](https://bazel.build/designs/2016/09/05/build-python-on-windows.html).
+To build Python targets, you need:
+
+*   The [Python interpreter](https://www.python.org/downloads/)
+
+    Both Python 2 and Python 3 are supported.
+
+    Bazel tries to locate the Python runtime the first time you build any
+    target. To tell Bazel where Python is, you can set the `BAZEL_PYTHON`
+    environment variable to the Python interpreter's path. For example:
+
+    ```
+    set BAZEL_PYTHON=C:\Python27\python.exe
+    ```
+
+On Windows, Bazel builds two output files for `py_binary` rules:
+
+*   a self-extracting zip file
+*   a batch script that can execute the Python interpreter with the
+    self-extracting zip file as the argument
+
+You can either run the batch script (it has a `.cmd` extension) or you can run
+Python with the self-extracting zip file as the argument.
+
+Try building a target from one of our [sample
+projects](https://github.com/bazelbuild/bazel/tree/master/examples):
 
-```bash
-bazel build examples/py_native:bin
-./bazel-bin/examples/py_native/bin
-python ./bazel-bin/examples/py_native/bin    # This works in both msys and cmd.exe
-bazel run examples/py_native:bin
 ```
+C:\projects\bazel> bazel build //examples/py_native:bin
+
+C:\projects\bazel> bazel-bin\examples\py_native\bin.cmd
+
+C:\projects\bazel> python bazel-bin\examples\py_native\bin
+```
+
+If you are interested in details about how Bazel builds Python targets on
+Windows, check out this [design
+doc](https://bazel.build/designs/2016/09/05/build-python-on-windows.html).