Update macOS Install Instructions

Updating macOS install instructions together with David.

Closes #5025.

PiperOrigin-RevId: 193374002

1 files changed, 48 insertions, 50 deletions

diff --git a/site/docs/install-ubuntu.md b/site/docs/install-ubuntu.md
index ce93022462..7061c71a9b 100644
--- a/site/docs/install-ubuntu.md
+++ b/site/docs/install-ubuntu.md
@@ -12,8 +12,8 @@ Supported Ubuntu Linux platforms:
 
 Install Bazel on Ubuntu using one of the following methods:
 
-*   [Use our custom APT repository (recommended)](#install-on-ubuntu)
-*   [Use the binary installer](#install-with-installer-ubuntu)
+*   [Use the binary installer (recommended)](#install-with-installer-ubuntu)
+*   [Use our custom APT repository](#install-on-ubuntu)
 *   [Compile Bazel from source](install-compile-source.md)
 
 Bazel comes with two completion scripts. After installing Bazel, you can:
@@ -21,51 +21,12 @@ Bazel comes with two completion scripts. After installing Bazel, you can:
 *   access the [bash completion script](install.md)
 *   install the [zsh completion script](install.md)
 
-## <a name="install-on-ubuntu"></a> Using Bazel custom APT repository (recommended)
-
-### 1. Install JDK 8
-
-Install JDK 8 by using:
-
-```bash
-sudo apt-get install openjdk-8-jdk
-```
-
-On Ubuntu 14.04 LTS you'll have to use a PPA:
-
-```bash
-sudo add-apt-repository ppa:webupd8team/java
-sudo apt-get update && sudo apt-get install oracle-java8-installer
-```
-
-### 2. Add Bazel distribution URI as a package source (one time setup)
-
-```bash
-echo "deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8" | sudo tee /etc/apt/sources.list.d/bazel.list
-curl https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
-```
-
-If you want to install the testing version of Bazel, replace `stable` with
-`testing`.
-
-### 3. Install and update Bazel
-
-```bash
-sudo apt-get update && sudo apt-get install bazel
-```
-
-Once installed, you can upgrade to a newer version of Bazel with:
-
-```bash
-sudo apt-get upgrade bazel
-```
-
 ## <a name="install-with-installer-ubuntu"></a>Installing using binary installer
 
 The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
 
-The installer contains the Bazel binary and the required JDK. Some additional
-libraries must also be installed for Bazel to work.
+The installer contains the Bazel binary<sup>1</sup>. Some additional libraries must
+also be installed for Bazel to work.
 
 ### 1. Install required packages
 
@@ -80,13 +41,7 @@ sudo apt-get install pkg-config zip g++ zlib1g-dev unzip python
 
 Go to Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
 
-Download the binary installer `bazel-<version>-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.
-
-Note that `bazel-<version>-without-jdk-installer-linux-x86_64.sh` also exists.
-It is a version without embedded JDK 8. Only use this installer if you already
-have JDK 8 installed.
+Download the binary installer `bazel-<version>-installer-linux-x86_64.sh`.
 
 ### 3. Run the installer
 
@@ -112,3 +67,46 @@ export PATH="$PATH:$HOME/bin"
 ```
 
 You can also add this command to your `~/.bashrc` file.
+
+_<sup>1</sup>Note that Bazel includes an embedded JDK 8, which can be used even if a JDK is already
+installed. `bazel-<version>-without-jdk-installer-linux-x86_64.sh` is a version of the installer
+without embedded JDK 8. Only use this installer if you already have JDK 8 installed._
+
+## <a name="install-on-ubuntu"></a> Using Bazel custom APT repository
+
+### 1. Install JDK 8
+
+Install JDK 8 by using:
+
+```bash
+sudo apt-get install openjdk-8-jdk
+```
+
+On Ubuntu 14.04 LTS you'll have to use a PPA:
+
+```bash
+sudo add-apt-repository ppa:webupd8team/java
+sudo apt-get update && sudo apt-get install oracle-java8-installer
+```
+
+### 2. Add Bazel distribution URI as a package source (one time setup)
+
+```bash
+echo "deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8" | sudo tee /etc/apt/sources.list.d/bazel.list
+curl https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
+```
+
+If you want to install the testing version of Bazel, replace `stable` with
+`testing`.
+
+### 3. Install and update Bazel
+
+```bash
+sudo apt-get update && sudo apt-get install bazel
+```
+
+Once installed, you can upgrade to a newer version of Bazel with:
+
+```bash
+sudo apt-get upgrade bazel
+```