diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go index d6725a63ba5..8fe48810e4e 100644 --- a/src/cmd/go/alldocs.go +++ b/src/cmd/go/alldocs.go @@ -35,23 +35,24 @@ // // Additional help topics: // -// buildmode build modes -// c calling between Go and C -// cache build and test caching -// environment environment variables -// filetype file types -// go.mod the go.mod file -// gopath GOPATH environment variable -// gopath-get legacy GOPATH go get -// goproxy module proxy protocol -// importpath import path syntax -// modules modules, module versions, and more -// module-get module-aware go get -// module-auth module authentication using go.sum -// module-private module configuration for non-public modules -// packages package lists and patterns -// testflag testing flags -// testfunc testing functions +// buildconstraint build constraints +// buildmode build modes +// c calling between Go and C +// cache build and test caching +// environment environment variables +// filetype file types +// go.mod the go.mod file +// gopath GOPATH environment variable +// gopath-get legacy GOPATH go get +// goproxy module proxy protocol +// importpath import path syntax +// modules modules, module versions, and more +// module-get module-aware go get +// module-auth module authentication using go.sum +// module-private module configuration for non-public modules +// packages package lists and patterns +// testflag testing flags +// testfunc testing functions // // Use "go help " for more information about that topic. // @@ -1477,6 +1478,60 @@ // See also: go fmt, go fix. // // +// Build constraints +// +// Build constraints describe the conditions under which each source file +// should be included in the corresponding package. Build constraints +// for a given source file may be added by build constraint comments +// within the file, or by specific patterns in the file's name. +// +// A build constraint comment appears before the file's package clause and +// must be separated from the package clause by at least one blank line. +// The comment begins with: +// +// // +build +// +// and follows with a space-separated list of options on the same line. +// The constraint is evaluated as the OR of the options. +// Each option evaluates as the AND of its comma-separated terms. +// Each term consists of letters, digits, underscores, and dots. +// Each term may be negated with a leading exclamation point. +// +// For example, the build constraint: +// +// // +build linux,386 darwin,!cgo arm +// +// corresponds to boolean formula: +// +// (linux AND 386) OR (darwin AND NOT cgo) OR arm +// +// During a particular build, the following terms are satisfied: +// - the target operating system and architecture, as spelled by +// runtime.GOOS and runtime.GOARCH respectively +// - the compiler being used, either "gc" or "gccgo" +// - "cgo", if the cgo command is supported +// (see CGO_ENABLED in 'go help environment') +// - a term for each Go major release, through the current version: +// "go1.1" from Go version 1.1 onward, +// "go1.2" from Go version 1.2 onward, and so on +// - and any additional tags given by the '-tags' flag (see 'go help build'). +// +// An additional build constraint may be derived from the source file name. +// If a file's name, after stripping the extension and a possible _test suffix, +// matches the patterns *_GOOS, *_GOARCH, or *_GOOS_GOARCH for any known +// GOOS or GOARCH value, then the file is implicitly constrained to that +// specific GOOS and/or GOARCH, in addition to any other build constraints +// declared as comments within the file. +// +// For example, the file: +// +// source_windows_amd64.go +// +// is implicitly constrained to windows / amd64. +// +// See 'go doc go/build' for more details. +// +// // Build modes // // The 'go build' and 'go install' commands take a -buildmode argument which diff --git a/src/cmd/go/internal/help/help.go b/src/cmd/go/internal/help/help.go index edb4a2a23ca..7a730fc8eb8 100644 --- a/src/cmd/go/internal/help/help.go +++ b/src/cmd/go/internal/help/help.go @@ -93,7 +93,7 @@ Use "go help{{with .LongName}} {{.}}{{end}} " for more information abou {{if eq (.UsageLine) "go"}} Additional help topics: {{range .Commands}}{{if and (not .Runnable) (not .Commands)}} - {{.Name | printf "%-11s"}} {{.Short}}{{end}}{{end}} + {{.Name | printf "%-15s"}} {{.Short}}{{end}}{{end}} Use "go help{{with .LongName}} {{.}}{{end}} " for more information about that topic. {{end}} diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go index 4093e40f26a..693de8ff49d 100644 --- a/src/cmd/go/internal/help/helpdoc.go +++ b/src/cmd/go/internal/help/helpdoc.go @@ -765,3 +765,60 @@ GODEBUG=gocachetest=1 causes the go command to print details of its decisions about whether to reuse a cached test result. `, } + +var HelpBuildConstraint = &base.Command{ + UsageLine: "buildconstraint", + Short: "build constraints", + Long: ` +Build constraints describe the conditions under which each source file +should be included in the corresponding package. Build constraints +for a given source file may be added by build constraint comments +within the file, or by specific patterns in the file's name. + +A build constraint comment appears before the file's package clause and +must be separated from the package clause by at least one blank line. +The comment begins with: + + // +build + +and follows with a space-separated list of options on the same line. +The constraint is evaluated as the OR of the options. +Each option evaluates as the AND of its comma-separated terms. +Each term consists of letters, digits, underscores, and dots. +Each term may be negated with a leading exclamation point. + +For example, the build constraint: + + // +build linux,386 darwin,!cgo arm + +corresponds to boolean formula: + + (linux AND 386) OR (darwin AND NOT cgo) OR arm + +During a particular build, the following terms are satisfied: +- the target operating system and architecture, as spelled by + runtime.GOOS and runtime.GOARCH respectively +- the compiler being used, either "gc" or "gccgo" +- "cgo", if the cgo command is supported + (see CGO_ENABLED in 'go help environment') +- a term for each Go major release, through the current version: + "go1.1" from Go version 1.1 onward, + "go1.2" from Go version 1.2 onward, and so on +- and any additional tags given by the '-tags' flag (see 'go help build'). + +An additional build constraint may be derived from the source file name. +If a file's name, after stripping the extension and a possible _test suffix, +matches the patterns *_GOOS, *_GOARCH, or *_GOOS_GOARCH for any known +GOOS or GOARCH value, then the file is implicitly constrained to that +specific GOOS and/or GOARCH, in addition to any other build constraints +declared as comments within the file. + +For example, the file: + + source_windows_amd64.go + +is implicitly constrained to windows / amd64. + +See 'go doc go/build' for more details. +`, +} diff --git a/src/cmd/go/main.go b/src/cmd/go/main.go index 2112defa6a5..fdf49b7380e 100644 --- a/src/cmd/go/main.go +++ b/src/cmd/go/main.go @@ -59,6 +59,7 @@ func init() { version.CmdVersion, vet.CmdVet, + help.HelpBuildConstraint, help.HelpBuildmode, help.HelpC, help.HelpCache,