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
diff --git a/site/versions/master/docs/install.md b/site/versions/master/docs/install.md
index 0a6f9e5..957d581 100644
--- a/site/versions/master/docs/install.md
+++ b/site/versions/master/docs/install.md
@@ -224,7 +224,7 @@
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 @@
<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 @@
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 e164ce2..c9f595d 100644
--- a/site/versions/master/docs/windows.md
+++ b/site/versions/master/docs/windows.md
@@ -18,24 +18,6 @@
## <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 @@
``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
