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:generate stringer -type=Color //go:embed templates/*.html //go:debug panicnil=1
Try it
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.
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; useimport _ "embed"when onlystringor[]bytevariables 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_. Writeall:dirto include those too. - A
stringor[]bytevariable needs exactly one file. Anembed.FScan 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:embedand//go:Embeddo nothing. A wrongly placed//go:embedproduces 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.FSkeeps the file names and a read-only tree, so usefs.Subto serve a subdirectory. - Generated code is checked in.
go generateis never run bygo build. Commit the files it produces, and start them with the line// Code generated by ... DO NOT EDIT.so tools can recognize them. //go:noinlineis for experiments. If you add it to production code to "fix" something, measure first. It changes performance, not correctness.//go:linknameis fragile. The linked symbol can change in any release. Prefer the public API.//linedirectives (nogo:) change the file name and line number reported for the following code. Code generators use them to point errors back at the original source.