Update and clean up macOS installation instructions
* Update old URLs
* Use consistent capitalization
* Emphasize the existence of bazelbuild Homebrew tap (which has the correct list of
dependencies)
* Add Bazelisk info
Fixes #11320.
RELNOTES: None.
PiperOrigin-RevId: 311325028
diff --git a/site/docs/install-bazelisk.md b/site/docs/install-bazelisk.md
new file mode 100644
index 0000000..0f8ca53
--- /dev/null
+++ b/site/docs/install-bazelisk.md
@@ -0,0 +1,23 @@
+---
+layout: documentation
+title: Installing Bazel using Bazelisk
+---
+
+# Installing Bazel using Bazelisk
+
+[Bazelisk](https://github.com/bazelbuild/bazelisk) is a launcher for Bazel which
+automatically downloads and installs an appropriate version of Bazel. Use
+Bazelisk if you need to switch between different versions of Bazel depending on
+the current working directory, or to always keep Bazel updated to the latest
+release.
+
+You can install Bazelisk in multiple ways, including:
+
+* `npm install -g @bazel/bazelisk`
+* using [a binary release](https://github.com/bazelbuild/bazelisk/releases) for
+ Linux, macOS, or Windows
+* using Homebrew on macOS
+* by compiling from source using Go: `go get github.com/bazelbuild/bazelisk`
+
+For more details, see
+[the official README](https://github.com/bazelbuild/bazelisk/blob/master/README.md).
diff --git a/site/docs/install-os-x.md b/site/docs/install-os-x.md
index 79d41df..d6632d6 100644
--- a/site/docs/install-os-x.md
+++ b/site/docs/install-os-x.md
@@ -9,6 +9,7 @@
* [Use the binary installer (recommended)](#install-with-installer-mac-os-x)
* [Use Homebrew](#install-on-mac-os-x-homebrew)
+* [Use Bazelisk](install-bazelisk.md)
* [Compile Bazel from source](install-compile-source.md)
Bazel comes with two completion scripts. After installing Bazel, you can:
@@ -16,7 +17,7 @@
* Access the [bash completion script](completion.md#bash)
* Install the [zsh completion script](completion.md#zsh)
-<h2 id="install-with-installer-mac-os-x">Installing using binary installer</h2>
+<h2 id="install-with-installer-mac-os-x">Installing using the binary installer</h2>
The binary installers are on Bazel's [GitHub releases page](https://github.com/bazelbuild/bazel/releases).
@@ -25,9 +26,9 @@
### Step 1: Install Xcode command line tools
-Xcode can be downloaded from the [Apple Developer
-Site](https://developer.apple.com/xcode/downloads/) (this link redirects to
-their App Store).
+Download Xcode from the
+[App Store](https://apps.apple.com/us/app/xcode/id497799835) or the
+[Apple Developer site](https://developer.apple.com/download/more/?=xcode).
For `objc_*` and `ios_*` rule support, you must have Xcode 6.1 or later with iOS
SDK 8.1 installed on your system.
@@ -42,7 +43,7 @@
Next, download the Bazel binary installer named `bazel-<version>-installer-darwin-x86_64.sh` from the [Bazel releases page on GitHub](https://github.com/bazelbuild/bazel/releases).
-Note: **on MacOS Catalina**, due to Apple's new app notarization requirements,
+Note: **on macOS Catalina**, due to Apple's new app notarization requirements,
you will need to download the installer from the terminal using `curl`:
```
@@ -66,7 +67,7 @@
sets the `.bazelrc` path to `$HOME/.bazelrc`. Use the `--help` command to see
additional installation options.
-If you are **on MacOS Catalina** and get an error that _**“bazel-real” cannot be
+If you are **on macOS Catalina** and get an error that _**“bazel-real” cannot be
opened because the developer cannot be verified**_, you will need to re-download
the installer from the terminal using `curl` as a workaround; see Step 2 above.
@@ -96,14 +97,15 @@
Install Homebrew (a one-time step):
```bash
-/usr/bin/ruby -e "$(curl -fsSL \
-https://raw.githubusercontent.com/Homebrew/install/master/install)"
+/bin/bash -c "$(curl -fsSL \
+https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
```
### Step 2: Install the Bazel Homebrew package
-_Please note that if your system has the Bazel package from homebrew core installed you first
-need to uninstall it by typing `brew uninstall bazel`_
+_Please note that if your system has the Bazel package from homebrew core
+installed you first need to uninstall it by typing `brew uninstall bazel`. We
+recommend using the `bazelbuild` tap, which is maintained by the Bazel team._
Install the Bazel package via Homebrew as follows:
@@ -124,4 +126,12 @@
brew upgrade bazelbuild/tap/bazel
```
+<h2 id="install-on-mac-os-x-bazelisk">Install using Bazelisk</h2>
+If you need to switch between different versions of Bazel, use
+[Bazelisk](https://github.com/bazelbuild/bazelisk) to automatically download and
+launch the right Bazel version.
+
+You can install Bazelisk in multiple ways: `npm`, Homebrew, or
+compiled from source using Go. For more details, see
+[the official README](https://github.com/bazelbuild/bazelisk/blob/master/README.md).
