From 9efc5a5237c12b382b0383bd9fa3944c700bc899 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Mon, 21 Nov 2022 17:19:06 -0500 Subject: [PATCH] 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 TryBot-Result: Gopher Robot Run-TryBot: Russ Cox --- doc/go1.20.html | 6 ++++- src/cmd/go/alldocs.go | 40 +++++++++++++++++++++++++++-- src/cmd/go/internal/help/helpdoc.go | 40 +++++++++++++++++++++++++++-- 3 files changed, 81 insertions(+), 5 deletions(-) diff --git a/doc/go1.20.html b/doc/go1.20.html index 4ffb5a457f..dbf96984b9 100644 --- a/doc/go1.20.html +++ b/doc/go1.20.html @@ -85,7 +85,11 @@ Do not send CLs removing the interior tags from such phrases.

- TODO: https://go.dev/issue/45454: provide build tags for architecture environment variables + The go command now defines + architecture feature build tags, such as amd64.v2, + to allow selecting a package implementation file based on the presence + or absence of a particular architecture feature. + See go help buildconstraint for details.

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: // diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go index 72abccd16b..dddb785c0d 100644 --- a/src/cmd/go/internal/help/helpdoc.go +++ b/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: -- 2.50.0