Build tags and file suffixes
A build constraint is a comment on the first line of a file that tells the toolchain when to compile it. It is how one package holds a Linux and a Windows implementation of the same function without an interface or a runtime check, and how a debug-only helper stays out of a release binary. The previous lesson changed which modules a build sees; this one changes which files.
A //go:build line
The line must be //go:build linux with no space after the slashes, before the package clause and after any other comment that is not a build constraint. The expression supports &&, ||, ! and parentheses, so //go:build linux && amd64 is a valid constraint. The older // +build form is still accepted but should not be written in new code.
//go:build linux
package main
func Platform() string {
return "linux build"
}
go list -f '{{join .GoFiles " "}}' .
main.go platform_linux.go
go run .
linux build
go list -tags debug -f '{{join .GoFiles " "}}' .
debug.go main.go platform_linux.go
go run -tags debug .
debug extras enabled
linux build
The first list has main.go platform_linux.go and not the Windows file, because the host is Linux; the run printed the Linux string. With -tags debug the list grew by debug.go and its init printed before main. The Windows file exists in the package and is simply not part of this build.
File name suffixes
A file whose name ends in _linux.go, _windows.go or _arm64.go gets the matching constraint implicitly, which is why the two platform files above are named that way even though they also carry an explicit line. The suffix is the older and still the most common form, and the two must agree: a file named _windows.go with //go:build linux is never built on either system.
Mistakes that do nothing
A constraint after a blank line, after the package clause, or spelled with a space (// go:build) is just a comment: the file is built everywhere and the duplicate definition breaks the build or, worse, the wrong implementation is used. A missing blank line between the constraint and the package clause is a compile error rather than a silent one, but the others are silent. go list -f with the GoFiles template is the check: it prints the files the build actually selected.
Exercises
- Add a platform_darwin.go and build for macOS with GOOS=darwin. Which file does the build list contain?
- Write a file that is only built with -tags integration and contains a test helper. What happens to the release binary?
- Break a constraint on purpose: move it below the package clause and run the tests. What error or behaviour proves it was ignored?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Where must a //go:build line be?
Answer
Before the package clause, after other comments, with no space after //
The position and the exact spelling are part of the syntax.
-
What does the _linux.go suffix do?
Answer
Adds an implicit linux constraint to the file
The suffix and an explicit constraint can both be present.
-
What does go run -tags debug do?
Answer
Includes files constrained by the debug tag
Custom tags are a build input, not a runtime setting.
-
Which operators does a constraint expression support?
Answer
&&, || and ! with parentheses
The expression language is small and boolean.
-
What does go list -f '{{.GoFiles}}' show?
Answer
The files the current build selected
It is the quickest way to see whether a constraint worked.
-
What happens to a constraint written after a blank line?
Answer
It is treated as a plain comment and the file is built everywhere
That is the silent mistake the section warns about.
-
Why keep one implementation per platform in the same package?
Answer
The caller compiles against one function and the build picks the file
The package API stays the same; only the file changes with the target.
-
What does // +build mean today?
Answer
The older constraint syntax, still accepted but not to be written
New code uses //go:build only.
-
What does GOOS affect in a build?
Answer
The target operating system and which suffix files are included
It is the platform switch, and the suffixes follow it.
-
Why can a mixed suffix and constraint be a bug?
Answer
The file is built only when both agree, so it may never be built
A _windows.go file with a linux constraint is dead in every build.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev