cmd/go: document new architecture feature build tags

Also mention in release notes.

Change-Id: Ifddfc6d2fdaae07c0774ad917838b0fdf9c0b0fe
Reviewed-on: https://go-review.googlesource.com/c/go/+/452559
Reviewed-by: Bryan Mills <bcmills@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
Run-TryBot: Russ Cox <rsc@golang.org>

1 files changed, 38 insertions, 2 deletions

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index 9079fa5f7b..4c72ab6d56 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -1872,6 +1872,8 @@
 //     GOOS environment variable.
 //   - the target architecture, as spelled by runtime.GOARCH, set with the
 //     GOARCH environment variable.
+//   - any architecture features, in the form GOARCH.feature
+//     (for example, "amd64.v2"), as detailed below.
 //   - "unix", if GOOS is a Unix or Unix-like system.
 //   - the compiler being used, either "gc" or "gccgo"
 //   - "cgo", if the cgo command is supported (see CGO_ENABLED in
@@ -1903,11 +1905,45 @@
 // Using GOOS=ios matches build tags and files as for GOOS=darwin
 // in addition to ios tags and files.
 //
-// To keep a file from being considered for the build:
+// The defined architecture feature build tags are:
+//
+//   - For GOARCH=386, GO386=387 and GO386=sse2
+//     set the 386.387 and 386.sse2 build tags, respectively.
+//   - For GOARCH=amd64, GOAMD64=v1, v2, and v3
+//     correspond to the amd64.v1, amd64.v2, and amd64.v3 feature build tags.
+//   - For GOARCH=arm, GOARM=5, 6, and 7
+//     correspond to the arm.5, arm.6, and arm.7 feature build tags.
+//   - For GOARCH=mips or mipsle,
+//     GOMIPS=hardfloat and softfloat
+//     correspond to the mips.hardfloat and mips.softfloat
+//     (or mipsle.hardfloat and mipsle.softfloat) feature build tags.
+//   - For GOARCH=mips64 or mips64le,
+//     GOMIPS64=hardfloat and softfloat
+//     correspond to the mips64.hardfloat and mips64.softfloat
+//     (or mips64le.hardfloat and mips64le.softfloat) feature build tags.
+//   - For GOARCH=ppc64 or ppc64le,
+//     GOPPC64=power8, power9, and power10 correspond to the
+//     ppc64.power8, ppc64.power9, and ppc64.power10
+//     (or ppc64le.power8, ppc64le.power9, and ppc64le.power10)
+//     feature build tags.
+//   - For GOARCH=wasm, GOWASM=satconv and signext
+//     correspond to the wasm.satconv and wasm.signext feature build tags.
+//
+// For GOARCH=amd64, arm, ppc64, and ppc64le, a particular feature level
+// sets the feature build tags for all previous levels as well.
+// For example, GOAMD64=v2 sets the amd64.v1 and amd64.v2 feature flags.
+// This ensures that code making use of v2 features continues to compile
+// when, say, GOAMD64=v4 is introduced.
+// Code handling the absence of a particular feature level
+// should use a negation:
+//
+//	//go:build !amd64.v2
+//
+// To keep a file from being considered for any build:
 //
 //	//go:build ignore
 //
-// (any other unsatisfied word will work as well, but "ignore" is conventional.)
+// (Any other unsatisfied word will work as well, but "ignore" is conventional.)
 //
 // To build a file only when using cgo, and only on Linux and OS X:
 //