Build Constraints & Platform-Specific Files

Build constraints tell the Go toolchain which source files belong in a given build.

You express them with //go:build lines, file suffixes, and custom tags passed via -tags.

The result is one module tree that compiles different implementations per OS, architecture, or feature flag.

Summary

Before Go 1.17, constraints used // +build comment lines.

Modern code should use //go:build as the first line of a file (optionally followed by blank line and package).

The toolchain evaluates constraints against GOOS, GOARCH, and custom tags.

Files without constraints are always included; platform-specific files should provide fallbacks or live behind matching tags only.

Recipe

Quick-reference recipe card - copy-paste ready.

//go:build linux && amd64
 
package sysfs
 
// linux_amd64 implementation

go build -tags=integration ./...
GOOS=windows GOARCH=arm64 go build ./...

When to reach for this:

• Calling OS-specific APIs (syscall, x/sys) without runtime if runtime.GOOS sprawl.
• Shipping arch-tuned code (SIMD, pointer size assumptions) in separate files.
• Gating integration tests, FIPS builds, or enterprise feature sets.
• Excluding cgo files on platforms where the C toolchain is unavailable.

Working Example

example.com/net/
  listen.go
  listen_unix.go
  listen_windows.go

// listen.go - all platforms
package net
 
func DefaultListenConfig() ListenConfig {
    return ListenConfig{}
}
 
type ListenConfig struct {
    ReusePort bool
}

// listen_unix.go
//go:build unix
 
package net
 
func (c ListenConfig) platformReuse() bool { return c.ReusePort }

// listen_windows.go
//go:build windows
 
package net
 
func (c ListenConfig) platformReuse() bool { return false } // SO_REUSEPORT unlike Windows

// demo/main.go
package main
 
import (
    "fmt"
    "example.com/net"
)
 
func main() {
    cfg := net.DefaultListenConfig()
    cfg.ReusePort = true
    fmt.Println("reuse supported:", cfg.platformReuse())
}

What this demonstrates:

• Shared API in neutral files; platform deltas in tagged files.
• unix is a predefined tag covering Linux, BSD, macOS, and other Unix-like GOOS values.
• The same package name compiles different bodies per platform without import changes.

Deep Dive

How It Works

1. go build collects all .go files in the package directory.
2. For each file, the toolchain evaluates build constraints (explicit line or suffix-derived).
3. Files with false constraints are excluded from the package for that build.
4. GOOS, GOARCH, and -tags values form the evaluation environment.
5. The compiler proceeds with the remaining file set as one package.

Predefined Tags

File Suffix Shorthand

Suffix rules combine with explicit //go:build lines when both are present.

Boolean Expressions

//go:build (linux || darwin) && amd64
//go:build !windows
//go:build integration && !short

Use parentheses for precedence.

Go Notes

go list -tags=integration -f '{{.GoFiles}}' ./...

Inspect selected files before debugging "undefined symbol" build failures.

Gotchas

• Missing fallback implementation - tagging only linux leaves other GOOS without required functions. Fix: add default.go or !linux file with portable code.
• Runtime GOOS checks instead of tags - compiles forbidden imports on other platforms. Fix: move imports behind build-tagged files.
• Drift between suffix and explicit tag - _foo.go plus conflicting //go:build confuses readers. Fix: prefer one style per file.
• Forgetting CI matrix - only building linux/amd64 hides broken Windows files. Fix: cross-compile GOOS=windows in CI at minimum.
• Custom tags undocumented - teammates run go test without -tags and skip suites silently. Fix: document tags in Makefile and README.
• Legacy // +build only - still works but gofmt rewrites to //go:build in modern toolchains. Fix: migrate on touch.

Alternatives

FAQs

Related

• Beyond the Spec: Embed, Build Modes, and Assembly - toolchain big picture
• Advanced Language Features Basics - tag and suffix examples
• Assembly in Go (*.s files) - arch-specific .s files
• CGO Basics - cgo gated behind tags on some teams

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).