cmd/go: add 'go help buildconstraint'

Fixes #37018

Change-Id: I1d32c1cb432bc2d7a4d8d6b5c3a54fee558141ec
Reviewed-on: https://go-review.googlesource.com/c/go/+/228017
Run-TryBot: Bryan C. Mills <bcmills@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Jay Conrod <jayconrod@google.com>

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 <topic>" 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

src/cmd/go/internal/help/help.go

@@ -93,7 +93,7 @@ Use "go help{{with .LongName}} {{.}}{{end}} <command>" 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}} <topic>" for more information about that topic.
 {{end}}

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.
+`,
+}

src/cmd/go/main.go

@@ -59,6 +59,7 @@ func init() {
 		version.CmdVersion,
 		vet.CmdVet,
 
+		help.HelpBuildConstraint,
 		help.HelpBuildmode,
 		help.HelpC,
 		help.HelpCache,