doc/install-source: create distinction between steps that involve "git clone"

Prior doc implied that "git clone" was one way to obtain a go1.4
bootstrap toochain, but it did not state this outright. Further,
the doc did not make it explicit in the "Fetch the repository"
section that one must necessarily "git clone" a second time in
the (presumed-to-be-uncommon) case where "git clone" had already
been perfomed in the "compiler binaries" section.

Updates #33402

Change-Id: Id70a6587b6ee09aca13559d63868b75cb07dff1e
Reviewed-on: https://go-review.googlesource.com/c/go/+/188900
Reviewed-by: Ian Lance Taylor <iant@golang.org>

diff --git a/doc/install-source.html b/doc/install-source.html
index f78dacf7ea2fd5a158ecdca6c3c04f50fb76ba5d..12b10d56211324253ad2b2f7b954d30d3ba44a94 100644 (file)
--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -140,12 +140,16 @@ For example, <code>$GOROOT_BOOTSTRAP/bin/go</code> should be
 the <code>go</code> command binary for the bootstrap toolchain.
 </p>
 
+<h3 id="bootstrapFromBinaryRelease">Bootstrap toolchain from binary release</h3>
+
 <p>
 To use a binary release as a bootstrap toolchain, see
 <a href="/dl/">the downloads page</a> or use any other
 packaged Go distribution.
 </p>
 
+<h3 id="bootstrapFromSource">Bootstrap toolchain from source</h3>
+
 <p>
 To build a bootstrap toolchain from source, use
 either the git branch <code>release-branch.go1.4</code> or
@@ -159,6 +163,17 @@ the environment, and run <code>make.bash</code> (or,
 on Windows, <code>make.bat</code>).
 </p>
 
+<p>
+Once the Go 1.4 source has been unpacked into your GOROOT_BOOTSTRAP directory,
+you must keep this git clone instance checked out to branch
+<code>release-branch.go1.4</code>.  Specifically, do not attempt to reuse
+this git clone in the later step named "Fetch the repository."  The go1.4
+bootstrap toolchain <b>must be able</b> to properly traverse the go1.4 sources
+that it assumes are present under this repository root.
+</p>
+
+<h3 id="bootstrapFromCrosscompiledSource">Bootstrap toolchain from cross-compiled source</h3>
+
 <p>
 To cross-compile a bootstrap toolchain from source, which is
 necessary on systems Go 1.4 did not target (for
@@ -181,6 +196,8 @@ That tree can be copied to a machine of the given target type
 and used as <code>GOROOT_BOOTSTRAP</code> to bootstrap a local build.
 </p>
 
+<h3 id="bootstrapFromGccgo">Bootstrap toolchain using gccgo</h3>
+
 <p>
 To use gccgo as the bootstrap toolchain, you need to arrange
 for <code>$GOROOT_BOOTSTRAP/bin/go</code> to be the go tool that comes
@@ -246,6 +263,11 @@ that if Go is checked out in <code>$HOME/go</code>, it will conflict with
 the default location of <code>$GOPATH</code>.
 See <a href="#gopath"><code>GOPATH</code></a> below.</p>
 
+Reminder: If you opted to also compile the bootstrap binaries from source (in an
+earlier section), you still need to <code>git clone</code> again at this point
+(to checkout the latest <code>&lt;tag&gt;</code>), because you must keep your
+go1.4 repository distinct.
+
 <h2 id="head">(Optional) Switch to the master branch</h2>
 
 <p>If you intend to modify the go source code, and