78 lines
4.2 KiB
Markdown
78 lines
4.2 KiB
Markdown
# Go command environments
|
|
|
|
`internal/gotool` resolves effective Go settings once for a validation or build
|
|
operation and applies the shared environment to its Go commands. It uses
|
|
`internal/process` for cancellation, the working directory, output, and wrapped
|
|
errors.
|
|
|
|
## Command output ownership
|
|
|
|
`Tool.Run` executes a status-only command. It forwards combined stdout and
|
|
stderr to the optional writer while the child runs, then releases its capture
|
|
on success. Failures include the captured diagnostic text and preserve the
|
|
underlying process or forwarding error.
|
|
|
|
`Tool.Output` returns combined stdout and stderr for commands whose output is
|
|
needed by the caller, such as compiler identification. After the child stops,
|
|
the capture's backing bytes transfer to the caller without a second copy. A
|
|
failed output command returns both those bytes and an error containing the
|
|
diagnostic text. The capture remains in memory for the duration of the child;
|
|
the component benchmark compares one 8 MiB write with the same output in
|
|
32 KiB writes, forwarding to `io.Discard`. Smaller writes incur buffer-growth
|
|
allocations. The [output benchmark](../../internal/gotool/performance_test.go)
|
|
measures total allocated bytes per operation, excluding subprocess overhead and
|
|
diagnostic strings. These totals count all allocations, including superseded
|
|
buffers. The returned slice retains the final buffer holding the complete output.
|
|
Peak live memory depends on buffer growth, garbage collection, and other command
|
|
work and is not measured by allocation totals. Failed output also formats
|
|
diagnostics into the error, so the returned bytes and diagnostic string can
|
|
coexist. Disk-backed diagnostics could reduce large failure peaks, but add file
|
|
lifecycle and cleanup work and remain a follow-up option.
|
|
|
|
Dependency preparation uses a separate command environment so proxy, private
|
|
module, checksum, and cache settings remain available. Its completed capture
|
|
uses the same ownership transfer when formatting a failure.
|
|
|
|
## Configuration discovery
|
|
|
|
The owner asks the installed `go` command for `GOHOSTOS` and `GOHOSTARCH`, then
|
|
queries effective operational settings with that host selected. Both queries
|
|
use `GOTOOLCHAIN=local` and controlled `GOFLAGS`. Discovery sets
|
|
`GOEXPERIMENT=none` and clears architecture feature variables so an invalid or
|
|
nonbaseline tuning value cannot prevent settings from being read. The
|
|
experiment override is discovery-only.
|
|
|
|
The persistent Go environment remains active during discovery. The owner copies
|
|
the effective cache and module-cache locations, Go root, temporary directory,
|
|
and native cgo/C-tool configuration into its settings. This captures values
|
|
supplied by either the process environment or the persistent Go environment
|
|
file.
|
|
|
|
Configuration discovery parses JSON from stdout. Stderr is captured separately
|
|
and included in command-failure diagnostics, so a successful query can emit
|
|
warnings while supplying valid configuration.
|
|
|
|
## Command environments
|
|
|
|
Every Go command receives `GOENV=off`, so removed persistent values cannot
|
|
return. ReleaseKit owns `GOFLAGS=-mod=readonly`, `GOWORK=off`,
|
|
`GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`.
|
|
Native commands use `GOHOSTOS` and `GOHOSTARCH` and retain the effective
|
|
`CGO_ENABLED`, `CC`, `CXX`, `PKG_CONFIG`, and `CGO_CFLAGS`, `CGO_CPPFLAGS`,
|
|
`CGO_CXXFLAGS`, and `CGO_LDFLAGS`. Static commands use the selected target and
|
|
`CGO_ENABLED=0`.
|
|
|
|
Both modes clear `GOEXPERIMENT` and the Go architecture feature variables
|
|
`GOAMD64`, `GOARM`, `GOARM64`, `GO386`, `GOMIPS`, `GOMIPS64`, `GOPPC64`,
|
|
`GORISCV64`, and `GOWASM`. The selected Go toolchain supplies its ordinary
|
|
baseline values. Effective `GOCACHE`, `GOCACHEPROG`, `GOMODCACHE`, `GOPATH`,
|
|
`GOROOT`, and `GOTMPDIR` values are retained. Other process variables remain
|
|
available to child commands.
|
|
|
|
Candidate validation uses native mode for the offline `go test` suite and
|
|
selected full `go vet` pass. Package-compilation checks use static mode for each
|
|
selected target and direct Go's output to the operating system null device, so
|
|
they leave no binary artifact. Artifact builds also use static mode for
|
|
selected-target compilation, then build the native version-check executable;
|
|
that executable runs as a normal child process.
|