From dadd80ae204bda1c3a48245d8a938f55f71259ea Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Tue, 29 Nov 2022 15:13:52 -0500 Subject: [PATCH] runtime/debug: more complete BuildInfo documentation A potential user did not realize Deps included all transitive dependencies, not just direct dependencies of the main module. Clarify that and add various other useful information. Change-Id: I5b8e1314bb26092edbcc090ba8eb9859f0a70662 Reviewed-on: https://go-review.googlesource.com/c/go/+/453602 Run-TryBot: Russ Cox Auto-Submit: Russ Cox Reviewed-by: Julie Qiu TryBot-Result: Gopher Robot Reviewed-by: Bryan Mills --- src/runtime/debug/mod.go | 44 ++++++++++++++++++++++++++++++++-------- 1 file changed, 36 insertions(+), 8 deletions(-) diff --git a/src/runtime/debug/mod.go b/src/runtime/debug/mod.go index 3ef8cfb5de..b0dbe158c4 100644 --- a/src/runtime/debug/mod.go +++ b/src/runtime/debug/mod.go @@ -39,14 +39,26 @@ func ReadBuildInfo() (info *BuildInfo, ok bool) { // BuildInfo represents the build information read from a Go binary. type BuildInfo struct { - GoVersion string // Version of Go that produced this binary. - Path string // The main package path - Main Module // The module containing the main package - Deps []*Module // Module dependencies - Settings []BuildSetting // Other information about the build. + // GoVersion is the version of the Go toolchain that built the binary + // (for example, "go1.19.2"). + GoVersion string + + // Path is the package path of the main package for the binary + // (for example, "golang.org/x/tools/cmd/stringer"). + Path string + + // Main describes the module that contains the main package for the binary + Main Module + + // Deps describes all the dependency modules, both direct and indirect, + // that contributed packages to the build of this binary. + Deps []*Module + + // Settings describes the build settings used to build the binary. + Settings []BuildSetting } -// Module represents a module. +// A Module describes a single module included in a build. type Module struct { Path string // module path Version string // module version @@ -54,8 +66,24 @@ type Module struct { Replace *Module // replaced by this module } -// BuildSetting describes a setting that may be used to understand how the -// binary was built. For example, VCS commit and dirty status is stored here. +// A BuildSetting is a key-value pair describing one setting that influenced a build. +// +// Defined keys include: +// +// - -buildmode: the buildmode flag used (typically "exe") +// - -compiler: the compiler toolchain flag used (typically "gc") +// - CGO_ENABLED: the effective CGO_ENABLED environment variable +// - CGO_CFLAGS: the effective CGO_CFLAGS environment variable +// - CGO_CPPFLAGS: the effective CGO_CPPFLAGS environment variable +// - CGO_CXXFLAGS: the effective CGO_CPPFLAGS environment variable +// - CGO_LDFLAGS: the effective CGO_CPPFLAGS environment variable +// - GOARCH: the architecture target +// - GOAMD64/GOARM64/GO386/etc: the architecture feature level for GOARCH +// - GOOS: the operating system target +// - vcs: the version control system for the source tree where the build ran +// - vcs.revision: the revision identifier for the current commit or checkout +// - vcs.time: the modification time associated with vcs.revision, in RFC3339 format +// - vcs.modified: true or false indicating whether the source tree had local modifications type BuildSetting struct { // Key and Value describe the build setting. // Key must not contain an equals sign, space, tab, or newline. -- 2.48.1