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>

doc/go1.20.html

@@ -85,7 +85,11 @@ Do not send CLs removing the interior tags from such phrases.
 </p>
 
 <p><!-- https://go.dev/issue/45454 -->
-  TODO: <a href="https://go.dev/issue/45454">https://go.dev/issue/45454</a>: provide build tags for architecture environment variables
+  The <code>go</code> command now defines
+  architecture feature build tags, such as <code>amd64.v2</code>,
+  to allow selecting a package implementation file based on the presence
+  or absence of a particular architecture feature.
+  See <a href="/cmd/go#hdr-Build_constraints"><code>go</code> <code>help</code> <code>buildconstraint</code></a> for details.
 </p>
 
 <p><!-- https://go.dev/issue/50332 -->

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:
 //

src/cmd/go/internal/help/helpdoc.go

@@ -851,6 +851,8 @@ During a particular build, the following build tags are satisfied:
 	  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
@@ -880,11 +882,45 @@ in addition to illumos tags and files.
 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: