cmd/go: GOMOD env var is not documented

[pierreprinetti]

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

go version devel +4f1f503373 Fri Jul 20 03:30:04 2018 +0000 darwin/amd64

Does this issue reproduce with the latest release?

N/A

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

GOARCH="amd64"
GOBIN="/Users/pierre/code/bin"
GOCACHE="/Users/pierre/Library/Caches/go-build"
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/pierre/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/Cellar/go/HEAD-4f1f503/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/HEAD-4f1f503/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD=""
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 -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/7g/98rjcknd3tg687h6z8shgtmr0000gn/T/go-build873031824=/tmp/go-build -gno-record-gcc-switches -fno-common"

What did you do?

go help environment

What did you expect to see?

I expected to see some information about the GOMOD enviroment variable, which is listed in the output of go env.

What did you see instead?

Documentation on many environment variables, but no mention of GOMOD:

The go command, and the tools it invokes, examine a few different
environment variables. For many of these, you can see the default
value of on your system by running 'go env NAME', where NAME is the
name of the variable.

General-purpose environment variables:

	GCCGO
		The gccgo command to run for 'go build -compiler=gccgo'.
	GOARCH
		The architecture, or processor, for which to compile code.
		Examples are amd64, 386, arm, ppc64.
	GOBIN
		The directory where 'go install' will install a command.
	GOCACHE
		The directory where the go command will store cached
		information for reuse in future builds.
	GOOS
		The operating system for which to compile code.
		Examples are linux, darwin, windows, netbsd.
	GOPATH
		For more details see: 'go help gopath'.
	GOPROXY
		URL of Go module proxy. See 'go help goproxy'.
	GORACE
		Options for the race detector.
		See https://golang.org/doc/articles/race_detector.html.
	GOROOT
		The root of the go tree.
	GOTMPDIR
		The directory where the go command will write
		temporary source files, packages, and binaries.
	GOTOOLDIR
		The directory where the go tools (compile, cover, doc, etc...)
		are installed. This is printed by go env, but setting the
		environment variable has no effect.

Environment variables for use with cgo:

	CC
		The command to use to compile C code.
	CGO_ENABLED
		Whether the cgo command is supported. Either 0 or 1.
	CGO_CFLAGS
		Flags that cgo will pass to the compiler when compiling
		C code.
	CGO_CFLAGS_ALLOW
		A regular expression specifying additional flags to allow
		to appear in #cgo CFLAGS source code directives.
		Does not apply to the CGO_CFLAGS environment variable.
	CGO_CFLAGS_DISALLOW
		A regular expression specifying flags that must be disallowed
		from appearing in #cgo CFLAGS source code directives.
		Does not apply to the CGO_CFLAGS environment variable.
	CGO_CPPFLAGS, CGO_CPPFLAGS_ALLOW, CGO_CPPFLAGS_DISALLOW
		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
		but for the C preprocessor.
	CGO_CXXFLAGS, CGO_CXXFLAGS_ALLOW, CGO_CXXFLAGS_DISALLOW
		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
		but for the C++ compiler.
	CGO_FFLAGS, CGO_FFLAGS_ALLOW, CGO_FFLAGS_DISALLOW
		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
		but for the Fortran compiler.
	CGO_LDFLAGS, CGO_LDFLAGS_ALLOW, CGO_LDFLAGS_DISALLOW
		Like CGO_CFLAGS, CGO_CFLAGS_ALLOW, and CGO_CFLAGS_DISALLOW,
		but for the linker.
	CXX
		The command to use to compile C++ code.
	PKG_CONFIG
		Path to pkg-config tool.

Architecture-specific environment variables:

	GOARM
		For GOARCH=arm, the ARM architecture for which to compile.
		Valid values are 5, 6, 7.
	GO386
		For GOARCH=386, the floating point instruction set.
		Valid values are 387, sse2.
	GOMIPS
		For GOARCH=mips{,le}, whether to use floating point instructions.
		Valid values are hardfloat (default), softfloat.
	GOMIPS64
		For GOARCH=mips64{,le}, whether to use floating point instructions.
		Valid values are hardfloat (default), softfloat.

Special-purpose environment variables:

	GCCGOTOOLDIR
		If set, where to find gccgo tools, such as cgo.
		The default is based on how gccgo was configured.
	GOROOT_FINAL
		The root of the installed Go tree, when it is
		installed in a location other than where it is built.
		File names in stack traces are rewritten from GOROOT to
		GOROOT_FINAL.
	GO_EXTLINK_ENABLED
		Whether the linker should use external linking mode
		when using -linkmode=auto with code that uses cgo.
		Set to 0 to disable external linking mode, 1 to enable it.
	GIT_ALLOW_PROTOCOL
		Defined by Git. A colon-separated list of schemes that are allowed to be used
		with git fetch/clone. If set, any scheme not explicitly mentioned will be
		considered insecure by 'go get'.

Thank you!

[mvdan]

It seems like this environment variable simply points at the go.mod currently in use, if there is one:

func ExtraEnvVars() []cfg.EnvVar {
        gomod := ""
        if modload.Init(); modload.ModRoot != "" {
                gomod = filepath.Join(modload.ModRoot, "go.mod")
        }
        return []cfg.EnvVar{
                {Name: "GOMOD", Value: gomod},
        }
}

The question is whether the variable should be hidden from go env, or properly documented like you say. cc @rsc @bcmills

[CJ-Jackson]

@mvdan I find that having GOMOD in go env is quite useful, I would say don't hide it, keep it and get it's properly documented.

https://github.com/CJ-Jackson/gobox/blob/master/tool/env.go#L15

[rsc]

I put GOMOD in 'go env' mainly so that it would be listed in bug reports. The expected way to get at this is 'go list -m -f {{.GoMod}}' but I have not added that yet. :-)

[gopherbot]

Change https://golang.org/cl/125655 mentions this issue: cmd/go: document go env GOMOD