Repository: bazelbuild/bazel
Issue: Building bazel Docs missing install info
Labels: type: documentation (cleanup)
P2
team-OSS

> ATTENTION! Please read and follow:
> - if this is a _question_ about how to build / test / query / deploy using Bazel, or a _discussion starter_, send it to bazel-discuss@googlegroups.com
> - if this is a _bug_ or _feature request_, fill the form below as best as you can.

### Description of the problem / feature request:

> Looking at the page...
>    https://docs.bazel.build/versions/master/install-compile-source.html
> 
> It seems relatively straight forward to build a version of bazel (for the current machine) using the downloaded bazel binary  to build itself.
> 
> So I did as the instructions said..
> ```
>    bazel build //src:bazel
> ```
> All is well.. except   **Where is the built binary?** and **How do I Install it?**
> 
> There is just no information on this, making the whole exercise futile!
> 

### Feature requests: what underlying problem are you trying to solve with this feature?

> Original problem.. building "tenserflow" producing "`this rule is missing dependency declarations`" errors, that nothing seems to resolve!


### Bugs: what's the simplest, easiest way to reproduce this bug? Please provide a minimal example if possible.

> Replace this line with your answer.

### What operating system are you running Bazel on?

> Red Hat Enterprise Linux Server release 7.6 (Maipo)

### What's the output of `bazel info release`?

> release 0.26.1

### If `bazel info release` returns "development version" or "(@non-git)", tell us how you built Bazel.

> Replace this line with your answer.

### What's the output of `git remote get-url origin ; git rev-parse master ; git rev-parse HEAD` ?

> No GIT!
> Installed binary   bazel-0.26.1-installer-linux-x86_64.sh
> Compiling from source tar file from same version.

###  Have you found anything relevant by searching the web?

> Replace these lines with your answer.
>
> Places to look:
> - StackOverflow: http://stackoverflow.com/questions/tagged/bazel
> - GitHub issues: https://github.com/bazelbuild/bazel/issues
> - email threads on https://groups.google.com/forum/#!forum/bazel-discuss

### Any other information, logs, or outputs that you want to share?

> Replace these lines with your answer.
>
> If the files are large, upload as attachment or provide link.


Issue comments:

Pull request review comments:
Do we want to recommend //src:bazel-dev.exe instead?
Good idea! Yes.
Will do in internal review.

Patch that resolved the issue:
diff --git a/site/_layouts/documentation.html b/site/_layouts/documentation.html
index 0f8515e292431c..a43ac66ff8741a 100644
--- a/site/_layouts/documentation.html
+++ b/site/_layouts/documentation.html
@@ -10,7 +10,7 @@
 {% if version_components.size < 2 %}
 {%   assign major_version = "master" %}
 {%   assign minor_version = "master" %}
-{% else % }
+{% else %}
 {%   assign major_version = version_components[0] | plus:0 %}
 {%   assign minor_version = version_components[1] | plus:0 %}
 {% endif %}
diff --git a/site/docs/install-compile-source.md b/site/docs/install-compile-source.md
index d2f550ee2798ed..eac2c5801172b5 100644
--- a/site/docs/install-compile-source.md
+++ b/site/docs/install-compile-source.md
@@ -14,22 +14,138 @@ To build Bazel from source, you can do one of the following:
 
 <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 somwhere.
+    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.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.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.
+
+**Advanced**:
+
+If you want to build Bazel at an earlier commit than HEAD, you'll need the Bazel
+release that was the latest one 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.
+
+<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.exe`).
+
+**Instructions**:
+
+1.  Start Command Prompt (Start Menu &gt; Run &gt; "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.exe
+
+4.  The output will be at `bazel-bin\src\bazel.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,24 +157,26 @@ You can also build Bazel from scratch, without using an existing Bazel binary.
 
 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.
+**To build a development version** of Bazel from a GitHub source tree, 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>
 
@@ -100,7 +218,7 @@ on your `PATH` (such as `/usr/local/bin` on Linux).
 
 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 +280,16 @@ Unix-like systems.)
 
 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.


Test patch: