Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

cmd/go: improve documentation of GOAMD64 environment variable #50174

Closed
ulikunitz opened this issue Dec 14, 2021 · 3 comments
Closed

cmd/go: improve documentation of GOAMD64 environment variable #50174

ulikunitz opened this issue Dec 14, 2021 · 3 comments
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Backlog

Comments

@ulikunitz
Copy link
Contributor

ulikunitz commented Dec 14, 2021 •
edited

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
@ianlancetaylor ianlancetaylor changed the title Improve documentation of GOAMD64 environment variable cmd/go: improve documentation of GOAMD64 environment variable Dec 14, 2021
@ianlancetaylor ianlancetaylor added help wanted NeedsFix The path to resolution is known, but the work has not been done. labels Dec 14, 2021
@ianlancetaylor ianlancetaylor added this to the Backlog milestone Dec 14, 2021
@randall77
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link

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

jproberts pushed a commit to jproberts/go that referenced this issue Jun 21, 2022
@ulikunitz @jproberts
doc: improve documentation for GOAMD64
08894e4 
The change clarifies in the release notes for go1.18 that the variable
is for compilation and references the microarchitecture description in
the Go Wiki,
https://golang.org/wiki/MinimumRequirements#amd64,
and references the same information in the output of go help
environment.

Fixes golang#50174

Change-Id: I6a7d5a06f48463a810c96cc9c76fe66113d5147c
Reviewed-on: https://go-review.googlesource.com/c/go/+/372194
Reviewed-by: Keith Randall <khr@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
Run-TryBot: Ian Lance Taylor <iant@golang.org>
TryBot-Result: Gopher Robot <gobot@golang.org>
@golang golang locked and limited conversation to collaborators Jan 6, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge help wanted NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
4 participants
@ianlancetaylor @randall77 @ulikunitz @gopherbot