1 files changed, 53 insertions, 32 deletions
diff --git a/doc/install-source.html b/doc/install-source.html
index cbf4eac70b..f0a909263c 100644
--- a/doc/install-source.html
+++ b/doc/install-source.html
@@ -119,41 +119,32 @@ 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>
 
-<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.
+There are four possible ways to obtain a bootstrap toolchain:
 </p>
 
-<h3 id="bootstrapFromSource">Bootstrap toolchain from source</h3>
+<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>
-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>).
+These approaches are detailed below.
 </p>
 
+<h3 id="bootstrapFromBinaryRelease">Bootstrap toolchain from binary release</h3>
+
 <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.
+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="bootstrapFromCrosscompiledSource">Bootstrap toolchain from cross-compiled source</h3>
@@ -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>
@@ -507,8 +528,8 @@ These default to the values of <code>$GOHOSTOS</code> and
 
 <p>
 Choices for <code>$GOOS</code> are
-<code>android</code>, <code>darwin</code> (macOS/iOS),
-<code>dragonfly</code>, <code>freebsd</code>, <code>illumos</code>, <code>js</code>,
+<code>android</code>, <code>darwin</code>, <code>dragonfly</code>,
+<code>freebsd</code>, <code>illumos</code>, <code>ios</code>, <code>js</code>,
 <code>linux</code>, <code>netbsd</code>, <code>openbsd</code>,
 <code>plan9</code>, <code>solaris</code> and <code>windows</code>.
 </p>
@@ -567,6 +588,9 @@ The valid combinations of <code>$GOOS</code> and <code>$GOARCH</code> are:
 <td></td><td><code>illumos</code></td> <td><code>amd64</code></td>
 </tr>
 <tr>
+<td></td><td><code>ios</code></td> <td><code>arm64</code></td>
+</tr>
+<tr>
 <td></td><td><code>js</code></td> <td><code>wasm</code></td>
 </tr>
 <tr>
@@ -663,16 +687,13 @@ For example, you should not set <code>$GOHOSTARCH</code> to
 <code>arm</code> on an x86 system.
 </p>
 
-<li><code>$GO386</code> (for <code>386</code> only, default is auto-detected
-if built on either <code>386</code> or <code>amd64</code>, <code>387</code> otherwise)
+<li><code>$GO386</code> (for <code>386</code> only, defaults to <code>sse2</code>)
 <p>
-This controls the code generated by gc to use either the 387 floating-point unit
-(set to <code>387</code>) or SSE2 instructions (set to <code>sse2</code>) for
-floating point computations.
+This variable controls how gc implements floating point computations.
 </p>
 <ul>
-	<li><code>GO386=387</code>: use x87 for floating point operations; should support all x86 chips (Pentium MMX or later).</li>
-	<li><code>GO386=sse2</code>: use SSE2 for floating point operations; has better performance than 387, but only available on Pentium 4/Opteron/Athlon 64 or later.</li>
+	<li><code>GO386=softfloat</code>: use software floating point operations; should support all x86 chips (Pentium MMX or later).</li>
+	<li><code>GO386=sse2</code>: use SSE2 for floating point operations; has better performance but only available on Pentium 4/Opteron/Athlon 64 or later.</li>
 </ul>
 </li>