Install guide: add known issues; Windows doc fixes

Add a list of known issues (currently only on
Windows) when trying to build from source.

Also update the Windows run/compile requirements.

Motivated by:
https://github.com/bazelbuild/bazel/issues/2431
https://github.com/bazelbuild/bazel/issues/2449

--
PiperOrigin-RevId: 146091804
MOS_MIGRATED_REVID=146091804

2 files changed, 68 insertions, 22 deletions

diff --git a/site/versions/master/docs/install.md b/site/versions/master/docs/install.md
index 0a6f9e5b0c..957d581219 100644
--- a/site/versions/master/docs/install.md
+++ b/site/versions/master/docs/install.md
@@ -224,7 +224,7 @@ label "Windows"](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aop
 on GitHub issues.
 
 We currently support only 64 bit Windows 7 or higher and we compile Bazel as a
-msys2 binary.
+MSYS2 binary.
 
 Install Bazel on Windows using one of the following methods:
 
@@ -256,8 +256,8 @@ We provide binary versions on our
 <a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a>
 
 This is merely the Bazel binary. You'll need additional software (e.g. msys2
-shell) and some setup in your environment to run Bazel. See these requirements
-on our [Windows page](windows.md#requirements).
+shell of the right version) and some setup in your environment to run Bazel.
+See these requirements on our [Windows page](windows.md#requirements).
 
 
 ## <a name="compiling-from-source"></a>Compiling from source
@@ -277,6 +277,41 @@ bazel binary in `output/bazel`. This binary is self-contained,
 so it can be copied to a directory on the PATH (e.g.,
 `/usr/local/bin`) or used in-place.
 
+###<a name="compiling-from-source-issues"></a>Known issues when compiling from source
+
+**On Windows:**
+
+* version 0.4.4 and below: `compile.sh` may fail right after start with an error
+  like this:
+
+    ```
+    File not found - *.jar
+    no error prone jar
+    ```
+
+    Workaround is to run this (and add it to your `~/.bashrc`):
+
+    ```
+    export PATH="/bin:/usr/bin:$PATH"
+    ```
+
+* version 0.4.3 and below: `compile.sh` may fail fairly early with many Java
+  compilation errors. The errors look similar to:
+
+    ```
+    C:\...\bazel_VR1HFY7x\src\com\google\devtools\build\lib\remote\ExecuteServiceGrpc.java:11: error: package io.grpc.stub does not exist
+    import static io.grpc.stub.ServerCalls.asyncUnaryCall;
+                              ^
+    ```
+
+    This is caused by a bug in one of the bootstrap scripts
+    (`scripts/bootstrap/compile.sh`). Manually apply this one-line fix if you want
+    to build Bazel purely from source (without using an existing Bazel binary):
+    [5402993a5e9065984a42eca2132ec56ca3aa456f]( https://github.com/bazelbuild/bazel/commit/5402993a5e9065984a42eca2132ec56ca3aa456f).
+
+* version 0.3.2 and below:
+  [github issue #1919](https://github.com/bazelbuild/bazel/issues/1919)
+
 
 ## <a name="jdk7"></a>Using Bazel with JDK 7 (deprecated)
 
diff --git a/site/versions/master/docs/windows.md b/site/versions/master/docs/windows.md
index e164ce20ba..c9f595d308 100644
--- a/site/versions/master/docs/windows.md
+++ b/site/versions/master/docs/windows.md
@@ -18,24 +18,6 @@ See instructions on the [installation page](install.md#windows).
 
 ## <a name="requirements"></a>Requirements
 
-To **run** Bazel (even pre-built binaries), you will need:
-
-*    Java JDK 8 or later
-*    [msys2](https://msys2.github.io/) (need to be installed at
-     ``C:\tools\msys64\``).
-    * We build against version
-     [20160205](https://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-x86_64-20160205.exe/download),
-     the [newer versions](https://sourceforge.net/projects/msys2/files/latest/download?source=files)
-     should also work. Older versions are known to have
-     [issues](https://github.com/bazelbuild/bazel/issues/1919).
-
-To **compile** Bazel, in addition to the above you will need:
-
-*    [Visual C++](https://www.visualstudio.com/) with Windows SDK installed
-     (Community Edition is fine)
-*    Several msys2 packages. Use the ``pacman`` command to install them:
-     ``pacman -Syuu gcc git curl zip unzip zlib-devel``
-
 Before you can compile or run Bazel, you will need to set some environment
 variables:
 
@@ -58,8 +40,37 @@ should make sure ``c:\tools\msys64\usr\bin`` appears in ``PATH`` *before*
 ``c:\windows\system32``, because otherwise Windows' ``bash.exe`` is used before
 msys2's.
 
-Use `where msys-2.0.dll` to ensure your ``PATH`` is set up correctly.
+Use ``where msys-2.0.dll`` to ensure your ``PATH`` is set up correctly.
 
+To **run** Bazel (even pre-built binaries), you will need:
+
+*    Java JDK 8 or later
+*    [msys2 shell](https://msys2.github.io/) (need to be installed at
+     ``C:\tools\msys64\``).
+    * We build against version
+     [20160205](https://sourceforge.net/projects/msys2/files/Base/x86_64/msys2-x86_64-20160205.exe/download),
+     you will need this version in order to run the pre-built
+     [release Bazel binaries](https://github.com/bazelbuild/bazel/releases).
+    * You can also use newer versions or the
+     [latest version](https://sourceforge.net/projects/msys2/files/latest/download?source=files),
+     but then you will need to compile Bazel from the distribution archive (the
+     source zip file) so that it's linked against the right version of
+     ``msys-2.0.dll``. See also the
+     [known issues](install.md#compiling-from-source-issues).
+*    Several msys2 packages. Use the ``pacman`` command to install them:
+
+     ```
+     pacman -Syuu gcc git curl zip unzip zlib-devel
+     ```
+
+To **compile** Bazel, in addition to the above you will need:
+
+*    [Visual C++](https://www.visualstudio.com/) with Windows SDK installed
+     (Community Edition is fine). Note: we intend to relax this requirement in
+     the future to only require the Microsoft Visual C++ Build Tools, see
+     [github issue #2448](https://github.com/bazelbuild/bazel/issues/2448).
+*    You may need to apply some patches/workarounds, see the
+     [known issues](install.md#compiling-from-source-issues).
 
 ## <a name="compiling"></a>Compiling Bazel on Windows