cmd/go: document environment variables

This adds documentation for all the environment variables I could
locate in the go tool and the commands that it invokes.

Fixes #9672.

Change-Id: Id5f09160a3a8a938af4a3fcb8757eb3eced05416
Reviewed-on: https://go-review.googlesource.com/12620
Reviewed-by: Rob Pike <r@golang.org>

diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index a769f6c926bde977d4abc95a2413928f97a8dd69..66c277bb01ce7e8d2c1c71cc0a5a298ff28c9ed1 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -38,6 +38,7 @@ Additional help topics:
        buildmode   description of build modes
        filetype    file types
        gopath      GOPATH environment variable
+       environment environment variables
        importpath  import path syntax
        packages    description of package lists
        testflag    description of testing flags
@@ -974,6 +975,77 @@ in future releases. Once settled, they will be on by default.
 See https://golang.org/s/go15vendor for details.
 
 
+Environment variables
+
+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.
+       GOOS
+               The operating system for which to compile code.
+               Examples are linux, darwin, windows, netbsd.
+       GOPATH
+               See 'go help gopath'.
+       GORACE
+               Options for the race detector.
+               See https://golang.org/doc/articles/race_detector.html.
+       GOROOT
+               The root of the go tree.
+
+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_CPPFLAGS
+               Flags that cgo will pass to the compiler when compiling
+               C or C++ code.
+       CGO_CXXFLAGS
+               Flags that cgo will pass to the compiler when compiling
+               C++ code.
+       CGO_LDFLAGS
+               Flags that cgo will pass to the compiler when linking.
+       CXX
+               The command to use to compile C++ code.
+
+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.
+
+Special-purpose environment variables:
+
+       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.
+       GO15VENDOREXPERIMENT
+               Set to 1 to enable the Go 1.5 vendoring experiment.
+       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.
+
+
 Import path syntax
 
 An import path (see 'go help packages') denotes a package

diff --git a/src/cmd/go/help.go b/src/cmd/go/help.go
index 2f463f765000262f2af42280adcbf91935928ec5..591c2f4a0739be54b35ae8f906f67cb893d708bd 100644 (file)
--- a/src/cmd/go/help.go
+++ b/src/cmd/go/help.go
@@ -420,6 +420,81 @@ See https://golang.org/s/go15vendor for details.
        `,
 }
 
+var helpEnvironment = &Command{
+       UsageLine: "environment",
+       Short:     "environment variables",
+       Long: `
+
+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.
+       GOOS
+               The operating system for which to compile code.
+               Examples are linux, darwin, windows, netbsd.
+       GOPATH
+               See 'go help gopath'.
+       GORACE
+               Options for the race detector.
+               See https://golang.org/doc/articles/race_detector.html.
+       GOROOT
+               The root of the go tree.
+
+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_CPPFLAGS
+               Flags that cgo will pass to the compiler when compiling
+               C or C++ code.
+       CGO_CXXFLAGS
+               Flags that cgo will pass to the compiler when compiling
+               C++ code.
+       CGO_LDFLAGS
+               Flags that cgo will pass to the compiler when linking.
+       CXX
+               The command to use to compile C++ code.
+
+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.
+
+Special-purpose environment variables:
+
+       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.
+       GO15VENDOREXPERIMENT
+               Set to 1 to enable the Go 1.5 vendoring experiment.
+       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.
+       `,
+}
+
 var helpFileType = &Command{
        UsageLine: "filetype",
        Short:     "file types",

diff --git a/src/cmd/go/main.go b/src/cmd/go/main.go
index ae1f954b3e87e23dfc2a1ec8a10955627a67f5e9..e07651bb026b787b923d0ea7f0ea610b018ca327 100644 (file)
--- a/src/cmd/go/main.go
+++ b/src/cmd/go/main.go
@@ -95,6 +95,7 @@ var commands = []*Command{
        helpBuildmode,
        helpFileType,
        helpGopath,
+       helpEnvironment,
        helpImportPath,
        helpPackages,
        helpTestflag,