go/build: move build constraint docs to 'go help buildconstraint'
CL 228017 added a new help page 'go help buildconstraint' which
summarized the information on build constraints in the go/build
documentation. The summary was almost as long as the go/build
documentation, since there's very little that can be left out.
This CL moves the original go/build documentation to
'go help buildconstraint' to eliminate redundnancy. The text
describing enabled tags is slightly different (targeting command-line
users more than go/build users), but the rest of the documentation is
unchanged.
Fixes #37018
Change-Id: Ic0ed4c6fdae2395dd58852e1600c701247c9c4cc
Reviewed-on: https://go-review.googlesource.com/c/go/+/232981
Run-TryBot: Jay Conrod <jayconrod@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Bryan C. Mills <bcmills@google.com>
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
index fdeef65..2316fb9 100644
--- a/src/cmd/go/alldocs.go
+++ b/src/cmd/go/alldocs.go
@@ -1480,56 +1480,91 @@
//
// 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:
+// A build constraint, also known as a build tag, is a line comment that begins
//
// // +build
//
-// and follows with a space-separated list of options on the same line.
-// The constraint is evaluated as the OR of the options.
+// that lists the conditions under which a file should be included in the package.
+// Constraints may appear in any kind of source file (not just Go), but
+// they must appear near the top of the file, preceded
+// only by blank lines and other line comments. These rules mean that in Go
+// files a build constraint must appear before the package clause.
+//
+// To distinguish build constraints from package documentation, a series of
+// build constraints must be followed by a blank line.
+//
+// A build constraint is evaluated as the OR of space-separated 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.
-//
+// A term may be negated with a preceding !.
// For example, the build constraint:
//
-// // +build linux,386 darwin,!cgo arm
+// // +build linux,386 darwin,!cgo
//
-// corresponds to boolean formula:
+// corresponds to the boolean formula:
//
-// (linux AND 386) OR (darwin AND NOT cgo) OR arm
+// (linux AND 386) OR (darwin AND (NOT cgo))
//
-// 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').
+// A file may have multiple build constraints. The overall constraint is the AND
+// of the individual constraints. That is, the build constraints:
//
-// An additional build constraint may be derived from the source file name.
+// // +build linux darwin
+// // +build amd64
+//
+// corresponds to the boolean formula:
+//
+// (linux OR darwin) AND amd64
+//
+// During a particular build, the following words are satisfied:
+//
+// - the target operating system, as spelled by runtime.GOOS, set with the
+// GOOS environment variable.
+// - the target architecture, as spelled by runtime.GOARCH, set with the
+// GOARCH environment variable.
+// - 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.12" from Go 1.12, and so on.
+// - any additional tags given by the -tags flag (see 'go help build').
+//
+// There are no separate build tags for beta or minor releases.
+//
// 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.
+// matches any of the following patterns:
+// *_GOOS
+// *_GOARCH
+// *_GOOS_GOARCH
+// (example: source_windows_amd64.go) where GOOS and GOARCH represent
+// any known operating system and architecture values respectively, then
+// the file is considered to have an implicit build constraint requiring
+// those terms (in addition to any explicit constraints in the file).
//
-// For example, the file:
+// Using GOOS=android matches build tags and files as for GOOS=linux
+// in addition to android tags and files.
//
-// source_windows_amd64.go
+// Using GOOS=illumos matches build tags and files as for GOOS=solaris
+// in addition to illumos tags and files.
//
-// is implicitly constrained to windows / amd64.
+// To keep a file from being considered for the build:
//
-// See 'go doc go/build' for more details.
+// // +build ignore
+//
+// (any other unsatisfied word will work as well, but "ignore" is conventional.)
+//
+// To build a file only when using cgo, and only on Linux and OS X:
+//
+// // +build linux,cgo darwin,cgo
+//
+// Such a file is usually paired with another file implementing the
+// default functionality for other systems, which in this case would
+// carry the constraint:
+//
+// // +build !linux,!darwin !cgo
+//
+// Naming a file dns_windows.go will cause it to be included only when
+// building the package for Windows; similarly, math_386.s will be included
+// only when building the package for 32-bit x86.
//
//
// Build modes
diff --git a/src/cmd/go/internal/help/helpdoc.go b/src/cmd/go/internal/help/helpdoc.go
index 693de8f..b937a61 100644
--- a/src/cmd/go/internal/help/helpdoc.go
+++ b/src/cmd/go/internal/help/helpdoc.go
@@ -770,55 +770,90 @@
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:
+A build constraint, also known as a build tag, is a line comment that begins
// +build
-and follows with a space-separated list of options on the same line.
-The constraint is evaluated as the OR of the options.
+that lists the conditions under which a file should be included in the package.
+Constraints may appear in any kind of source file (not just Go), but
+they must appear near the top of the file, preceded
+only by blank lines and other line comments. These rules mean that in Go
+files a build constraint must appear before the package clause.
+
+To distinguish build constraints from package documentation, a series of
+build constraints must be followed by a blank line.
+
+A build constraint is evaluated as the OR of space-separated 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.
-
+A term may be negated with a preceding !.
For example, the build constraint:
- // +build linux,386 darwin,!cgo arm
+ // +build linux,386 darwin,!cgo
-corresponds to boolean formula:
+corresponds to the boolean formula:
- (linux AND 386) OR (darwin AND NOT cgo) OR arm
+ (linux AND 386) OR (darwin AND (NOT cgo))
-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').
+A file may have multiple build constraints. The overall constraint is the AND
+of the individual constraints. That is, the build constraints:
-An additional build constraint may be derived from the source file name.
+ // +build linux darwin
+ // +build amd64
+
+corresponds to the boolean formula:
+
+ (linux OR darwin) AND amd64
+
+During a particular build, the following words are satisfied:
+
+ - the target operating system, as spelled by runtime.GOOS, set with the
+ GOOS environment variable.
+ - the target architecture, as spelled by runtime.GOARCH, set with the
+ GOARCH environment variable.
+ - 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.12" from Go 1.12, and so on.
+ - any additional tags given by the -tags flag (see 'go help build').
+
+There are no separate build tags for beta or minor releases.
+
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.
+matches any of the following patterns:
+ *_GOOS
+ *_GOARCH
+ *_GOOS_GOARCH
+(example: source_windows_amd64.go) where GOOS and GOARCH represent
+any known operating system and architecture values respectively, then
+the file is considered to have an implicit build constraint requiring
+those terms (in addition to any explicit constraints in the file).
-For example, the file:
+Using GOOS=android matches build tags and files as for GOOS=linux
+in addition to android tags and files.
- source_windows_amd64.go
+Using GOOS=illumos matches build tags and files as for GOOS=solaris
+in addition to illumos tags and files.
-is implicitly constrained to windows / amd64.
+To keep a file from being considered for the build:
-See 'go doc go/build' for more details.
+ // +build ignore
+
+(any other unsatisfied word will work as well, but "ignore" is conventional.)
+
+To build a file only when using cgo, and only on Linux and OS X:
+
+ // +build linux,cgo darwin,cgo
+
+Such a file is usually paired with another file implementing the
+default functionality for other systems, which in this case would
+carry the constraint:
+
+ // +build !linux,!darwin !cgo
+
+Naming a file dns_windows.go will cause it to be included only when
+building the package for Windows; similarly, math_386.s will be included
+only when building the package for 32-bit x86.
`,
}
diff --git a/src/go/build/doc.go b/src/go/build/doc.go
index 9633d59..2c6f0a8 100644
--- a/src/go/build/doc.go
+++ b/src/go/build/doc.go
@@ -59,99 +59,15 @@
//
// A build constraint, also known as a build tag, is a line comment that begins
//
-// // +build
+// // +build
//
-// that lists the conditions under which a file should be included in the package.
-// Constraints may appear in any kind of source file (not just Go), but
-// they must appear near the top of the file, preceded
-// only by blank lines and other line comments. These rules mean that in Go
-// files a build constraint must appear before the package clause.
+// that lists the conditions under which a file should be included in the
+// package. Build constraints may also be part of a file's name
+// (for example, source_windows.go will only be included if the target
+// operating system is windows).
//
-// To distinguish build constraints from package documentation, a series of
-// build constraints must be followed by a blank line.
-//
-// A build constraint is evaluated as the OR of space-separated options.
-// Each option evaluates as the AND of its comma-separated terms.
-// Each term consists of letters, digits, underscores, and dots.
-// A term may be negated with a preceding !.
-// For example, the build constraint:
-//
-// // +build linux,386 darwin,!cgo
-//
-// corresponds to the boolean formula:
-//
-// (linux AND 386) OR (darwin AND (NOT cgo))
-//
-// A file may have multiple build constraints. The overall constraint is the AND
-// of the individual constraints. That is, the build constraints:
-//
-// // +build linux darwin
-// // +build amd64
-//
-// corresponds to the boolean formula:
-//
-// (linux OR darwin) AND amd64
-//
-// During a particular build, the following words are satisfied:
-//
-// - the target operating system, as spelled by runtime.GOOS
-// - the target architecture, as spelled by runtime.GOARCH
-// - the compiler being used, either "gc" or "gccgo"
-// - "cgo", if ctxt.CgoEnabled is true
-// - "go1.1", from Go version 1.1 onward
-// - "go1.2", from Go version 1.2 onward
-// - "go1.3", from Go version 1.3 onward
-// - "go1.4", from Go version 1.4 onward
-// - "go1.5", from Go version 1.5 onward
-// - "go1.6", from Go version 1.6 onward
-// - "go1.7", from Go version 1.7 onward
-// - "go1.8", from Go version 1.8 onward
-// - "go1.9", from Go version 1.9 onward
-// - "go1.10", from Go version 1.10 onward
-// - "go1.11", from Go version 1.11 onward
-// - "go1.12", from Go version 1.12 onward
-// - "go1.13", from Go version 1.13 onward
-// - "go1.14", from Go version 1.14 onward
-// - "go1.15", from Go version 1.15 onward
-// - any additional words listed in ctxt.BuildTags
-//
-// There are no build tags for beta or minor releases.
-//
-// If a file's name, after stripping the extension and a possible _test suffix,
-// matches any of the following patterns:
-// *_GOOS
-// *_GOARCH
-// *_GOOS_GOARCH
-// (example: source_windows_amd64.go) where GOOS and GOARCH represent
-// any known operating system and architecture values respectively, then
-// the file is considered to have an implicit build constraint requiring
-// those terms (in addition to any explicit constraints in the file).
-//
-// To keep a file from being considered for the build:
-//
-// // +build ignore
-//
-// (any other unsatisfied word will work as well, but ``ignore'' is conventional.)
-//
-// To build a file only when using cgo, and only on Linux and OS X:
-//
-// // +build linux,cgo darwin,cgo
-//
-// Such a file is usually paired with another file implementing the
-// default functionality for other systems, which in this case would
-// carry the constraint:
-//
-// // +build !linux,!darwin !cgo
-//
-// Naming a file dns_windows.go will cause it to be included only when
-// building the package for Windows; similarly, math_386.s will be included
-// only when building the package for 32-bit x86.
-//
-// Using GOOS=android matches build tags and files as for GOOS=linux
-// in addition to android tags and files.
-//
-// Using GOOS=illumos matches build tags and files as for GOOS=solaris
-// in addition to illumos tags and files.
+// See 'go help buildconstraint'
+// (https://golang.org/cmd/go/#hdr-Build_constraints) for details.
//
// Binary-Only Packages
//
