Directives, Code Generation and Embedding

stringer is the traditional generator for enumerations but lives in golang.org/x/tools and must be installed. The example uses the same pattern with a generator inside the module, so go generate needs nothing else. It reads the declaring file named by GOFILE and writes a String method for the LoanState enumeration from the shelf scenario.

Source: cmd/go: Generate Go files by processing source

Before generating, Println shows raw integers because LoanState has no String method. go generate -x -v prints each file scanned (-v) and each command run (-x):

The generated loanstate_string.go is ordinary source that is committed: a Code generated … DO NOT EDIT. header, a names array and a String method that returns LoanState(N) for out-of-range values (hence LoanState(9) above).

Source: cmd/go: Generate Go files by processing source and The Go Blog: Generating code

//go:generate -command name args… defines an alias that lasts for the rest of that file only. -run regexp and -skip regexp select directives by matching the directive’s full original text, including //go:generate and any alias name; -n prints commands without running them. This file has a failing third directive:

Source: cmd/go: Generate Go files by processing source

The failing sh -c "exit 3" stopped the package, so never-reached never ran. -run second alone printed nothing because the -command say directive was filtered out too and the alias was never defined; a selecting expression must also match it.

A generator that does not need to be a package can be a single file excluded from the build with //go:build ignore. The tag ignore is never satisfied, so the file is listed under IgnoredGoFiles, yet go run gen.go still compiles it because files named on the command line bypass constraints. gen.go turns a text file of classification codes into a Go table:

gen.go starts with //go:build ignore, opens classes.txt, writes one "code": "name" map entry per line into a string builder and passes the result through go/format.Source before writing classes_table.go, whose first line is // Code generated by gen.go; DO NOT EDIT..

The package side is //go:generate go run gen.go above a main that prints len(deweyClasses) and deweyClasses["800"]:

The first command shows the cost of the model: until the generated file exists the package does not compile. That is why generated files are committed and why go generate is a documented developer step. A CI job can check freshness by running go generate ./... and failing on a non-empty git diff --exit-code.

Source: cmd/go: Build constraints

stringer generates String methods for integer types declared with iota. It was not installed on the machine used to check this page, so the following comes from its documentation and is not run here:

Useful flags are -type (comma-separated type names), -trimprefix, -linecomment (use the trailing line comment of each constant as its name), -output and -tags. The generated loanstate_string.go consists of a compile-time assertion that the constants have not changed (an "invalid array index" error means regenerate), one concatenated name string, an index table such as _LoanState_index = [...]uint8{0, 9, 17, 23, 30}, and a String method that falls back to LoanState(N). Compared with the hand-written generator above it packs all names into one string and notices when a constant is inserted. The go tool form pins the generator in go.mod and removes the old tools.go file with a blank import; see Modules and Dependency Management for the tool directive and Variables, Constants and iota for enumerations.

Source: golang.org/x/tools/cmd/stringer and Go 1.24 release notes: tool directives

Each restriction has its own message, produced by one-file variants of the program:

In order: no match, a .. path, a file in a nested module (a directory with its own go.mod), an unsupported type, a variable with an initializer, a missing embed import (top level, then inside a function, where a local variable cannot be embedded anyway), and a directive above a const.

The classic use is a web UI shipped inside the server binary. fs.Sub re-roots the tree so URLs do not repeat the directory name, http.FileServerFS serves any fs.FS, and http.ServeFileFS serves one file. httptest.NewServer keeps the output deterministic and needs no fixed port.

The content type comes from the extension. .htaccess is a 404 only because the directive named the directory without all:; with all:web/static hidden files become public. Anyone with the binary can extract embedded data, so never embed credentials. Because modification times are zero, responses carry no Last-Modified header; set an ETag or use content-hashed file names when caching matters. For http.Server see net/http Clients and Servers, for template.ParseFS on an embed.FS see Text and HTML Templates, and for io/fs and os.DirFS (a development build can read the same tree from disk) see I/O, Files and the Filesystem.

Source: net/http: FileServerFS and net/http/httptest

-gcflags=-m makes the compiler explain inlining and escape decisions; more m`s give more detail. Two functions share one body, and one is marked `//go:noinline:

Once newBook is inlined into main (line 20), the &Book{...} does not escape and can live on the stack, while the non-inlinable copy allocates on the heap. main itself is too costly to inline (cost 152 against a budget of 80). Escape analysis and the allocator are in Memory Management and Garbage Collection, and profile-guided inlining of hot calls is in Performance and PGO.

Source: cmd/compile: Compiler Directives

Every ordinary function starts by comparing the stack pointer with a limit and calls into the runtime to grow the goroutine stack when needed. //go:nosplit removes that check, so the function may use only a small fixed amount of stack. The linker enforces it by adding frame sizes along every nosplit call chain: a nosplit function with a 4000-byte array that calls another function fails to link. The same function without the call compiles, because only chains that might need to grow the stack are checked.

The directive exists for the scheduler, allocator and signal handlers, which run where growing the stack is impossible. //go:noescape is accepted on a function without a body, implemented in assembly; a Go function with no body and no .s file is the error ./main.go:4:6: missing function body. The directive promises that the assembly keeps no pointer argument, so callers may pass pointers to stack variables; a false promise means memory corruption. See unsafe and Low-Level Programming.

Many third-party packages had pulled unexported runtime functions through linkname, which made it impossible to change runtime internals without breaking them. Go 1.23 made the linker reject any reference to a symbol in the standard library (including the runtime) that is not marked //go:linkname on its definition. Uses found in a large open-source corpus stay supported, but new ones fail. Pulling runtime.casgstatus, which is not marked:

The compiler accepts the file; the link step fails. -checklinkname=0 disables the check "for debugging and experimenting purposes", but the program then depends on internals that can change in any release. A symbol that does not exist fails differently, with relocation target … not defined. When a hook is wanted, prefer asking for a supported exported API.

Source: Go 1.23 release notes: Linker and cmd/compile: Linkname Directive