cmd/go: improve documentation of GOAMD64 environment variable

[ulikunitz]

What version of Go are you using (go version)?

$ go version
go version devel go1.18-becaeea119 Tue Dec 14 17:43:51 2021 +0000 linux/amd64

Does this issue reproduce with the latest release?

No, this is for go1.18beta1.

What operating system and processor architecture are you using (go env)?

go env Output

$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/kunitz/.cache/go-build"
GOENV="/home/kunitz/.config/go/env"
GOEXE=""
GOEXPERIMENT=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GOMODCACHE="/home/kunitz/work/pkg/mod"
GONOPROXY="github.com/ulikunitz,doppelwuerfel.de/home/kunitz/git"
GONOSUMDB="github.com/ulikunitz,doppelwuerfel.de/home/kunitz/git"
GOOS="linux"
GOPATH="/home/kunitz/work"
GOPRIVATE="github.com/ulikunitz,doppelwuerfel.de/home/kunitz/git"
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/home/kunitz/go1.18"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/home/kunitz/go1.18/pkg/tool/linux_amd64"
GOVCS=""
GOVERSION="devel go1.18-becaeea119 Tue Dec 14 17:43:51 2021 +0000"
GCCGO="gccgo"
GOAMD64="v3"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD="/home/kunitz/src/compress/xz/go.mod"
GOWORK=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build3325120646=/tmp/go-build -gno-record-gcc-switches"
GOROOT/bin/go version: go version devel go1.18-becaeea119 Tue Dec 14 17:43:51 2021 +0000 linux/amd64
GOROOT/bin/go tool compile -V: compile version devel go1.18-becaeea119 Tue Dec 14 17:43:51 2021 +0000
uname -sr: Linux 5.4.0-91-generic
Distributor ID:	Ubuntu
Description:	Ubuntu 20.04.3 LTS
Release:	20.04
Codename:	focal
/lib/x86_64-linux-gnu/libc.so.6: GNU C Library (Ubuntu GLIBC 2.31-0ubuntu9.3) stable release version 2.31.
gdb --version: GNU gdb (Ubuntu 9.2-0ubuntu1~20.04) 9.2

What did you do?

I did some tests using the GOAMD64 environment variable.

What did you expect to see?

Release notes that mention that the variable is only relevant for compilation.

Documentation provided by go help environment that informs:

• about cache behavior when variable changes (Is there a need for `go clean -cache -testcache -cache -testcache)
• remark that programs will not be executed if the level is not supported by the actual CPU
• remark that performance doesn't necessarily improve with higher architecture levels; so benchmark testing is required (One of my benchmarks showed less performance for v3 compared to v2, while others showed improvements)

What did you see instead?

Terse documentation that didn't answer the questions I had

[randall77]

We currently have some docs in: https://github.com/golang/go/wiki/MinimumRequirements#amd64
Feel free to edit there.

about cache behavior when variable changes (Need for `go clean -cache -testcache -cache -testcache)

The cache should not require cleaning when changing GOAMD64. This is the same as any other arch-specific variable (e.g. GOARM).

remark that programs will not be executed if the level is not supported by the actual CPU

The binary when run will print a reasonable error message in such cases. I'm not sure I understand what other behavior you thought might happen.

remark that performance doesn't necessarily improve with higher architecture levels; so that benchmark testing is required (One of benchmarks showed less performance in v3 compared to v2)

Agreed. Machines are complicated - our hope is it gets faster with higher vX numbers but you would have to check your binary to be sure.

[ulikunitz]

I updated https://github.com/golang/go/wiki/MinimumRequirements#microarchitecture-support.

I will create a CL to reference this text in the Release Notes and the environment documentation instead of the Wikipedia link.

Note that I have no problems with the implementation. I just lacked documentation, having no experience with microarchitecture support in Go. I suppose there are many developers working exclusively on amd64 that will be in the same position.

[gopherbot]

Change https://golang.org/cl/372194 mentions this issue: doc: Improve documentation for GOAMD64