Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท The go Command and Tools

Go //go: directives

Reference for Go compiler directives: //go:embed, //go:generate, //go:debug, //go:build, //go:noinline, //go:linkname and //go:nosplit, with syntax rules.

A directive is a special comment that is read by the go command, the compiler or the linker instead of by people. Directives start with //go: (or //line, //export) with no space after the slashes. A comment such as // go:embed x with a space is just a comment, and the tool silently ignores it, which is the most common reason a directive appears not to work.

Some directives are part of everyday programming: //go:embed puts files into your binary, //go:generate records a command for go generate to run, //go:build selects files (see Build constraints) and //go:debug sets runtime compatibility settings for a program. Others are low-level hints for compiler and runtime authors.

Go
//go:generate stringer -type=Color
//go:embed templates/*.html
//go:debug panicnil=1

Try it

Go //go:embed with the program's own source

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.

Go //go:debug and panic(nil)

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

A directive is a line comment, usually written directly above the declaration it applies to. If it belongs to a variable or function with a doc comment, put it at the end of that comment, separated by an empty // line; gofmt moves it there.

Directive Where Description
//go:build expr Top of file Build constraint. See Build constraints.
//go:embed patterns Directly above a package-level var Fills a string, []byte or embed.FS variable with file contents.
//go:generate command args Anywhere in a .go file A command that go generate runs. Ignored by every other command.
//go:debug name=value Before package main Sets a GODEBUG default for this program (Go 1.21). Only the main package may have it.
//go:noinline Above a function The compiler must not inline calls. Used in benchmarks and tests of inlining.
//go:nosplit Above a function No stack-growth check; for runtime code with tiny frames.
//go:noescape Above a body-less function Promises that pointer arguments do not escape. Assembly only.
//go:linkname local importpath.name Anywhere Links a symbol to one in another package. Restricted since Go 1.23: the linker refuses most "pull" links into the standard library.
//go:wasmimport module name, //go:wasmexport name Above a function WebAssembly host imports (Go 1.21) and exports (Go 1.24).

//go:embed rules.

  • The package must import embed; use import _ "embed" when only string or []byte variables are used.
  • Patterns are relative to the source file's directory, use /, may contain * and ?, and must not contain . or .. elements or leave the module. One line may list several patterns, separated by spaces.
  • A directory pattern includes its files recursively, except names starting with . or _. Write all:dir to include those too.
  • A string or []byte variable needs exactly one file. An embed.FS can hold many, and is read-only and safe for concurrent use.
  • The variable must be at package level and may not be initialized with a value.

//go:generate rules. The command is split at spaces; double quotes group words. These variables are expanded: $GOFILE, $GOLINE, $GOPACKAGE, $GOOS, $GOARCH, $GOROOT, $DOLLAR and $PATH. The command runs in the package directory. Flags: -run regexp, -skip regexp, -n (print only), -x (print and run), -v.

//go:debug rules. The value is a known setting from the GODEBUG list, such as panicnil=1, httpmuxgo121=1 or asynctimerchan=1. Unknown names make the build fail. The same setting can also be given as a godebug line in go.mod or go.work, which suits a module with several programs. In our online runner there is no go.mod, so the //go:debug line is the way to set one.

Usage notes

  • Check the spelling. //go:embeed, // go:embed and //go:Embed do nothing. A wrongly placed //go:embed produces a compile error ("misplaced go:embed directive") because the compiler does look at it.
  • Embedded files are fixed at build time. Changing the file afterwards has no effect on a built binary. An embed.FS keeps the file names and a read-only tree, so use fs.Sub to serve a subdirectory.
  • Generated code is checked in. go generate is never run by go build. Commit the files it produces, and start them with the line // Code generated by ... DO NOT EDIT. so tools can recognize them.
  • //go:noinline is for experiments. If you add it to production code to "fix" something, measure first. It changes performance, not correctness.
  • //go:linkname is fragile. The linked symbol can change in any release. Prefer the public API.
  • //line directives (no go:) change the file name and line number reported for the following code. Code generators use them to point errors back at the original source.