From 41d8e61a6b9d8f9db912626eb2bbc535e929fefc Mon Sep 17 00:00:00 2001
From: Russ Cox <rsc@golang.org>
Date: Fri, 11 Dec 2020 13:32:14 -0500
Subject: [PATCH] doc: make clear that Go 1.4 is not required for bootstrap

Go 1.4 does not work on some systems, including the most
recent versions of macOS. Make it clearer that that's not the only
way to bootstrap Go.

Change-Id: I7c03d6808e43bf26283a53eab2bb0b2dc4af73af
Reviewed-on: https://go-review.googlesource.com/c/go/+/277216
Trust: Russ Cox <rsc@golang.org>
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
---
 doc/install-source.html | 71 ++++++++++++++++++++++++++---------------
 1 file changed, 46 insertions(+), 25 deletions(-)

diff --git a/doc/install-source.html b/doc/install-source.html
index c6dc3aed43e..f0a909263cf 100644
--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -119,11 +119,26 @@ The Go toolchain is written in Go. To build it, you need a Go compiler installed
 The scripts that do the initial build of the tools look for a "go" command
 in <code>$PATH</code>, so as long as you have Go installed in your
 system and configured in your <code>$PATH</code>, you are ready to build Go
-from source. 
+from source.
 Or if you prefer you can set <code>$GOROOT_BOOTSTRAP</code> to the
 root of a Go installation to use to build the new Go toolchain;
 <code>$GOROOT_BOOTSTRAP/bin/go</code> should be the go command to use.</p>
 
+<p>
+There are four possible ways to obtain a bootstrap toolchain:
+</p>
+
+<ul>
+<li>Download a recent binary release of Go.
+<li>Cross-compile a toolchain using a system with a working Go installation.
+<li>Use gccgo.
+<li>Compile a toolchain from Go 1.4, the last Go release with a compiler written in C.
+</ul>
+
+<p>
+These approaches are detailed below.
+</p>
+
 <h3 id="bootstrapFromBinaryRelease">Bootstrap toolchain from binary release</h3>
 
 <p>
@@ -132,30 +147,6 @@ To use a binary release as a bootstrap toolchain, see
 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
-<a href="https://dl.google.com/go/go1.4-bootstrap-20171003.tar.gz">go1.4-bootstrap-20171003.tar.gz</a>,
-which contains the Go 1.4 source code plus accumulated fixes
-to keep the tools running on newer operating systems.
-(Go 1.4 was the last distribution in which the toolchain was written in C.)
-After unpacking the Go 1.4 source, <code>cd</code> to
-the <code>src</code> subdirectory, set <code>CGO_ENABLED=0</code> in
-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>
@@ -194,6 +185,36 @@ $ sudo update-alternatives --set go /usr/bin/go-5
 $ GOROOT_BOOTSTRAP=/usr ./make.bash
 </pre>
 
+<h3 id="bootstrapFromSource">Bootstrap toolchain from C source code</h3>
+
+<p>
+To build a bootstrap toolchain from C source code, use
+either the git branch <code>release-branch.go1.4</code> or
+<a href="https://dl.google.com/go/go1.4-bootstrap-20171003.tar.gz">go1.4-bootstrap-20171003.tar.gz</a>,
+which contains the Go 1.4 source code plus accumulated fixes
+to keep the tools running on newer operating systems.
+(Go 1.4 was the last distribution in which the toolchain was written in C.)
+After unpacking the Go 1.4 source, <code>cd</code> to
+the <code>src</code> subdirectory, set <code>CGO_ENABLED=0</code> in
+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>
+
+<p>
+Note that Go 1.4 does not run on all systems that later versions of Go do.
+In particular, Go 1.4 does not support current versions of macOS.
+On such systems, the bootstrap toolchain must be obtained using one of the other methods.
+</p>
+
 <h2 id="git">Install Git, if needed</h2>
 
 <p>