How do you make `go build` print the Go compiler's inlining and escape-analysis decisions?

## What the flag is The Go compiler (`cmd/compile`, invoked for you by the `go` command) can narrate two of its optimisation decisions: **which functions it inlined**, and **which values it could not keep on the goroutine's stack** and therefore heap-allocated. The switch that turns this narration on is `-m`. You almost never call the compiler directly, so you hand the flag down through the `go` command: ``` go build -gcflags=-m ./... go test -gcflags=-m -run XXX -bench BenchmarkEncode ``` `-gcflags` takes an optional package pattern: its full form is `-gcflags=[pattern=]flag-list`. Without a pattern, the flags apply only to the packages **named on the command line**; with `all=`, they apply to every package in the build, including the standard library and dependencies. `-gcflags=all=-m` is therefore correct but produces thousands of lines, so most of the time you want the un-prefixed form plus a `grep` for your own file. ## Where the output goes To **stderr**, one line per decision, prefixed with the source position: ``` ./encode.go:22:6: cannot inline (*Encoder).encodeValue: function too complex: cost 214 exceeds budget 80 ./encode.go:38:2: moved to heap: scratch ``` Because it is stderr, a naive `go build -gcflags=-m ./... | grep escape` silently shows you nothing; you need `2>&1 |`. Nothing here is an error: the build succeeds and the resulting binary is byte-for-byte what you would have got without the flag. `-m` only asks the compiler to explain itself. ## The message families worth recognising - `can inline f with cost N as: func(...)` — the compiler decided `f` is a candidate. This says nothing about whether any particular call to it was actually inlined. - `inlining call to f` — a specific call site was replaced by the callee's body. - `cannot inline f: <reason>` — `f` will always be a real call. The reason is on the line: a cost that exceeds the inliner's budget, a `//go:noinline` directive, or a construct the inliner does not handle. - `moved to heap: x` — a local variable whose address is taken and which outlives its frame, so the compiler allocated it. - `x escapes to heap` / `&x escapes to heap` — the same conclusion reported at the point where the value gets away. - `leaking param: p` and `leaking param content: p` — a summary of a *function*, not a call: this parameter (or what it points to) can outlive the call, so callers passing a stack value must heap-allocate it. ## Turning up the verbosity `-m=2` — or the older spelling `-gcflags='-m -m'`, since the flag is repeatable — adds the arithmetic. You get the inlining cost of every candidate, the budget it was measured against, and a chain of reasoning for each escape ("parameter p leaks to result ~r0", "escapes to heap: flow: x = &y"). Levels above 2 exist but are for compiler development, not for tuning a program. ## How this fits an optimisation loop `-m` output is **evidence about the compiler**, not evidence about your program's behaviour. The useful loop is: measure first (a benchmark with `-benchmem` gives you `B/op` and `allocs/op`), then use `-m` to explain the number you measured, change one thing, and re-measure. Reading `-m` output cold, without a measurement, produces a long list of escapes that are all completely harmless because they happen once at start-up. A value that escapes on a path executed a million times a second is worth an hour of work; the same line in a config parser is worth none. The two families are also linked, which is why one flag prints both. Inlining a call lets the compiler analyse the callee's body *in the caller's frame*, so it can often prove a value never gets away — an inlining failure and an unexpected heap allocation two lines apart are frequently the same fact reported twice. ## Practical notes - The flags are part of the build cache key, so switching them on forces the affected packages to be recompiled; you do not need `-a`. - The positions are file:line:column of the *declaration or expression*, which is what lets you jump straight to the code. - `go vet` and the race detector tell you about correctness; `-m` tells you about code generation. They are unrelated tools that happen to be reached through the same `go` command.