For version 0.5.0, update installation instructions:

- Bazel with JDK 7 will not be supported past 0.5.0
- a new installer is available with embedded JDK

This change should only be submitted when version 0.5.0 is released.

PiperOrigin-RevId: 157396320

5 files changed, 88 insertions, 64 deletions

diff --git a/site/versions/master/docs/install-compile-source.md b/site/versions/master/docs/install-compile-source.md
index 0435bd95d8..453d5658df 100644
--- a/site/versions/master/docs/install-compile-source.md
+++ b/site/versions/master/docs/install-compile-source.md
@@ -6,7 +6,7 @@ title: Compile Bazel from Source
 # <a name="compiling-from-source"></a>Compile Bazel from source
 
 1. Ensure that you have OpenJDK 8 installed on your system.
-   For a system based on debian packages (e.g., Debian, Ubuntu), install
+   For a system based on debian packages (e.g. Debian, Ubuntu), install
    OpenJDK 8 by running the command `sudo apt-get install openjdk-8-jdk`.
 
 2. The standard way of compiling a release version of Bazel from source is to
@@ -50,9 +50,9 @@ title: Compile Bazel from Source
     ```
 
     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).
+    (`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)
diff --git a/site/versions/master/docs/install-os-x.md b/site/versions/master/docs/install-os-x.md
index a369d7d706..50ab2320fb 100644
--- a/site/versions/master/docs/install-os-x.md
+++ b/site/versions/master/docs/install-os-x.md
@@ -15,7 +15,7 @@ If you had Command Line Tools installed, you also need to switch to Xcode using
 
 Install Bazel on macOS (OS X) using one of the following methods:
 
-*   [Use Homebrew](#install-on-mac-os-x-homebrew)
+*   [Use Homebrew (recommended)](#install-on-mac-os-x-homebrew)
 *   [Use the binary installer](#install-with-installer-mac-os-x)
 *   [Compile Bazel from source](install-compile-source.md)
 
@@ -30,6 +30,7 @@ Bazel comes with two completion scripts. After installing Bazel, you can:
 
 JDK 8 can be downloaded from [Oracle's JDK
 Page](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
+
 Look for "Mac OS X" under "Java SE Development Kit". This will download a DMG
 image with an install wizard.
 
@@ -53,26 +54,18 @@ You are all set. You can confirm Bazel is installed successfully by running
 
 You can later upgrade to newer version of Bazel with `brew upgrade bazel`.
 
-## <a name="install-with-installer-mac-os-x"></a>Install with installer
-
-We provide binary installers on our
-<a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a>
+## <a name="install-with-installer-mac-os-x"></a>Install using binary installer
 
-The installer only contains Bazel binary, some additional libraries are required
-to be installed on the machine to work.
-
-### 1. Install JDK 8
+The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases").
 
-JDK 8 can be downloaded from [Oracle's JDK
-Page](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html).
-Look for "Mac OS X" under "Java SE Development Kit". This will download a DMG
-image with an install wizard.
+The installer contains the Bazel binary and the required JDK. Some additional
+libraries must also be installed for Bazel to work.
 
-### 2. Install XCode command line tools
+### 1. Install XCode command line tools
 
 Xcode can be downloaded from the [Apple Developer
-Site](https://developer.apple.com/xcode/downloads/), which will redirect to the
-App Store.
+Site](https://developer.apple.com/xcode/downloads/) (this link redirects to
+their App Store).
 
 For `objc_*` and `ios_*` rule support, you must have Xcode 6.1 or later with iOS
 SDK 8.1 installed on your system.
@@ -84,25 +77,38 @@ command:
 sudo gcc --version
 ```
 
-### 3. Download Bazel
+### 2. Download the Bazel installer
 
-Download the [Bazel installer](https://github.com/bazelbuild/bazel/releases) for
-your operating system.
+Go to Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
 
-### 4. Run the installer
+Download the binary installer `bazel-0.5.0-installer-darwin-x86_64.sh`. This
+installer contains the Bazel binary and the required JDK, and can be used even
+if a JDK is already installed.
+
+Note that `bazel-0.5.0-without-jdk-installer-darwin-x86_64.sh` is a version of
+the installer without embedded JDK 8. Only use this installer if you already
+have JDK 8 installed.
+
+Note that two other versions of the installer exist:
+*   `bazel-0.5.0-without-jdk-installer-darwin-x86_64.sh`: version without
+    embedded JDK 8. Only use this installer if you already have JDK 8 installed.
+*   `bazel-0.5.0-jdk7-installer-darwin-x86_64.sh`: last release compatible
+    with JDK 7.
+
+### 3. Run the installer
 
 Run the installer:
 
 <pre>
-chmod +x bazel-&lt;version&gt;-installer-&lt;os&gt;.sh
-./bazel-&lt;version&gt;-installer-&lt;os&gt;.sh --user
+chmod +x bazel-0.5.0-installer-darwin-x86_64.sh
+./bazel-0.5.0-installer-darwin-x86_64.sh --user
 </pre>
 
 The `--user` flag installs Bazel to the `$HOME/bin` directory on your system and
 sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help` command to see
 additional installation options.
 
-### 5. Set up your environment
+### 4. Set up your environment
 
 If you ran the Bazel installer with the `--user` flag as above, the Bazel
 executable is installed in your `$HOME/bin` directory. It's a good idea to add
@@ -118,3 +124,9 @@ You are all set. You can confirm Bazel is installed successfully by running
 ```bash
 bazel version
 ```
+
+Once installed, you can upgrade to a newer version of Bazel with:
+
+```bash
+sudo apt-get upgrade bazel
+```
diff --git a/site/versions/master/docs/install-ubuntu.md b/site/versions/master/docs/install-ubuntu.md
index ae36aba954..c36e091dca 100644
--- a/site/versions/master/docs/install-ubuntu.md
+++ b/site/versions/master/docs/install-ubuntu.md
@@ -31,8 +31,8 @@ echo "deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8" |
 curl https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
 ```
 
-If you want to use the JDK 7, please replace `jdk1.8` with `jdk1.7` and if you
-want to install the testing version of Bazel, replace `stable` with `testing`.
+If you want to install the testing version of Bazel, replace `stable` with
+`testing`.
 
 ### 2. Install and update Bazel
 
@@ -46,47 +46,47 @@ Once installed, you can upgrade to a newer version of Bazel with:
 sudo apt-get upgrade bazel
 ```
 
-## <a name="install-with-installer-ubuntu"></a>Install with installer
+## <a name="install-with-installer-ubuntu"></a>Install using binary installer
 
-We provide binary installers on our
-<a href="https://github.com/bazelbuild/bazel/releases">GitHub releases page</a>
+The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases").
 
-The installer only contains Bazel binary, some additional libraries are required
-to be installed on the machine to work.
+The installer contains the Bazel binary and the required JDK. Some additional
+libraries must also be installed for Bazel to work.
 
-### 1. Install JDK 8
-
-To install OpenJDK 8:
+### 1. Install required packages
 
 ```
-sudo apt-get install openjdk-8-jdk
+sudo apt-get install pkg-config zip g++ zlib1g-dev unzip
 ```
 
-### 2. Install other required packages
+### 2. Download Bazel
 
-```
-sudo apt-get install pkg-config zip g++ zlib1g-dev unzip
-```
+Go to Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
 
-### 3. Download Bazel
+Download the binary installer `bazel-0.5.0-installer-linux-x86_64.sh`. This
+installer contains the Bazel binary and the required JDK, and can be used even
+if JDK is already installed.
 
-Download the [Bazel installer](https://github.com/bazelbuild/bazel/releases) for
-your operating system.
+Note that two other versions of the installer exist:
+*   `bazel-0.5.0-without-jdk-installer-linux-x86_64.sh`: version without
+    embedded JDK 8. Only use this installer if you already have JDK 8 installed.
+*   `bazel-0.5.0-jdk7-installer-linux-x86_64.sh`: last release compatible
+    with JDK 7.
 
-### 4. Run the installer
+### 3. Run the installer
 
 Run the installer:
 
 ```bash
-chmod +x bazel-<version>-installer-<os>.sh
-./bazel-<version>-installer-<os>.sh --user
+chmod +x bazel-0.5.0-installer-linux-x86_64.sh
+./bazel-0.5.0-installer-linux-x86_64.sh --user
 ```
 
 The `--user` flag installs Bazel to the `$HOME/bin` directory on your system and
 sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help` command to see
 additional installation options.
 
-### 5. Set up your environment
+### 4. Set up your environment
 
 If you ran the Bazel installer with the `--user` flag as above, the Bazel
 executable is installed in your `$HOME/bin` directory. It's a good idea to add
@@ -97,3 +97,9 @@ export PATH="$PATH:$HOME/bin"
 ```
 
 You can also add this command to your `~/.bashrc` file.
+
+Once installed, you can upgrade to a newer version of Bazel with:
+
+```bash
+sudo apt-get upgrade bazel
+```
diff --git a/site/versions/master/docs/install-windows.md b/site/versions/master/docs/install-windows.md
index af69f4053c..44713c291e 100644
--- a/site/versions/master/docs/install-windows.md
+++ b/site/versions/master/docs/install-windows.md
@@ -29,9 +29,9 @@ You can install the unofficial package using the
 choco install bazel
 ```
 
-This will install the latest available version of bazel, and dependencies.
+This will install the latest available version of Bazel, and dependencies.
 
-This package is experimental; please provide feedback to `@petemounce` in GitHub
+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.
 
@@ -41,6 +41,7 @@ maintenance](windows-chocolatey-maintenance.md) guide for more information.
 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 of the right version) and some setup in your environment to run Bazel.
-See these requirements on our [Windows page](windows.md#requirements).
+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).
diff --git a/site/versions/master/docs/install.md b/site/versions/master/docs/install.md
index dd69f7a270..1109bb1de1 100644
--- a/site/versions/master/docs/install.md
+++ b/site/versions/master/docs/install.md
@@ -15,8 +15,11 @@ For other platforms, you can try to [compile from source](install-compile-source
 
 Required Java version:
 
-*   Java JDK 8 or later ([JDK 7](#jdk7) is still supported
-    but deprecated).
+Java JDK 8 or later is required. To address the problem of JDK 8 not being
+available on some machines, Bazel's binary installer embeds a JDK by default.
+
+**Note:** Homebrew and Debian packages do not contain the embedded JDK. The
+shell installers are the only ones with an embedded JDK.
 
 Extras:
 
@@ -27,15 +30,17 @@ For more information on using Bazel, see
 [Getting Started with Bazel](getting-started.html).
 
 
-## <a name="jdk7"></a>Using Bazel with JDK 7 (deprecated)
+## <a name="jdk7"></a>Using Bazel with JDK 7
+
+Bazel version _0.5.0_ does run with JDK 7. However, starting with version
+_0.5.1_ Bazel must use JDK 8.
+
+The installers available for _0.5.0_ are:
 
-Bazel version _0.1.0_ runs without any change with JDK 7. However, future
-version will stop supporting JDK 7 when our CI cannot build for it anymore.
-The installer for JDK 7 for Bazel versions after _0.1.0_ is labeled
-<pre>
-./bazel-<em>version</em>-jdk7-installer-<em>os</em>.sh
-</pre>
-If you wish to use JDK 7, follow the same steps as for JDK 8 but with the _jdk7_ installer or using a different APT repository as described [here](#1-add-bazel-distribution-uri-as-a-package-source-one-time-setup).
+*  `bazel-0.5.0-installer.sh`: default version with embedded JDK
+*  `bazel-0.5.0-without-jdk-installer.sh`: version without embedded JDK
+*  `bazel-0.5.0-jdk7-installer.sh`: version compatible with JDK 7, will not be
+   available in later releases
 
 ## <a name="bash"></a>Getting bash completion