mirror of
https://github.com/golang/go
synced 2024-11-18 05:54:49 -07:00
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>
This commit is contained in:
Jay Conrod
parent
c2d1df6391
commit
6ad5f4e334
@ -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:
|
||||
//
|
||||
// // +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.
|
||||
//
|
||||
// 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.
|
||||
// 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
|
||||
|
||||
@ -770,55 +770,90 @@ 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:
|
||||
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:
|
||||
|
||||
// +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.
|
||||
|
||||
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.
|
||||
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.
|
||||
`,
|
||||
}
|
||||
|
||||
@ -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
|
||||
//
|
||||
|
||||
Loading…
Reference in New Issue
Block a user