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

1 files changed, 148 insertions, 77 deletions

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).