Docs: explain building bazel with bazel
Fixes https://github.com/bazelbuild/bazel/issues/9155
Change-Id: I909c5ca359ad89243667ca3f1dc09c9913ff8ce3
Closes #9169.
Change-Id: I909c5ca359ad89243667ca3f1dc09c9913ff8ce3
PiperOrigin-RevId: 263763184
diff --git a/site/docs/install-compile-source.md b/site/docs/install-compile-source.md
index d2f550e..6982fb9 100644
--- a/site/docs/install-compile-source.md
+++ b/site/docs/install-compile-source.md
@@ -14,22 +14,134 @@
<h2 id="build-bazel-using-bazel">Build Bazel using Bazel</h2>
-If you already have a Bazel binary, you can build Bazel from a GitHub checkout.
+TL;DR:
-You will need:
+1. [Get the latest Bazel release](https://github.com/bazelbuild/bazel/releases)
-* A GitHub checkout of Bazel's sources at the desired commit.
+2. [Download Bazel's sources from GitHub](https://github.com/bazelbuild/bazel/archive/master.zip)
+ and extract somewhere.
+ Alternatively you can git clone the source tree from https://github.com/bazelbuild/bazel
-* The Bazel version that was the latest when the commit was merged. (Other
- Bazel versions may work too, but are not guaranteed to.) You can either
- download this version from
- [GitHub](https://github.com/bazelbuild/bazel/releases), or build it from
- source, or bootstrap it as described below.
+3. Install the same prerequisites as for bootstrapping (see
+ [for Unix-like systems](#bootstrap-unix-prereq) or
+ [for Windows](#bootstrap-windows-prereq))
-* The same prerequisites as for bootstrapping (JDK, C++ compiler, etc.)
+4. Build Bazel using Bazel: `bazel build //src:bazel`
+ (or `bazel build //src:bazel-dev.exe` on Windows)
-Once you have a Bazel binary to build with and the source tree of Bazel, `cd`
-into the directory and run `bazel build //src:bazel`.
+5. The resulting binary is at `bazel-bin/src/bazel`
+ (or `bazel-bin\src\bazel-dev.exe` on Windows). You can copy it wherever you
+ like and use immediately without further installation.
+
+Detailed instructions follow below.
+
+<h3 id="build-bazel-install-bazel">1. Get the latest Bazel release</h3>
+
+**Goal**: Install or download a release version of Bazel. Make sure you can run
+it by typing `bazel` in a terminal.
+
+**Reason**: To build Bazel from a GitHub source tree, you need a pre-existing
+Bazel binary. You can install one from a package manager or download one from
+GitHub. See <a href="install.html">Installing Bazel</a>. (Or you can [build from
+scratch (bootstrap)](#bootstrap-bazel).)
+
+**Troubleshooting**:
+
+* If you cannot run Bazel by typing `bazel` in a terminal:
+
+ * Maybe your Bazel binary's directory is not on the PATH.
+
+ This is not a big problem. Instead of typing `bazel`, you will need to
+ type the full path.
+
+ * Maybe the Bazel binary itself is not called `bazel` (on Unixes) or
+ `bazel.exe` (on Windows).
+
+ This is not a big problem. You can either rename the binary, or type the
+ binary's name instead of `bazel`.
+
+ * Maybe the binary is not executable (on Unixes).
+
+ You must make the binary executable by running `chmod +x /path/to/bazel`.
+
+<h3 id="build-bazel-git">2. Download Bazel's sources from GitHub</h3>
+
+If you are familiar with Git, then just git clone https://github.com/bazelbuild/bazel
+
+Otherwise:
+
+1. Download the
+ [latest sources as a zip file](https://github.com/bazelbuild/bazel/archive/master.zip).
+
+2. Extract the contents somewhere.
+
+ For example create a `bazel-src` directory under your home directory and
+ extract there.
+
+<h3 id="build-bazel-prerequisites">3. Install prerequisites</h3>
+
+Install the same prerequisites as for bootstrapping (see below) -- JDK, C++
+compiler, MSYS2 (if you are building on Windows), etc.
+
+<h3 id="build-bazel-on-unixes">4. Build Bazel on Ubuntu Linux, macOS, and other
+Unix-like systems</h3>
+
+([Scroll down](#build-bazel-on-windows) for instructions for Windows.)
+
+**Goal**: Run Bazel to build a custom Bazel binary (`bazel-bin/src/bazel`).
+
+**Instructions**:
+
+1. Start a Bash terminal
+
+2. `cd` into the directory where you extracted (or cloned) Bazel's sources.
+
+ For example if you extracted the sources under your home directory, run:
+
+ cd ~/bazel-src
+
+3. Build Bazel from source:
+
+ bazel build //src:bazel
+
+4. The output will be at `bazel-bin/src/bazel`
+
+<h3 id="build-bazel-on-windows">4. Build Bazel on Windows</h3>
+
+([Scroll up](#build-bazel-on-unixes) for instructions for Linux, macOS, and other
+Unix-like systems.)
+
+**Goal**: Run Bazel to build a custom Bazel binary
+(`bazel-bin\src\bazel-dev.exe`).
+
+**Instructions**:
+
+1. Start Command Prompt (Start Menu > Run > "cmd.exe")
+
+2. `cd` into the directory where you extracted (or cloned) Bazel's sources.
+
+ For example if you extracted the sources under your home directory, run:
+
+ cd %USERPROFILE%\bazel-src
+
+3. Build Bazel from source:
+
+ bazel build //src:bazel-dev.exe
+
+ Alternatively you can build `//src:bazel.exe` -- that yields a smaller
+ binary but it's slower to build.
+
+4. The output will be at `bazel-bin\src\bazel-dev.exe`
+
+<h3 id="build-bazel-install">5. Install the built binary</h3>
+
+Actually, there's nothing to install.
+
+The output of the previous step is a self-contained Bazel binary. You can copy
+it to any directory and use immediately. (It's useful if that directory is on
+your PATH so that you can run "bazel" everywhere.)
+
+---
<h2 id="bootstrap-bazel">Build Bazel from scratch (bootstrapping)</h2>
@@ -41,25 +153,23 @@
1. Download `bazel-<version>-dist.zip` from
[GitHub](https://github.com/bazelbuild/bazel/releases), for example
- `bazel-0.18.0-dist.zip`.
+ `bazel-0.28.1-dist.zip`.
- There is a **single, architecture-independent** distribution archive. There
- are no architecture-specific or OS-specific distribution archives.
+ **Attention**:
- You **have to use the distribution archive** to bootstrap Bazel. You cannot
- use a source tree cloned from GitHub. (The distribution archive contains
- generated source files that are required for bootstrapping and are not part
- of the normal Git source tree.)
+ - There is a **single, architecture-independent** distribution archive.
+ There are no architecture-specific or OS-specific distribution archives.
+ - These sources are **not the same as the GitHub source tree**. You
+ have to use the distribution archive to bootstrap Bazel. You cannot
+ use a source tree cloned from GitHub. (The distribution archive contains
+ generated source files that are required for bootstrapping and are not part
+ of the normal Git source tree.)
-2. Unpack the zip file somewhere on disk.
+2. Unpack the distribution archive somewhere on disk.
We recommend to also verify the signature made by our
[release key](https://bazel.build/bazel-release.pub.gpg) 48457EE0.
-**To build a development version** of Bazel from a GitHub checkout, you need a
-working Bazel binary. [Scroll up](#build-bazel-using-bazel) to see how to build
-Bazel using Bazel.
-
<h3 id="bootstrap-unix">2. Bootstrap Bazel on Ubuntu Linux, macOS, and other Unix-like systems</h3>
([Scroll down](#bootstrap-windows) for instructions for Windows.)
@@ -100,7 +210,7 @@
To build the `bazel` binary in a reproducible way, also set
[`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/)
-in the `compile.sh` step.
+in the "Run the compilation script" step.
<h3 id="bootstrap-windows">2. Bootstrap Bazel on Windows</h3>
@@ -162,12 +272,16 @@
3. `cd` to the directory where you unpacked the distribution archive.
-4. Run the compilation script: `./compile.sh`
+4. Run the compilation script: `env EXTRA_BAZEL_ARGS="--host_javabase=@local_jdk//:jdk" ./compile.sh`
The compiled output is placed into `output/bazel.exe`. This is a self-contained
Bazel binary, without an embedded JDK. You can copy it anywhere or use it
in-place. For convenience we recommend copying this binary to a directory that's
on your `PATH`.
+To build the `bazel.exe` binary in a reproducible way, also set
+[`SOURCE_DATE_EPOCH`](https://reproducible-builds.org/specs/source-date-epoch/)
+in the "Run the compilation script" step.
+
You don't need to run Bazel from the MSYS2 shell. You can run Bazel from the
Command Prompt (`cmd.exe`) or PowerShell.
