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.