Bazel documentation update, mainly for Windows
This change:
- Updates the Installation page with instructions
for Windows. Until now those were on the dedicated
Windows page, but now for sake of consistency with
other instructions for platforms, we have
everything on one page.
- Adds notes about Chocolatey and links to the
relevant maintenance page.
- Updates the Windows requirements page, removes
duplicate information.
- Updates the left-side navigation pane making the
Installation menu collapsible, adding the
Windows-specific pages as submenu items
- Updates the Copyright message in page footers,
fixes some typos, fixes broken links.
Fixes https://github.com/bazelbuild/bazel/issues/2128
--
MOS_MIGRATED_REVID=140119465
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 1515230..d3b37c1 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -25,8 +25,21 @@
</a>
<nav class="sidebar collapse" id="sidebar-nav">
<ul class="sidebar-nav">
- <li><a href="{{ page.version_prefix }}/docs/install.html">Installing</a></li>
+ <li>
+ <a class="sidebar-nav-heading" data-toggle="collapse"
+ href="#installing-menu" aria-expanded="false"
+ aria-controls="installing-menu">
+ Installing <span class="caret"></span>
+ </a>
+ <ul class="collapse sidebar-nav sidebar-submenu" id="installing-menu">
+ <li><a href="{{ page.version_prefix }}/docs/install.html">General information</a></li>
+ <li><a href="{{ page.version_prefix }}/docs/windows.html">Windows: installation and running</a></li>
+ <li><a href="{{ page.version_prefix }}/docs/windows-chocolatey-maintenance.html">Windows: Chocolatey package manager</a></li>
+ </ul>
+ </li>
+
<li><a href="{{ page.version_prefix }}/docs/getting-started.html">Getting Started</a></li>
+
<li>
<a class="sidebar-nav-heading" data-toggle="collapse"
href="#tutorial-menu" aria-expanded="false"
diff --git a/site/versions/master/docs/install.md b/site/versions/master/docs/install.md
index 44716bb..000efb0 100644
--- a/site/versions/master/docs/install.md
+++ b/site/versions/master/docs/install.md
@@ -9,7 +9,7 @@
* [Ubuntu Linux (Wily 15.10 and Trusty 14.04 LTS)](#ubuntu)
* [Mac OS X](#mac-os-x)
-* [Windows (highly experimental)](windows.md#installing-bazel-on-windows)
+* [Windows (highly experimental)](#windows)
For other platforms, you can try to [compile from source](#compiling-from-source).
@@ -216,13 +216,57 @@
You can also add this command to your `~/.bashrc` file.
+
+## <a name="windows"></a>Windows
+
+Windows support is highly experimental. 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.
+
+We currently support only 64 bit Windows 7 or higher and we compile Bazel as a
+msys2 binary.
+
+Install Bazel on Windows using one of the following methods:
+
+ * [Using Chocolatey](#install-on-windows-chocolatey)
+ * [Using binary distribution](#download-binary-windows)
+ * [Compiling Bazel from source](#compiling-from-source) -- make sure
+ your machine meets the [requirements](windows.md#requirements)
+
+
+### <a name="install-on-windows-chocolatey"></a>Install on Windows using Chocolatey
+
+You can install the unofficial package using the
+[chocolatey](https://chocolatey.org) package manager:
+
+```sh
+choco install bazel
+```
+
+This will install the latest available version of bazel, and dependencies.
+
+This package is experimental; please provide feedback to `@petemounce` in GitHub
+issue tracker. See the [Chocolatey installation and package
+maintenance](windows-chocolatey-maintenance.md) guide for more information.
+
+
+### <a name="download-binary-windows"></a>Download a precompiled binary
+
+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).
+
+
## <a name="compiling-from-source"></a>Compiling from source
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 (for releases 0.4.0 and earlier: dowload the "source
+the desired version (for releases 0.4.0 and earlier: download the "source
code" zip archive and note that it will only work for the supported
architectures as it contains binaries). We recommend to also verify
the signature made by our
@@ -233,6 +277,7 @@
so it can be copied to a directory on the PATH (e.g.,
`/usr/local/bin`) or used in-place.
+
## <a name="jdk7"></a>Using Bazel with JDK 7 (deprecated)
Bazel version _0.1.0_ runs without any change with JDK 7. However, future
diff --git a/site/versions/master/docs/support.md b/site/versions/master/docs/support.md
index 2119e6d..8b22ea6 100644
--- a/site/versions/master/docs/support.md
+++ b/site/versions/master/docs/support.md
@@ -8,7 +8,7 @@
* [User mailing list](https://groups.google.com/forum/#!forum/bazel-discuss)
* [Issue tracker](https://github.com/bazelbuild/bazel/issues)
* [Twitter](http://www.twitter.com/bazelbuild)
-* [IRC](irc://irc.freenode.net/bazel) (freenode.net#bazel)
+* [IRC](http://webchat.freenode.net) (irc.freenode.net#bazel)
# Support Policy
diff --git a/site/versions/master/docs/windows-chocolatey-maintenance.md b/site/versions/master/docs/windows-chocolatey-maintenance.md
index 90c9200..ee71282 100644
--- a/site/versions/master/docs/windows-chocolatey-maintenance.md
+++ b/site/versions/master/docs/windows-chocolatey-maintenance.md
@@ -3,30 +3,23 @@
title: Windows Chocolatey maintenance
---
-Installing Bazel on Windows
-===========================
-
-You can install the unofficial package using the [chocolatey](https://chocolatey.org) package manager:
-
-```sh
-choco install bazel
-```
-
-This will install the latest available version of bazel, and dependencies.
-
-This package is experimental; please provide feedback (`@petemounce` in issue tracker).
-
-
Maintaining Bazel Chocolatey package on Windows
===============================================
+**NOTE:** The Chocolatey package is experimental; please provide feedback
+(`@petemounce` in issue tracker).
+
### Prerequisites
You need:
-* [chocolatey package manager](https://chocolatey.org) installed
-* (to publish) a chocolatey API key granting you permission to publish the `bazel` package
- * [@petemounce](https://github.com/petemounce) currently maintains this unofficial package.
-* (to publish) to have set up that API key for the chocolatey source locally via `choco apikey -k <your key here> -s https://chocolatey.org/`
+
+* [chocolatey package manager](https://chocolatey.org) installed
+* (to publish) a chocolatey API key granting you permission to publish the
+ `bazel` package
+ * [@petemounce](https://github.com/petemounce) currently maintains this
+ unofficial package.
+* (to publish) to have set up that API key for the chocolatey source locally
+ via `choco apikey -k <your key here> -s https://chocolatey.org/`
### Build
@@ -38,17 +31,23 @@
popd
```
-Should result in `scripts/packages/chocolatey/bazel.<version>.nupkg` being created.
+Should result in `scripts/packages/chocolatey/bazel.<version>.nupkg` being
+created.
The `build.ps1` script supports `mode` values `local`, `rc` and `release`.
#### Test
0. Build the package (with `-mode local`)
- * run a webserver (`python -m SimpleHTTPServer` in `scripts/packages/chocolatey` is convenient and starts one on `http://localhost:8000`)
+
+ * run a webserver (`python -m SimpleHTTPServer` in
+ `scripts/packages/chocolatey` is convenient and starts one on
+ `http://localhost:8000`)
+
0. Test the install
- The `test.ps1` should install the package cleanly (and error if it did not install cleanly), then tell you what to do next.
+ The `test.ps1` should install the package cleanly (and error if it did not
+ install cleanly), then tell you what to do next.
0. Test the uninstall
@@ -61,7 +60,8 @@
### Release
-Modify `tools/parameters.json` for the new release's URI and checksum once the release has been published to github releases.
+Modify `tools/parameters.json` for the new release's URI and checksum once the
+release has been published to github releases.
```powershell
./build.ps1 -version <version> -isRelease
@@ -70,4 +70,5 @@
choco push bazel.x.y.z.nupkg --source https://chocolatey.org/
```
-Chocolatey.org will then run automated checks and respond to the push via email to the maintainers.
+Chocolatey.org will then run automated checks and respond to the push via email
+to the maintainers.
diff --git a/site/versions/master/docs/windows.md b/site/versions/master/docs/windows.md
index 63ef99d..2e8c8ab 100644
--- a/site/versions/master/docs/windows.md
+++ b/site/versions/master/docs/windows.md
@@ -4,18 +4,21 @@
---
-Windows support is highly experimental. 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)
+Windows support is highly experimental. 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.
-We currently support only 64 bit Windows 7 or higher and we compile Bazel as a msys2 binary.
+We currently support only 64 bit Windows 7 or higher and we compile Bazel as a
+msys2 binary.
-Using the release binary
-=========================
+## <a name="install"></a>Installation
-Release binaries are available on our [GitHub release page](https://github.com/bazelbuild/bazel/releases).
+See instructions on the [installation page](install.md#windows).
-To run the binary you will need:
+
+## <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
@@ -26,7 +29,14 @@
should also work. Older versions are known to have
[issues](https://github.com/bazelbuild/bazel/issues/1919).
-Before you run the binary, you will need to set some environment
+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:
```bash
@@ -38,44 +48,33 @@
(if you install msys2 to ``c:\tools\msys64``, just add
``c:\tools\msys64\usr\bin`` to ``PATH``).
-### Issues/Troubleshooting
+If you have another tool that vendors msys2 (such as msysgit), then
+``c:\tools\msys64\usr\bin`` must appear in your ``PATH`` *before* entries for
+those tools.
-If you have another tool that vendors msys2 (such as msysgit), then ``c:\tools\msys64\usr\bin`` must appear in your ``PATH`` *before* entries for those tools.
-
-Similarly, if you have [bash on Ubuntu on Windows](https://msdn.microsoft.com/en-gb/commandline/wsl/about) installed, you 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.
+Similarly, if you have [bash on Ubuntu on
+Windows](https://msdn.microsoft.com/en-gb/commandline/wsl/about) installed, you
+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.
-Building Bazel on Windows
-=========================
+## <a name="compiling"></a>Compiling Bazel on Windows
-To bootstrap Bazel on Windows, you will need:
-
-* Java JDK 8 or later
-* [Visual C++](https://www.visualstudio.com/) with Windows SDK installed
- (Community Edition is fine)
-* [msys2](https://msys2.github.io/) (need to be installed at
- ``C:\tools\msys64\``).
-* Several msys2 packages. Use the ``pacman`` command to install them:
- ``pacman -Syuu gcc git curl zip unzip zlib-devel``
+Ensure you have the [requirements](#requirements).
To build Bazel:
* Open the msys2 shell.
* Clone the Bazel git repository as normal.
-* Set the environment variables:
+* Set the environment variables (see above)
+* Run ``compile.sh`` in Bazel directory.
+* If all works fine, bazel will be built at ``output\bazel.exe``.
-```bash
-export JAVA_HOME="$(ls -d C:/Program\ Files/Java/jdk* | sort | tail -n 1)"
-export BAZEL_SH=c:/tools/msys64/usr/bin/bash.exe
-```
-* Run ``compile.sh`` in Bazel directory.
-* If all works fine, bazel will be built at ``output\bazel.exe``.
-
-Using Bazel on Windows
-======================
+## <a name="using"></a>Using Bazel on Windows
Bazel now supports building C++, Java and Python targets on Windows.
