How to Use Conditional Compilation and Build Tags in Go

Conditional compilation lets developers include or exclude code at build time, which is essential for writing cross‑platform libraries where operating‑system APIs differ. In C/C++ this is usually done with #ifdef macros, as shown in the example that selects a Windows‑specific HFILE type or a generic int type.

Go does not use preprocessor macros; instead it relies on two mechanisms:

File‑name suffixes of the form name_{system}_{arch}.go (or *_test.go) where system matches the GOOS environment variable (e.g., windows, linux, darwin) and arch matches GOARCH (e.g., amd64, arm64). Files without a suffix are compiled for all platforms.

Build tags written as //go:build expressions at the top of a file. The expression can contain tag names and Boolean operators. Examples:

//go:build !windows
//go:build linux && (arm64 || amd64)
//go:build ignore
//go:build customTag

These tags control whether the file participates in the build, and custom tags can be activated with go build -tags customTag.

Using file‑name suffixes is straightforward but can lead to duplicated platform‑independent code, which makes maintenance harder. It works best when the platform differences are large, such as Go's own runtime implementation.

Build tags allow shared files to contain both platform‑specific and common logic, reducing duplication. The article demonstrates this with a zero‑overhead logging library. Two sets of files are provided:

// file log_debug.go
//go:build debug || (!info && !warning)
package log

import "fmt"

func Debug(msg any) { fmt.Println("DEBUG:", msg) }

// file log_no_debug.go
//go:build info || warning
package log

func Debug(_ any) {}

// file log_info.go
//go:build !debug && !warning
package log

import "fmt"

func Info(msg any) { fmt.Println("INFO:", msg) }

// file log_no_info.go
//go:build warning
package log

func Info(_ any) {}

// file log_warning.go
package log

import "fmt"

func Warning(msg any) { fmt.Println("WARN:", msg) }

When the appropriate tags are supplied, only the relevant functions are compiled; the others become empty stubs, eliminating any runtime cost. A simple test shows the expected output for the default build, a build with the info tag, and a build with the warning tag.

$ go run
DEBUG: A debug level message
INFO: A info level message
WARN: A warning level message

$ go run -tags info .
INFO: A info level message
WARN: A warning level message

$ go run -tags warning .
WARN: A warning level message

The author warns that this approach should be used only when the performance impact of a regular if check is proven to be a bottleneck, because maintaining duplicate files and complex tag expressions can be error‑prone.

Finally, the article mentions a real‑world use case: the dependency‑injection tool wire places code behind custom build tags so that the code is only compiled when wire generates the injection files, demonstrating how tags can integrate with build pipelines without inflating the final binary.