Go Reference ยท The go Command and Tools
Go build constraints
Reference for Go build constraints: //go:build expressions, &&, || and !, GOOS and GOARCH file name suffixes, built-in tags like unix and cgo, and custom tags.
A build constraint (also called a build tag) tells the go command to include a file in a build only under certain conditions: on one operating system, with a custom tag, or from a certain Go version on. It lets one package hold platform-specific code or optional features without any preprocessor.
There are two ways to write a constraint. A //go:build line at the top of the file holds a boolean expression, and a file name ending in _GOOS, _GOARCH or both (such as files_linux.go or io_windows_amd64.go) works as an implicit constraint. A file that is excluded is not compiled, and not even parsed beyond the header, so it may contain code that would not build on the current platform.
//go:build linux && (amd64 || arm64) package sys
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.
Syntax
//go:build expression
The expression uses tags and these operators, from lowest to highest precedence: ||, &&, !. Parentheses group. A tag is an identifier made of letters, digits, _ and ..
Placement rules:
| Rule | Description |
|---|---|
| Position | Before the package clause, preceded only by blank lines and other line comments. |
| Blank line | A blank line must separate the constraint from the package clause (otherwise it would become the package doc comment). |
| One per file | Only one //go:build line is allowed. Put alternatives in the expression with ` |
| Comment form | It must be a line comment starting with //go:build, with no space after the slashes. A /* */ comment is not a constraint. |
Tags that are set automatically:
| Tag | Meaning |
|---|---|
GOOS and GOARCH values |
linux, windows, darwin, amd64, arm64, and so on. android also satisfies linux, and ios also satisfies darwin. |
unix |
True for every Unix-like GOOS (Go 1.19). |
gc, gccgo |
The compiler in use. |
cgo |
cgo is enabled. |
go1.N |
True when the toolchain's language version is at least 1.N. |
race, msan, asan |
The matching sanitizer is on. |
goexperiment.name |
A GOEXPERIMENT is enabled. |
Tags from -tags |
Whatever you pass: go build -tags=integration,postgres. |
File name rules. The suffix forms *_GOOS.go, *_GOARCH.go and *_GOOS_GOARCH.go apply only when the word is a known OS or architecture name. _test.go marks test files. Files beginning with _ or . are ignored entirely.
Errors and edge cases: when every file in a directory is excluded the command stops with build constraints exclude all Go files. A malformed expression is reported by the go command (and by go vet) with the file and line.
Usage notes
- Pairs of files for two implementations. Write
clock_unix.gowith//go:build unixandclock_windows.gothat exposes the same function names. Add a fallback file (//go:build !unix && !windows) so other systems still compile. - Opt-in tests. Put slow tests behind
//go:build integrationand run them withgo test -tags=integration ./.... //go:build ignore. The wordignoreis not special to the go tool; it is just a tag nobody sets. It is the usual way to keep a generator script in a package directory without building it. Run it withgo run gen.go.- Version gating.
//go:build go1.22on a file selects it for new toolchains. In a module, a constraint usinggo1.Nalso sets the language version for that file, which is how a file can use an older loop-variable meaning (see Loop variable semantics). - Old
// +buildlines. Before Go 1.17 constraints were written// +build linux,amd64. New code uses only//go:build;gofmtconverts old lines andgo vetchecks that both agree if both are present. - Do not overuse. Many tags multiply the combinations you need to test. Prefer runtime checks (
runtime.GOOS) for small differences that compile everywhere. - See what is selected.
go list -f '{{.GoFiles}} {{.IgnoredGoFiles}}' .shows which files were used and which were excluded.