Breakpoints and Stepping

## Why an optimised Go binary is hostile to a debugger A debugger works from a map the compiler leaves behind: *this machine instruction belongs to that source line*, and *this variable lives at that address, in that register, over this instruction range*. An optimising compiler is allowed to change the program as long as the observable behaviour is the same — and "observable" does not include what a debugger sees. Three optimisations account for nearly every confusing session. **Register allocation and dead-store elimination.** A local variable does not need a stack slot. If the compiler can keep it in a CPU register for its whole lifetime, or prove that an assignment is never read afterwards, there is no memory location to point at when you stop. Asked for the value, the debugger honestly answers that it was optimised out. Nothing is broken; there is simply nothing to read at that instruction. **Inlining.** A small function called from one place is copied into the body of its caller and the call instruction disappears. The frame you wanted to step into is not merely hidden — it never exists at runtime. "Step into" walks straight past it, and the stack you see is shallower than the source suggests. **Instruction scheduling.** Instructions from several statements are interleaved, so consecutive "next" commands land on line 42, then 38, then 45. The line table is not wrong; the machine code genuinely belongs to those lines in that order. ## The build that fixes it ``` go build -gcflags="all=-N -l" -o fixtool.debug ./cmd/fixtool ``` `-gcflags` forwards flags to the compiler. The two switches do different jobs, and confusing them is a standard interview tell: - `-N` **disables optimisations.** Every local gets a stack slot with a stable address; assignments happen where you wrote them; the line table is statement-for-statement. - `-l` **disables inlining.** Every call in the source is a call at runtime, so the frames you expect are on the stack and stepping into a helper works. ## The `all=` prefix `-gcflags` accepts an optional **package pattern** before the flags. Without one, the flags apply only to the packages *named on the command line*. `go build -gcflags="-N -l" ./cmd/fixtool` therefore produces one unoptimised package linked against a fully optimised standard library and fully optimised dependencies. That is usually enough to make the session look fixed — until you step into a decoder in `encoding/json` to watch a struct field get populated, and every value there reads as optimised out again. `all=` is the pattern that means every package in the build, including the standard library. Keep the quotes: unquoted, the shell hands `-l` to `go build` itself, which has no such flag and errors out. ## What the debug build costs A `-N -l` binary is slower — sometimes dramatically, because hot small functions that would have been inlined now pay call overhead and everything spills to memory — and it is larger. It also occupies a different entry in the build cache, so the first such build recompiles the world. Two consequences follow: - **Never measure performance on it.** Timings and allocation counts from a `-N -l` build describe a program nobody runs. - **Never ship it.** It is a local artefact; give it a distinct output name (`-o fixtool.debug`) so it cannot be confused with the release binary. ## Test binaries and stopping without a breakpoint The same flags apply to a test binary: `go test -c -gcflags="all=-N -l"` compiles a debuggable test executable instead of running the tests. If a spot is awkward to reach by hand — a rare branch, a callback deep inside a decode — `runtime.Breakpoint()` compiles to a breakpoint trap. Under a debugger the process stops there; with no debugger attached the process dies of SIGTRAP, so it is strictly a temporary edit, never something you commit. ## Symptom to cause | What you see | What caused it | |---|---| | A local reads as optimized out | It lived in a register or was eliminated; rebuild with `-N` | | Step into skips a function | The callee was inlined; rebuild with `-l` | | The cursor jumps backwards between lines | Instruction scheduling; `-N` restores statement order | | Your own package steps fine, dependencies do not | The `all=` prefix was missing | | A breakpoint on a function name will not resolve | Debug information was stripped at link time, a separate problem from optimisation |