These are the notes for Go episode 76. Raju's shop app prints order statuses as numbers ("order 1042 is 2"), like a station board that says "status 2". A hand-written String() method fixes that, until someone adds a status in the middle of the list: then one order prints the wrong name and another panics. From there we invent code generation (let a program write the boring code), then go one level deeper and write programs that read Go code: tokens, syntax trees, types, and our own checker, the same building blocks the compiler, gofmt, go vet and the gopls editor server use. We finish with the compiler directives: comments that give instructions to the Go toolchain.
All outputs below are from real runs (Go 1.24.7, linux/amd64, 14 November 2026), through the same runner the video's compiler uses. The runner prints each command as $ command and prints the error stream (stderr) after the normal output. golang.org/x/tools is version v0.42.0, the newest release whose go.mod still accepts Go 1.24 (v0.43.0 and later need Go 1.25).
Facts and sources
go help generate(Go 1.24.7): "Generate runs commands described by directives within existing files. Those commands can run any process but the intent is to create or update Go source files." "Go generate is never run automatically by go build, go test, and so on. It must be run explicitly." The directive is//go:generate command argument..."(note: no leading spaces and no space in "//go")". "Go generate does not parse the file, so lines that look like directives in comments or multiline strings will be treated as directives." Generated files should contain a line matching^// Code generated .* DO NOT EDIT\.$before the first non-comment text. It sets$GOARCH,$GOOS,$GOFILE,$GOLINE,$GOPACKAGE,$GOROOT,$DOLLARand$PATHfor the command.- stringer (package doc in
golang.org/x/tools/cmd/stringer): "Stringer is a tool to automate the creation of methods that satisfy the fmt.Stringer interface." It works on "a (signed or unsigned) integer type T that has constants defined"; "The default output file is t_string.go, where t is the lower-cased name of the first type listed"; "Typically this process would be run using go generate"; the-typeflag "accepts a comma-separated list of types". - Go standard library docs (
go doc, Go 1.24.7): go/token "defines constants representing the lexical tokens of the Go programming language and basic operations on tokens (printing, predicates)"; go/parser "implements a parser for Go source files"; go/ast "declares the types used to represent syntax trees for Go packages"; go/types "declares the data types and implements the algorithms for type-checking of Go packages"; text/template "implements data-driven templates for generating textual output". - go/analysis package doc (x/tools): "A static analysis is a function that inspects a package of Go code and reports a set of diagnostics (typically mistakes in the code)". "An analysis that reports mistakes is informally called a "checker"." Drivers include "command-line tools (such as vet), text editors and IDEs". singlechecker "defines the main function for an analysis driver with only a single analyzer".
- gopls README and
doc/index.md(github.com/golang/tools): "gopls(pronounced "Go please") is the official language server for Go, developed and maintained by the Go team." It works with "any LSP-compatible editor"; the editors listed include VS Code, Vim or Neovim, Emacs, Helix, Sublime Text and Zed. Install withgo install golang.org/x/tools/gopls@latest.doc/command-line.md: the gopls command line "is currently experimental and subject to change at any point", and "Its primary use is as a debugging aid." - cmd/compile documentation (Go 1.24.7 source, "Compiler Directives"): directives are comments with "no space between the comment opening and the name of the directive".
//go:noinline"specifies that calls to the function should not be inlined, overriding the compiler's usual optimization rules. This is typically only needed for special runtime functions or when debugging the compiler."//go:nosplit"specifies that the function must omit its usual stack overflow check. This is most commonly used by low-level runtime code invoked at times when it is unsafe for the calling goroutine to be preempted." - embed package doc: "Go source files that import "embed" can use the //go:embed directive to initialize a variable of type string, []byte, or FS with the contents of files read from the package directory or subdirectories at compile time."
- The go.dev blog post on
go generatecould not be fetched in this run, so every quote above comes from the documentation that ships with Go 1.24.7 and from the x/tools source.
The problem: statuses print as numbers
A railway station board that says "Train 12951, status 2" tells you nothing. Raju's app has the same problem. Status is a defined integer type (episode 19) and iota (episode 5) numbers its constants:
main.go:
package main
import "fmt"
type Status int // an order's status, stored as a number
const (
Placed Status = iota // 0
Packed // 1
Shipped // 2
Delivered // 3
)
func main() {
s := Shipped
fmt.Println("order 1042 is", s)
fmt.Printf("%v %d\n", Delivered, Delivered)
}
Commands:
$ go run .
Output:
$ go run .
order 1042 is 2
3 3
%v and %d both print 3. From episode 21: if a type has a method String() string, it satisfies the fmt.Stringer interface, and fmt calls that method to print the value. So the first fix is a String() method.
The obvious fix fails: a hand-written String()
A String() written last month, when there were four statuses, indexes an array of names. Today someone added OutForDelivery in the middle:
main.go:
package main
import "fmt"
type Status int
const (
Placed Status = iota
Packed
OutForDelivery // new status, added in the middle
Shipped
Delivered
)
// String was written by hand, back when there were four statuses.
func (s Status) String() string {
return [...]string{"Placed", "Packed", "Shipped", "Delivered"}[s]
}
func main() {
fmt.Println("order 1042 is", Shipped)
fmt.Println("order 1043 is", Delivered)
}
Commands:
$ go run .
Output:
$ go run .
order 1042 is Delivered
order 1043 is %!v(PANIC=String method: runtime error: index out of range [4] with length 4)
Two bugs from one change:
Shippedis now 3, and the array's index 3 is"Delivered": a wrong answer that looks right.Deliveredis now 4, past the end of a 4-element array: a panic.fmtrecovers panics insideStringmethods and prints them as%!v(PANIC=String method: ...), which is why the program didn't crash.
Why it failed: the constant list and the list of names are two lists that must match, and a human keeps them in sync. With 12 statuses, 6 enums and 3 teams, someone always forgets. But the String() code is completely predictable from the constants, so a program can write it.
Code generation, go generate and stringer
Code generation means a program (a generator) writes source code for you. Think of a wedding card shop: the guest list is the input, one card design with a blank for the name is the template, and the printing press prints all 300 cards with no typos.
Go's tool for running generators is go generate. It looks for directives, comments that give an instruction to a Go tool, of the form //go:generate command args, and runs each command. stringer is a generator from golang.org/x/tools that writes String() methods:
go.mod:
module shop
go 1.24
require golang.org/x/tools v0.42.0
status.go:
package main
//go:generate go run golang.org/x/tools/cmd/stringer -type=Status
type Status int
const (
Placed Status = iota
Packed
OutForDelivery
Shipped
Delivered
)
main.go:
package main
import "fmt"
func main() {
fmt.Println("order 1042 is", Shipped)
fmt.Println("order 1043 is", Delivered)
fmt.Println("bad value:", Status(9))
}
show/main.go:
package main // a tiny helper: prints the first 14 lines of a file
import (
"fmt"
"os"
"strings"
)
func main() {
b, _ := os.ReadFile(os.Args[1])
fmt.Println(strings.Join(strings.Split(string(b), "\n")[:14], "\n"))
}
Commands:
$ go generate ./...
$ go run .
$ go run ./show status_string.go
Output:
$ go generate ./...
$ go run .
order 1042 is Shipped
order 1043 is Delivered
bad value: Status(9)
$ go run ./show status_string.go
// Code generated by "stringer -type=Status"; DO NOT EDIT.
package main
import "strconv"
func _() {
// An "invalid array index" compiler error signifies that the constant values have changed.
// Re-run the stringer command to generate them again.
var x [1]struct{}
_ = x[Placed-0]
_ = x[Packed-1]
_ = x[OutForDelivery-2]
_ = x[Shipped-3]
go generate ./...ran the directive instatus.go../...means "this package and every package below it".go run golang.org/x/tools/cmd/stringerruns stringer at the version ingo.mod, so nobody has to install it first.- An unknown value prints
Status(9)instead of panicking. - The generated file starts with the standard
Code generated ... DO NOT EDIT.line.
The full generated file (status_string.go):
// Code generated by "stringer -type=Status"; DO NOT EDIT.
package main
import "strconv"
func _() {
// An "invalid array index" compiler error signifies that the constant values have changed.
// Re-run the stringer command to generate them again.
var x [1]struct{}
_ = x[Placed-0]
_ = x[Packed-1]
_ = x[OutForDelivery-2]
_ = x[Shipped-3]
_ = x[Delivered-4]
}
const _Status_name = "PlacedPackedOutForDeliveryShippedDelivered"
var _Status_index = [...]uint8{0, 6, 12, 26, 33, 42}
func (i Status) String() string {
idx := int(i) - 0
if i < 0 || idx >= len(_Status_index)-1 {
return "Status(" + strconv.FormatInt(int64(i), 10) + ")"
}
return _Status_name[_Status_index[idx]:_Status_index[idx+1]]
}
All names are stored in one string, _Status_name, and _Status_index holds where each name starts: Shipped is bytes 26 to 33. The odd func _() is a compile-time check: x has length 1, so x[Placed-0] only compiles while Placed is still 0, x[Packed-1] while Packed is still 1, and so on.
The rules of go generate
| Rule | Detail |
|---|---|
| Never automatic | go build and go test never run it. You run it when the inputs change, then commit the generated files so anyone can build without the generator. |
| Exact spelling | //go:generate with no space after // and no leading spaces. // go:generate is an ordinary comment. |
| No parsing | It scans lines; a line inside a multi-line string that looks like a directive is run too. |
| Variables | $GOFILE, $GOLINE, $GOPACKAGE, $GOOS, $GOARCH, $GOROOT, $DOLLAR. Example: //go:generate echo $GOFILE |
| Header | Generated files should contain // Code generated <by what>; DO NOT EDIT. Editors, linters and reviewers treat such files as generated. |
| Flags | go generate -n prints the commands without running them, -x prints and runs, -run regexp runs only matching directives. |
A stale generated file is caught at build time
A teammate adds Cancelled and forgets go generate. The helper teammate simulates that edit:
go.mod:
module shop
go 1.24
require golang.org/x/tools v0.42.0
status.go:
package main
//go:generate go run golang.org/x/tools/cmd/stringer -type=Status
type Status int
const (
Placed Status = iota
Packed
Shipped
)
main.go:
package main
import "fmt"
func main() { fmt.Println(Placed, Packed, Shipped, Status(1)) }
teammate/main.go:
package main // a teammate adds a status and forgets go generate
import (
"os"
"strings"
)
func main() {
b, _ := os.ReadFile("status.go")
s := strings.Replace(string(b), " Packed\n", " Cancelled\n Packed\n", 1)
os.WriteFile("status.go", []byte(s), 0o644)
}
Commands:
$ go generate ./...
$ go run ./teammate
$ go build .
$ go generate ./...
$ go run .
Output (normal output, then the error stream):
$ go generate ./...
$ go run ./teammate
$ go build .
$ go generate ./...
$ go run .
Placed Packed Shipped Cancelled
# shop
./status_string.go:12:8: invalid argument: index 1 out of bounds [0:1]
./status_string.go:13:8: invalid argument: index 1 out of bounds [0:1]
go build . failed because of the compile check: Packed is now 2, so x[Packed-1] is x[1], out of bounds for an array of length 1. The comment in the generated file calls it an "invalid array index" error; Go 1.24 words it as invalid argument: index 1 out of bounds [0:1]. Running go generate again rewrote the file, and Status(1) now prints Cancelled. Many teams also run go generate ./... && git diff --exit-code in CI: if regenerating changes anything, someone forgot to commit the generated code.
Writing your own generator with text/template
Stringer covers one job. For your own data, write a generator. text/template fills a text template with data; go/format formats Go code exactly like gofmt:
menu.txt:
masala chai,1500
samosa,2000
filter coffee,2500
main.go:
package main
//go:generate go run ./gen menu.txt menu_gen.go
import "fmt"
func main() { fmt.Println(len(Menu), "items; samosa costs", Menu["samosa"], "paise") }
gen/main.go:
package main // the generator: menu.txt in, Go code out
import (
"bytes"
"go/format"
"os"
"strings"
"text/template"
)
var tmpl = template.Must(template.New("menu").Parse(`// Code generated by gen from {{.Src}}; DO NOT EDIT.
package main
var Menu = map[string]int{
{{- range .Items}}
{{printf "%q" .Name}}: {{.Paise}},
{{- end}}
}
`))
type Item struct{ Name, Paise string }
func main() {
src, out := os.Args[1], os.Args[2]
b, _ := os.ReadFile(src)
var items []Item
for _, line := range strings.Split(strings.TrimSpace(string(b)), "\n") {
name, paise, _ := strings.Cut(line, ",")
items = append(items, Item{name, paise})
}
var buf bytes.Buffer
tmpl.Execute(&buf, map[string]any{"Src": src, "Items": items})
code, err := format.Source(buf.Bytes()) // gofmt the generated code
if err != nil {
panic(err)
}
os.WriteFile(out, code, 0o644)
os.Stdout.Write(code) // and show it
}
Commands:
$ go generate ./...
$ go run .
Output:
$ go generate ./...
// Code generated by gen from menu.txt; DO NOT EDIT.
package main
var Menu = map[string]int{
"masala chai": 1500,
"samosa": 2000,
"filter coffee": 2500,
}
$ go run .
3 items; samosa costs 2000 paise
Template basics:
| Syntax | Meaning | Example |
|---|---|---|
{{ }} |
an action: something to evaluate | {{.Src}} |
. (dot) |
the current data: the whole input at the top, each element inside range |
{{.Name}} |
{{range .Items}} ... {{end}} |
repeat for each element | one map entry per item |
{{printf "%q" .Name}} |
call a function; %q makes a quoted Go string |
"masala chai" |
{{- and -}} |
trim the white space before / after the action | no blank lines |
format.Source returns an error when the generated text isn't valid Go, so a broken template is caught right away (we panic with that error). Generate readable code: it is reviewed and debugged like any other code.
Reading Go code, step 1: tokens (go/scanner, go/token)
How did stringer find our constants? It read our Go code. A teacher reading an essay first sees words and full stops, then sentences, then meaning. Go has a package for each step.
A token is the smallest meaningful piece of code: a name, an operator, a number, a comment. go/scanner splits text into tokens; go/token defines the token kinds (IDENT, INT, :=...) and the FileSet, which remembers files so every position (token.Pos, just a number) can be turned into file:line:column.
main.go:
package main
import (
"fmt"
"go/scanner"
"go/token"
)
func main() {
src := []byte("total := qty * 1500 // paise")
fset := token.NewFileSet()
file := fset.AddFile("line.go", -1, len(src))
var s scanner.Scanner
s.Init(file, src, nil, scanner.ScanComments)
for {
pos, tok, lit := s.Scan() // the next token: position, kind, text
if tok == token.EOF {
break
}
fmt.Printf("%-12v %-8s %q\n", fset.Position(pos), tok, lit)
}
}
Commands:
$ go run .
Output:
$ go run .
line.go:1:1 IDENT "total"
line.go:1:7 := ""
line.go:1:10 IDENT "qty"
line.go:1:14 * ""
line.go:1:16 INT "1500"
line.go:1:21 COMMENT "// paise"
line.go:1:29 ; "\n"
IDENT means identifier (a name). The last token is a ; with the text "\n": the semicolon the scanner inserts automatically at the end of a line (episode 1).
Step 2: syntax trees (go/parser, go/ast)
Parsing arranges tokens into a tree that shows the structure. go/parser builds an AST (abstract syntax tree): the code as a tree of nodes, each one a piece of the program such as a declaration, an expression or a statement. go/ast defines the node types, and ast.Inspect visits every node, depth first.
status.go:
package main
type Status int
const (
Placed Status = iota
Packed
Shipped
)
func ship(s Status) Status { return Shipped }
inspect/main.go:
package main // reads Go code the way stringer does
import (
"fmt"
"go/ast"
"go/parser"
"go/token"
"os"
)
func main() {
fset := token.NewFileSet() // remembers file names and line numbers
f, err := parser.ParseFile(fset, os.Args[1], nil, 0)
if err != nil {
fmt.Println(err)
return
}
ast.Inspect(f, func(n ast.Node) bool { // visit every node of the tree
switch x := n.(type) {
case *ast.TypeSpec:
fmt.Printf("%v: type %s\n", fset.Position(x.Pos()), x.Name)
case *ast.ValueSpec:
fmt.Printf("%v: const %s\n", fset.Position(x.Pos()), x.Names[0])
case *ast.FuncDecl:
fmt.Printf("%v: func %s\n", fset.Position(x.Pos()), x.Name)
}
return true
})
}
Commands:
$ go run ./inspect status.go
Output:
$ go run ./inspect status.go
status.go:3:6: type Status
status.go:6:5: const Placed
status.go:7:5: const Packed
status.go:8:5: const Shipped
status.go:11:1: func ship
The tree for the const block:
*ast.File package main
└── *ast.GenDecl (Tok: const) const ( ... )
├── *ast.ValueSpec Placed Status = iota
│ ├── Names: *ast.Ident Placed
│ ├── Type: *ast.Ident Status
│ └── Values: *ast.Ident iota
├── *ast.ValueSpec Packed
└── *ast.ValueSpec Shipped
Useful node types: *ast.File, *ast.GenDecl (import, const, type, var blocks), *ast.FuncDecl, *ast.TypeSpec, *ast.ValueSpec, *ast.Ident, *ast.CallExpr, *ast.BinaryExpr, *ast.AssignStmt. ast.Print(fset, node) dumps any node's whole tree, which is the fastest way to learn the shapes.
The AST is syntax only. It knows qty + rate is a *ast.BinaryExpr with Op: +, but not whether you can add those two things.
Step 3: meaning (go/types)
A type checker works out the type of every name and expression and reports type errors. go/types is Go's type checker as a library, the same checks as the compiler's front end:
bill.go:
package shop
func Bill(qty int, rate float64) float64 {
total := float64(qty) * rate
tax := total / 20
items := qty + rate
return total + tax + items
}
check/main.go:
package main // type-checks a file, like the compiler's front end
import (
"fmt"
"go/ast"
"go/importer"
"go/parser"
"go/token"
"go/types"
"os"
)
func main() {
fset := token.NewFileSet()
f, _ := parser.ParseFile(fset, os.Args[1], nil, 0)
conf := types.Config{
Importer: importer.Default(),
Error: func(err error) { fmt.Println("type error:", err) },
}
info := &types.Info{Defs: map[*ast.Ident]types.Object{}}
conf.Check("shop", fset, []*ast.File{f}, info)
ast.Inspect(f, func(n ast.Node) bool { // in source order
if id, ok := n.(*ast.Ident); ok {
if v, ok := info.Defs[id].(*types.Var); ok {
fmt.Printf("%v: %s is %s\n", fset.Position(id.Pos()), id.Name, v.Type())
}
}
return true
})
}
Commands:
$ go run ./check bill.go
Output:
$ go run ./check bill.go
type error: bill.go:6:14: invalid operation: qty + rate (mismatched types int and float64)
bill.go:3:11: qty is int
bill.go:3:20: rate is float64
bill.go:4:5: total is float64
bill.go:5:5: tax is float64
bill.go:6:5: items is invalid type
types.Configholds the settings: the importer (importer.Default()loads the types of imported packages from the installed toolchain) and anErrorcallback, so checking continues after the first error.types.Infocollects what the checker learned:Defs(identifier → the object it declares),Uses,Types(expression → type and value),Selections,Scopes...- A variable whose initial expression is wrong gets the type
invalid type.
Your own analyzer with go/analysis
Static analysis means checking code without running it. A checker (an analysis that reports mistakes) is like a building inspector: go vet is the city's standard inspection, and your own analyzer enforces your society's own rules. Raju's team rule: never store money in a float64 (in binary floating point, 0.1 + 0.2 is not exactly 0.3; use integer paise).
go/analysis (in x/tools) is the framework go vet's checks are written in:
go.mod:
module shop
go 1.24
require golang.org/x/tools v0.42.0
order.go:
package shop
type Order struct {
Qty int
Price float64 // rupees in a float: 0.1 + 0.2 != 0.3
}
func Total(o Order) float64 {
total := float64(o.Qty) * o.Price
return total
}
moneycheck/main.go:
package main // our own checker, built on go/analysis
import (
"go/ast"
"go/types"
"strings"
"golang.org/x/tools/go/analysis"
"golang.org/x/tools/go/analysis/singlechecker"
)
var Analyzer = &analysis.Analyzer{
Name: "moneycheck",
Doc: "reports money stored in a float64",
Run: run,
}
func run(pass *analysis.Pass) (any, error) {
for _, f := range pass.Files {
ast.Inspect(f, func(n ast.Node) bool { // every node, in source order
id, ok := n.(*ast.Ident)
if !ok {
return true
}
name := strings.ToLower(id.Name)
v, isVar := pass.TypesInfo.Defs[id].(*types.Var) // a declared variable or field?
if isVar && v.Type() == types.Typ[types.Float64] &&
(strings.Contains(name, "price") || strings.Contains(name, "total")) {
pass.Reportf(id.Pos(), "%s is money in a float64: use int paise", id.Name)
}
return true
})
}
return nil, nil
}
func main() { singlechecker.Main(Analyzer) }
Commands:
$ go vet ./...
$ go run ./moneycheck ./...
Output (go vet prints nothing; our checker's diagnostics go to the error stream):
$ go vet ./...
$ go run ./moneycheck ./...
order.go:5:5: Price is money in a float64: use int paise
order.go:9:5: total is money in a float64: use int paise
exit status 3
| Part | What it is |
|---|---|
analysis.Analyzer |
describes the check: Name, Doc, Run, optional Requires, Flags, FactTypes |
*analysis.Pass |
one package handed to Run: Files (parsed ASTs), TypesInfo, Pkg, Fset, ResultOf |
pass.Reportf(pos, format, ...) |
reports a diagnostic: a message tied to a position |
| driver | the program that runs analyzers: singlechecker (one), multichecker (many), go vet -vettool=$(which mytool), gopls |
exit status 3 |
singlechecker exits with 3 when it found diagnostics, so CI marks the step red |
analysistest |
tests an analyzer on testdata/src/... files whose // want "regexp" comments list the expected diagnostics |
go vet's own checks (printf, copylocks, nilness, shadow, ...) live in golang.org/x/tools/go/analysis/passes and are analyzers just like ours.
gopls, the language server
Your phone keyboard suggests the next word and underlines spelling mistakes in every app. For Go code, that helper is gopls ("Go please"), the official Go language server: a program that gives editors language features over the Language Server Protocol (LSP), a standard set of messages between an editor and a language tool. One gopls works in VS Code, Vim/Neovim, Emacs, Helix, Sublime Text, Zed and others.
editor ──LSP: "completion at main.go:12:8?"──► gopls (go/parser, go/types, analyzers)
editor ◄──────────── ["Println", "Printf", ...] ─┘
gopls offers completion, go to definition, find references, rename, hover docs, code actions, and live diagnostics, including the go vet analyzers. Install: go install golang.org/x/tools/gopls@latest (VS Code's Go extension does it for you). The gopls command line exists but is experimental and "primarily a debugging aid". gopls wasn't built in this run (recent gopls releases pull in many more modules and v0.21 needs Go 1.25), so the video shows it as a concept.
Compiler directives
At a chai stall, "less sugar" written on the order slip is an instruction for the cook, not part of the chai. A compiler directive is a comment //go:name (no space) that gives an instruction to the Go toolchain; other tools skip it like any comment.
//go:embed and //go:noinline
welcome.txt:
Welcome to Raju's Chai Stall!
main.go:
package main
import (
_ "embed"
"fmt"
)
//go:embed welcome.txt
var welcome string // filled from welcome.txt at build time
func addTax(paise int) int { return paise + paise/20 }
//go:noinline
func addTaxSlow(paise int) int { return paise + paise/20 }
func main() {
fmt.Print(welcome)
fmt.Println(addTax(2000), addTaxSlow(2000))
}
remove/main.go:
package main // deletes a file: the binary must not need it any more
import "os"
func main() { os.Remove(os.Args[1]) }
Commands:
$ go build -gcflags=-m -o shop .
$ go run ./remove welcome.txt
$ ./shop
Output:
$ go build -gcflags=-m -o shop .
$ go run ./remove welcome.txt
$ ./shop
Welcome to Raju's Chai Stall!
2100 2100
Compiler notes printed by -gcflags=-m (error stream):
# shop
./main.go:11:6: can inline addTax
./main.go:17:14: inlining call to fmt.Print
./main.go:18:23: inlining call to addTax
./main.go:18:16: inlining call to fmt.Println
./main.go:17:14: ... argument does not escape
./main.go:17:15: welcome escapes to heap
./main.go:18:16: ... argument does not escape
./main.go:18:23: ~r0 escapes to heap
./main.go:18:41: addTaxSlow(2000) escapes to heap
//go:embed welcome.txtfillswelcomeat compile time. The file was deleted before./shopran, and the text still printed: it is inside the binary. You needimport _ "embed"forstring/[]byte, orimport "embed"forembed.FS(whole folders).-gcflags=-masks the compiler to print its optimisation decisions (episode 55): inlining and escape analysis.- Inlining means copying a small function's body into its caller so there is no call at all:
can inline addTaxandinlining call to addTax. There is no such line foraddTaxSlow, because//go:noinlineforbids it. Its docs say it is "typically only needed for special runtime functions or when debugging the compiler".
Embedding a file that doesn't exist fails at compile time:
$ go build .
main.go:8:12: pattern menu.txt: no matching files found
//go:nosplit
Almost every Go function starts with a small stack check: if the goroutine's stack is too small for the function, the runtime grows it first (goroutine stacks start small and grow, episode 10). //go:nosplit removes that check:
main.go:
package main
import "fmt"
//go:nosplit
func sum(n int) int {
var buf [200]int // 1600 bytes on the stack, with no stack check
for i := range buf {
buf[i] = i * n
}
return buf[n%200] + double(n)
}
//go:noinline
func double(n int) int { return 2 * n }
func main() { fmt.Println(sum(3)) }
Commands:
$ go build .
Output (error stream):
# shop
main.sum: nosplit stack over 792 byte limit
main.sum<1>
grows 1640 bytes, calls main.double<1>
848 bytes over limit
grows 1640 bytes, calls runtime.panicIndex<1>
grows 8 bytes, calls runtime.goPanicIndex<1>
grows 8 bytes, calls runtime.morestack<0>
864 bytes over limit
--- stdout
$ go build .
--- stderr
main.go:8:12: pattern menu.txt: no matching files found
Without the check, a nosplit function (and the nosplit chain below it) must fit in a small fixed stack budget, 792 bytes here, so the linker refuses the 1640-byte frame. The compiler docs say nosplit is for low-level runtime code "invoked at times when it is unsafe for the calling goroutine to be preempted" (paused by the scheduler). In application code: never.
Directives on one page
| Directive | What it does | Where you meet it |
|---|---|---|
//go:build expr |
include the file only when the expression is true | per-OS code, editions (episode 73) |
//go:embed pattern |
put files into a string, []byte or embed.FS at compile time |
web assets, SQL migrations, templates |
//go:generate cmd args |
a command for go generate (never run by go build) |
stringer, mocks, protobuf |
//go:noinline |
never inline this function | benchmarks, debugging, runtime |
//go:nosplit |
no stack overflow check | the runtime only |
//go:linkname |
reach an unexported symbol in another package (restricted) | episode 75 |
Code generation and tooling in one page
source text ─go/scanner─► tokens ─go/parser─► *ast.File ─go/types─► types + errors ─go/analysis─► diagnostics
users: compiler, gofmt, go vet, stringer, gopls, your tools
data / consts ─generator (stringer, text/template + go/format)─► x_gen.go (// Code generated ... DO NOT EDIT.)
- Generators write the boring, predictable code;
go generateruns them only when you ask; generated files are committed and checked in CI. - go/token + go/scanner give tokens with positions, go/parser + go/ast give the syntax tree, go/types gives meaning.
- go/analysis turns your team's rules into a tool that runs in CI and in the editor.
- Directives:
//go:build,//go:embed,//go:generateevery day;//go:noinlinerarely;//go:nosplitnever in app code.
Mini project: Raju's tooling
- Generate
String()for three enums with one stringer command, and add a CI step that fails when generated files are stale. - A generator:
prices.csv→prices_gen.gowithtext/template+go/format. funclist: with go/parser + go/ast, print every exported function and method withfile:line:col.moneycheckv2: also flag float64 parameters and named results, more money words, and tests withanalysistest.- Embed a
site/folder withembed.FSand serve it.
Solution
1. Three enums, one directive (real run):
go.mod:
module shop
go 1.24
require golang.org/x/tools v0.42.0
enums.go:
package main
//go:generate go run golang.org/x/tools/cmd/stringer -type=Status,Payment,Size
type Status int
const (
Placed Status = iota
Packed
Shipped
)
type Payment int
const (
Cash Payment = iota + 1
UPI
Card
)
type Size int
const (
Small Size = iota
Medium
Large
)
main.go:
package main
import "fmt"
func main() { fmt.Println(Shipped, UPI, Large, Payment(0)) }
show/main.go:
package main
func main() {}
Commands:
$ go generate ./...
$ go run .
$ go generate ./...
$ go run .
Shipped UPI Large Payment(0)
CI step (GitHub Actions):
- run: go generate ./...
- run: git diff --exit-code # fails if go generate changed any file
2. prices.csv generator. It is the episode's gen/main.go with the input renamed: //go:generate go run ./gen prices.csv prices_gen.go, and the template's map named Prices.
3. funclist (real run):
shop.go:
package shop
func Total(qty, paise int) int { return qty * paise }
func discount(p int) int { return p / 10 }
type Cart struct{}
func (c *Cart) Add(item string) {}
funclist/main.go:
package main
import (
"fmt"
"go/ast"
"go/parser"
"go/token"
"os"
)
func main() {
fset := token.NewFileSet()
for _, name := range os.Args[1:] {
f, err := parser.ParseFile(fset, name, nil, 0)
if err != nil {
fmt.Println(err)
continue
}
for _, d := range f.Decls {
fn, ok := d.(*ast.FuncDecl)
if !ok || !fn.Name.IsExported() {
continue
}
recv := ""
if fn.Recv != nil {
recv = "method "
}
fmt.Printf("%v: %s%s\n", fset.Position(fn.Pos()), recv, fn.Name)
}
}
}
Commands:
$ go run ./funclist shop.go
$ go run ./funclist shop.go
shop.go:3:1: Total
shop.go:9:1: method Add
fn.Name.IsExported() is true for names starting with a capital letter (episode 19), and fn.Recv is non-nil for methods.
4. moneycheck v2 with tests (real run). TypesInfo.Defs contains parameters and named results too, so the same loop catches them:
go.mod:
module shop
go 1.24
require golang.org/x/tools v0.42.0
shop/order.go:
package shop
type Order struct {
Price float64
}
func Discount(price float64) (total float64) { return price * 0.9 }
moneycheck/moneycheck.go:
package moneycheck
import (
"go/ast"
"go/types"
"strings"
"golang.org/x/tools/go/analysis"
)
var Analyzer = &analysis.Analyzer{
Name: "moneycheck",
Doc: "reports money stored in a float64",
Run: run,
}
func isMoney(name string) bool {
n := strings.ToLower(name)
for _, w := range []string{"price", "total", "amount", "paise", "rupees"} {
if strings.Contains(n, w) {
return true
}
}
return false
}
func run(pass *analysis.Pass) (any, error) {
for _, f := range pass.Files {
ast.Inspect(f, func(n ast.Node) bool {
id, ok := n.(*ast.Ident)
if !ok {
return true
}
// Defs covers vars, struct fields, parameters and named results.
if v, ok := pass.TypesInfo.Defs[id].(*types.Var); ok &&
types.Identical(v.Type(), types.Typ[types.Float64]) && isMoney(id.Name) {
pass.Reportf(id.Pos(), "%s is money in a float64: use int paise", id.Name)
}
return true
})
}
return nil, nil
}
moneycheck/moneycheck_test.go:
package moneycheck_test
import (
"testing"
"golang.org/x/tools/go/analysis/analysistest"
"shop/moneycheck"
)
func TestMoneycheck(t *testing.T) {
analysistest.Run(t, analysistest.TestData(), moneycheck.Analyzer, "a")
}
moneycheck/testdata/src/a/a.go:
package a
type Item struct {
Price float64 // want "Price is money in a float64: use int paise"
Qty int
}
func Pay(amount float64) {} // want "amount is money in a float64: use int paise"
func Ratio(x float64) float64 { return x }
cmd/moneycheck/main.go:
package main
import (
"golang.org/x/tools/go/analysis/singlechecker"
"shop/moneycheck"
)
func main() { singlechecker.Main(moneycheck.Analyzer) }
Commands:
$ go test ./moneycheck
$ go run ./cmd/moneycheck ./shop
$ go test ./moneycheck
ok shop/moneycheck 0.152s
$ go run ./cmd/moneycheck ./shop
shop/order.go:4:5: Price is money in a float64: use int paise
shop/order.go:7:15: price is money in a float64: use int paise
shop/order.go:7:31: total is money in a float64: use int paise
exit status 3
The test passes because testdata/src/a/a.go reports exactly the two diagnostics its // want comments expect, and nothing for Ratio's x.
5. Serving an embedded folder (real run):
site/index.html:
<h1>Raju's Chai Stall</h1>
site/menu.html:
<p>masala chai: Rs 15</p>
main.go:
package main
import (
"embed"
"fmt"
"io"
"io/fs"
"net/http"
"net/http/httptest"
)
//go:embed site
var siteFiles embed.FS
func main() {
site, _ := fs.Sub(siteFiles, "site") // serve site/ as the web root
h := http.FileServerFS(site)
for _, path := range []string{"/", "/menu.html", "/missing.html"} {
rec := httptest.NewRecorder()
h.ServeHTTP(rec, httptest.NewRequest("GET", path, nil))
body, _ := io.ReadAll(rec.Body)
fmt.Printf("%s -> %d %s", path, rec.Code, body)
}
}
Commands:
$ go run .
$ go run .
/ -> 200 <h1>Raju's Chai Stall</h1>
/menu.html -> 200 <p>masala chai: Rs 15</p>
/missing.html -> 404 404 page not found
fs.Sub makes site/ the root, and http.FileServerFS (Go 1.22+) serves an fs.FS. In a real server use http.ListenAndServe(":8080", h); httptest lets this example run and exit.
Common mistakes (and the real messages)
| Mistake | Real message / symptom | Why | Fix |
|---|---|---|---|
String() written by hand with an array |
%!v(PANIC=String method: runtime error: index out of range [4] with length 4), or a wrong name |
the names and the constants are two lists out of sync | stringer via go generate |
constants changed, go generate not run |
invalid argument: index 1 out of bounds [0:1] |
the generated compile check sees shifted values | go generate ./..., commit |
editing status_string.go by hand |
the edit disappears next time | the file is regenerated | change the input (the consts) instead |
//go:embed menu.txt with no such file |
pattern menu.txt: no matching files found |
files are embedded at compile time | put the file next to the .go file |
// go:generate or // go:embed (a space) |
nothing happens; the variable stays empty | it's an ordinary comment | //go:generate |
expecting go build to run generators |
stale code | go generate "must be run explicitly" | run it, commit the output, check in CI |
//go:nosplit in app code |
main.sum: nosplit stack over 792 byte limit |
no stack check, tiny budget | remove it |
reading info.Defs with range and printing |
output order changes between runs | map iteration order is random | walk the AST (ast.Inspect) for source order |
Practice
- Add
-trimprefix=Statusto the stringer command for a typeStatuswith constantsStatusPlaced,StatusPacked. What doesfmt.Println(StatusPacked)print? - Write a directive that prints the file and line it is on when you run
go generate. - Use go/parser and
ast.Inspectto count theifstatements in a file. - With go/types, print the type of every expression (not just variables) in
bill.go. - Why must generated files be committed, when they can always be regenerated?
- What do you expect
go build -gcflags=-mto print for a function with aforloop of 1,000 lines? Why?
Solutions
1. Packed. -trimprefix removes the prefix from the printed names (stringer -type=Status -trimprefix=Status).
2. //go:generate echo $GOFILE:$GOLINE — go generate replaces $GOFILE and $GOLINE before running echo.
3.
n := 0
ast.Inspect(f, func(x ast.Node) bool {
if _, ok := x.(*ast.IfStmt); ok {
n++
}
return true
})
fmt.Println("if statements:", n)
4. Add Types: map[ast.Expr]types.TypeAndValue{} to types.Info, then walk the AST and for every ast.Expr with an entry print info.Types[e].Type. (Constants also have .Value, for example 20 in total / 20.)
5. So that go build and go install work for everyone, including people who import your package, without installing or running the generator. Generators are a development step, not a build step.
6. No can inline line for it: the compiler only inlines small functions (its inlining budget), and large bodies or certain constructs exceed it.
Quick quiz
package main
// go:generate go run golang.org/x/tools/cmd/stringer -type=Size
type Size int
const (
Small Size = iota
Large
)
// $ go generate ./... then fmt.Println(Large)
What is printed?
- A.
Large - B.
1 - C. a compile error
- D. go generate fails
Answer
B. There's a space in // go:generate, so it is an ordinary comment. go generate finds no directive, no String() is written, and fmt prints the number 1.
Interview questions
- What is
go generateand when does it run? It runs commands named in//go:generatecomments, usually generators that write Go code. It never runs duringgo buildorgo test; developers or CI run it explicitly, and the output is committed. - How does stringer protect you from stale generated code? The generated file contains
func _() { var x [1]struct{}; _ = x[Placed-0] ... }; if a constant's value changes, an index becomes out of bounds and compilation fails. - Code generation vs generics vs reflection? Generics (episode 30s) give type-safe reusable code at compile time; reflection inspects values at run time and is slower and less safe; code generation writes ordinary, fast, readable code before compiling, at the cost of a generation step. Use generics first, generation when the code depends on data or on declarations (enums, protobuf, mocks).
- What do go/token, go/parser, go/ast and go/types do? Tokens and positions; parse source into a syntax tree; the node types of that tree; type-check the tree and record the type of every name and expression.
- How would you enforce a team rule like "no float64 for money"? Write a go/analysis Analyzer that uses
pass.TypesInfoto find float64 variables with money names, test it with analysistest, run it with singlechecker or multichecker in CI, and optionally in gopls. - What is gopls? The official Go language server; editors talk to it with LSP for completion, navigation, refactoring and diagnostics.
- What does
//go:noinlinedo, and why would you use it? It stops the compiler inlining a function; used in runtime code, compiler debugging, and to keep a benchmark's function call from being optimised away. - Why should application code not use
//go:nosplit? It removes the stack overflow check; the function must fit in a tiny stack budget and is meant for runtime code that must not be preempted. The linker rejects frames over the limit. - What does
//go:embedgive you over reading files at run time? A single self-contained binary: no missing files in production, works inscratchimages, read-onlyembed.FS.
Glossary
| Term | Meaning | Example |
|---|---|---|
| Enum (enumeration) | a fixed set of named values; in Go, a defined int type with constants | type Status int + Placed, Packed |
iota |
counts 0, 1, 2... inside a const block | Placed Status = iota |
fmt.Stringer |
the interface with String() string; fmt calls it when printing |
fmt.Println(Shipped) → Shipped |
| Code generation | a program writes source code for you | stringer writes status_string.go |
| Generator | the program that writes the code | stringer, go run ./gen |
| Directive | a //go:name comment that instructs a Go tool |
//go:generate ... |
go generate |
runs the commands in //go:generate directives |
go generate ./... |
//go:generate |
the directive go generate looks for | //go:generate go run ./gen menu.txt menu_gen.go |
./... |
this package and all packages below it | go generate ./... |
| stringer | x/tools generator for String() methods |
stringer -type=Status |
| Generated file header | // Code generated ... DO NOT EDIT. marks generated code |
first line of status_string.go |
| Stale generated file | generated code older than its input | index 1 out of bounds [0:1] |
| Template | text with holes filled from data | {{.Name}} |
text/template |
Go's package for data-driven text templates | template.Must(template.New("menu").Parse(...)) |
| Action | anything inside {{ }} |
{{range .Items}} |
Dot (.) |
the current data in a template | {{.Paise}} |
go/format |
formats Go source like gofmt | format.Source(buf.Bytes()) |
| gofmt | Go's standard code formatter | aligned map values |
| Token | the smallest meaningful piece of code | total, :=, 1500 |
| Scanner / lexer | splits text into tokens | go/scanner |
go/token |
token kinds and positions | token.IDENT, token.NewFileSet() |
IDENT |
token kind for identifiers (names) | total |
| FileSet | remembers files so positions become file:line:col | fset.Position(pos) |
| Position | where a token or node is | status.go:6:5 |
| Parser / parsing | turns tokens into a syntax tree | parser.ParseFile |
| AST (abstract syntax tree) | code as a tree of nodes | *ast.File → *ast.GenDecl |
| Node | one piece of the tree | *ast.FuncDecl |
go/ast |
the AST node types and helpers | ast.Inspect, ast.Print |
ast.Inspect |
visits every node, depth first | print every *ast.ValueSpec |
| Type checker | works out types and reports type errors | go/types |
go/types |
Go's type checker as a library | conf.Check(...) |
| Importer | loads the types of imported packages | importer.Default() |
types.Info |
what the checker learned | info.Defs[id] |
invalid type |
the type given to something whose expression had an error | items := qty + rate |
| Static analysis | checking code without running it | go vet, our moneycheck |
| Checker | an analysis that reports mistakes | the printf check |
| Analyzer | a go/analysis check: Name, Doc, Run | var Analyzer = &analysis.Analyzer{...} |
| Pass | one package handed to an analyzer's Run | pass.Files, pass.TypesInfo |
| Diagnostic | a reported problem tied to a position | order.go:5:5: Price is money in a float64 |
pass.Reportf |
reports a diagnostic | pass.Reportf(id.Pos(), "...") |
| Driver | a program that runs analyzers | singlechecker, go vet |
| singlechecker | a ready-made main for one analyzer | singlechecker.Main(Analyzer) |
| multichecker | a ready-made main for several analyzers | multichecker.Main(a, b) |
| analysistest | testing helper for analyzers using // want comments |
analysistest.Run(t, dir, A, "a") |
| go vet | Go's standard static checks | go vet ./... |
| gopls | the official Go language server ("Go please") | completion in VS Code |
| Language server | a program that gives editors language features | gopls |
| LSP (Language Server Protocol) | the standard messages between editors and language servers | "definition at main.go:12:8" |
| Compiler directive | a //go: comment that changes how code is built |
//go:noinline |
//go:build |
build constraint: include the file when true | //go:build linux |
//go:embed |
put files into the binary at compile time | //go:embed welcome.txt |
embed.FS |
a read-only file system of embedded files | //go:embed site |
| Inlining | copying a small function's body into its caller | inlining call to addTax |
-gcflags=-m |
ask the compiler to print its optimisation decisions | go build -gcflags=-m . |
//go:noinline |
never inline this function | addTaxSlow |
| Stack check | the check at a function's start that grows the stack if needed | in almost every function |
//go:nosplit |
omit the stack check (runtime only) | nosplit stack over 792 byte limit |
| Preempt | the scheduler pausing a goroutine to run another | why the runtime uses nosplit |
Summary
- A hand-written
String()went stale when a status was added: a wrong name and a panic. The fix: code generation.stringer, run bygo generatefrom a//go:generatedirective, writesString()from the constants, and its compile check catches stale files. go generatenever runs duringgo build; run it when inputs change, commit the output, and check it in CI.- Your own generators: data +
text/template+go/format. - Reading Go code: go/scanner and go/token (tokens and positions), go/parser and go/ast (syntax trees), go/types (types and type errors).
- go/analysis turns a team rule into a checker (
Analyzer,Pass,Reportf, singlechecker); gopls brings the same machinery into every LSP editor. - Directives:
//go:build,//go:embed,//go:generate,//go:noinline(benchmarks, debugging),//go:nosplit(runtime only). - Next episode: Runtime internals tour — goroutine stacks, interface internals, map and channel internals, defer, the compiler pipeline and assembly output.