Compiler directives and intrinsics

A compiler directive is a comment with a fixed prefix that the toolchain reads: //go:build selects a file, //go:embed fills a variable, //go:noinline stops the inliner, //go:generate names a command for go generate. They live in the toolchain, not the language, and an application needs three of them at most. Part 9 ends with the ones a program can observe.

go:noinline and the inliner

The inliner decides which calls to replace with the body of the function. //go:noinline above a declaration keeps the call, which a profiler or a stack trace needs to see the function as a frame. The program has a small function the compiler inlines and a marked one it cannot; the report below is filtered to those two decisions.

package main import "fmt" func add(a, b int) int { return a + b } //go:noinline func keep(a, b int) int { return a * b } func main() { fmt.Println("add:", add(2, 3)) fmt.Println("keep:", keep(2, 3)) }

go build -o app main.go && ./app

add: 5
keep: 6

go build -gcflags='-m=2' main.go 2>&1 | grep -E 'can inline|noinline'

./main.go:5:6: can inline add
./main.go:10:6: cannot inline keep: marked go:noinline

The first line says the compiler will replace a call to add with its body, the second says the directive stopped it for keep. -m=2 prints the reason for every decision and is the flag to reach for when a profile shows a function that should have been inlined and was not.

The directive in a stack trace

The same directive is visible at run time: a panic inside a marked function leaves that function as a frame, with its name and its line. Without the mark the call could be inlined and the trace would show main.main with a different line, which is why a runtime package that must appear in a trace marks its functions.

package main //go:noinline func inner() { panic("boom") } func main() { inner() }

go build -trimpath -o app main.go && ./app

panic: boom

goroutine 1 [running]:
main.inner()
./main.go:5 +0x25
main.main()
./main.go:9 +0xf
exit status: 2

Both frames are there: the panic in inner and the call from main. A library that wraps a panic for its caller uses the depth of the stack at the recover point, and a noinline boundary is one way to guarantee the frame exists.

go:generate

go generate runs the commands named by //go:generate comments in the package directory. It is not part of go build, so a generated file is committed or rebuilt by the developer and the CI job. The program below carries a directive that echoes a line, and the generate run and the program run are both real.

//go:generate echo generated by go generate package main import "fmt" func main() { fmt.Println("the program itself") }

go generate main.go && go build -o app main.go && ./app

generated by go generate
the program itself

The echo is a stand-in for stringer, mockgen or a small program of the repository. A directive that runs a tool installed on the machine is a build input nobody sees, which is why a generated file carries a header saying how it was made and the command is in the README.

go:build and file names

A build constraint at the top of a file, before the package clause and followed by a blank line, selects the file for a set of targets. The file suffix _linux does the same for a system and _amd64 for an architecture, and the two can be combined. The module below has one file per system and a shared one, and go list shows which files each target takes.

// main_linux.go //go:build linux package main import "fmt" func main() { fmt.Println("linux build") } // main_other.go //go:build !linux package main import "fmt" func main() { fmt.Println("other build") }

GOOS=linux go list -f '{{.GoFiles}}' . && GOOS=darwin go list -f '{{.GoFiles}}' . && go build -o app . && ./app

[helpers.go main_linux.go]
[helpers.go main_other.go]
linux build

The list for Linux has the linux file and the list for Darwin the other, and the shared helper is in both. The block above is the shape of the two files rather than a program run on its own, which is why it uses the plain code class: only one of the two can build on this machine.

The directives a program needs

An application needs //go:build for a platform file, //go:embed for an asset and //go:generate for a generated file. //go:noinline belongs to a runtime or a profiler, //go:nosplit and //go:linkname belong to the runtime, and a program that needs them is doing something the standard library has not exposed. The last group is the intrinsics: functions such as sync/atomic and math/bits that the compiler turns into a single instruction, with no directive to write.

Part 9 is over. The next part is a project: a JSON tokenizer, a parser, a value type, a writer, tests, a command line tool and a benchmark, one lesson each, built the way a small library is built.

Exercises

  1. Move the //go:noinline above add and read the report again. Which line changes, and what does the compiler say about the function now?
  2. Add a second //go:generate line that runs go version and run go generate. In which order do the commands run?
  3. Add a file with //go:build windows to the tags module and list the files for three systems. Which list has two main functions, and which error does a build give?

Questions

A new set of questions in a new order every time. Choose one answer for each, then check.

  1. What is a compiler directive?

    Answer

    A comment with a fixed prefix that the toolchain reads

    It lives in the toolchain, not the language.

  2. What does go:noinline do?

    Answer

    Stops the inliner from replacing the call

    The frame stays visible.

  3. Which flag prints the inlining decisions?

    Answer

    -gcflags=-m=2

    It prints the reason per decision.

  4. What does go generate run?

    Answer

    The commands in go:generate comments of the package

    It is a separate command, not part of build.

  5. Where must a build constraint be?

    Answer

    Before the package clause, followed by a blank line

    The suffix form is the alternative.

  6. What does the file suffix _linux do?

    Answer

    Includes the file only for Linux

    It is a build constraint in the name.

  7. Which directive embeds a file?

    Answer

    //go:embed

    It fills a string, []byte or embed.FS.

  8. Which directives belong to the runtime?

    Answer

    go:nosplit and go:linkname

    An application should not need them.

  9. What is an intrinsic?

    Answer

    A function the compiler turns into one instruction

    sync/atomic and math/bits are full of them.

  10. Why commit a generated file?

    Answer

    The tool that makes it may not be on every machine

    The build must not depend on an unseen tool.

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