Optimizer Debug

Optimizer pass debugging

The optimize.rs and wir_optimize.rs pipelines are big — many passes, each rewriting the IR in place. When a pass is wrong, the symptom usually shows up two passes later as "the WIR validates but produces the wrong behaviour" or as "the codegen finds an invalid Wasm module" deep in the final emitter. The debug hooks below let you diff the IR around any single pass without sprinkling eprintln! through pass internals.

All three are env-var-driven so they work uniformly across wado compile, wado test, wado run, and Kiln invocations from package-gale.

Quick recipes

Which pass changed the IR?

WADO_LIST_PASSES=1 cargo run --bin wado --quiet -- compile -O1 file.wado -o scratchpad/out.wasm 2>&1 | grep '\[pass\]'

Prints every pass name in execution order. Lets you correlate the order in source (optimize.rs and wir_optimize.rs) with what actually fires under your -Ox choice.

What does pass X produce?

WADO_DUMP_PASS_AFTER=wir/sroa_multi_value_returns \
  cargo run --bin wado --quiet -- compile -O1 file.wado -o scratchpad/out.wasm 2>scratchpad/after.log

scratchpad/after.log holds the full WIR (or NIR, depending on the pass) right after the named pass, framed by === WIR after <name> === / === end WIR after <name> === (NIR passes use === NIR after <name> ===).

What does pass X consume?

WADO_DUMP_PASS_BEFORE=wir/sroa_multi_value_returns \
  cargo run --bin wado --quiet -- compile -O1 file.wado -o scratchpad/out.wasm 2>scratchpad/before.log

Same framing, before the pass runs. diff the two logs to see exactly what the pass rewrote.

Multiple passes at once

The variables accept a comma-separated list:

WADO_DUMP_PASS_AFTER=nir/inline,wir/sroa_multi_value_returns \
  cargo run --bin wado --quiet -- compile -O1 file.wado -o scratchpad/out.wasm 2>scratchpad/dump.log

Bisect by skipping a pass

WADO_SKIP_PASS=nir/cse cargo run --bin wado --quiet -- compile -O3 file.wado -o scratchpad/out.wasm

Same comma-separated list as WADO_DUMP_PASS_*, with one extra convenience: a @N suffix targets the Nth invocation of a pass within the fixed-point loop (1-based). WADO_SKIP_PASS=nir/cse@2 skips cse only on the second iteration — invaluable for iteration-dependent bugs whose failing test passes on the first iteration and only diverges once the inliner expands an additional function on a later one.

Only standalone run_pass spans are skippable; confirm a name with WADO_LIST_PASSES=1 first. Local rules folded into the peephole session (ref_elim, elide_box_local, match_to_switch, value_copy_elide, array_literal, …) are not individually addressable — target nir/peephole to skip the whole session.

When a pass is the only one whose skipping makes the bug go away that just narrows the participants in the buggy interaction — it does not prove the pass is itself buggy. Pair the skip-bisection result with WADO_DUMP_PASS_AFTER on the same pass to compare its output across the working vs. broken configuration before concluding.

Trace pass-internal decisions

For developer-only messages from inside a pass. The crate denies eprintln!, so use compiler_trace!, which writes to the sink the host installed:

WADO_TRACE=sroa_return cargo run --bin wado --quiet -- compile -O1 file.wado -o scratchpad/out.wasm 2>&1 | grep '\[sroa_return\]'

Output is framed [target] message. Targets are passed verbatim to compiler_trace!(target, ...) calls inside the compiler. Use WADO_TRACE='*' to enable every target at once.

To add a new tracing call inside a pass:

use crate::compiler_trace;
// ...
compiler_trace!("sroa_return", "candidates = {}", candidates.len());
compiler_trace!("sroa_return", "rewriting return at {span:?}");

The cost when the target is disabled is one OnceLock get + a linear scan of the configured target list — fine for any rate that makes sense in a compiler pass.

Workflow for a fixed-point loop that never converges

--log-level debug ends the NIR loop with either "converged after N iteration(s)" or "hit the N-iteration cap without converging", the latter naming the passes still reporting changes. From there:

1. WADO_TRACE=opt_loop lists, per iteration, every pass that reported a change. The tail of that list is the culprit set.
2. WADO_TRACE=const_fold names each function const_fold changed, so a pass that keeps reporting a change points at the body it keeps rewriting. WADO_TRACE=inline_sites names, per round, the callees spliced into each caller: a late round splicing small helpers is a callee that only shrank under the threshold once its own callees were spliced.
3. WADO_DUMP_PASS_BEFORE/_AFTER=<pass> around a late round, diffed, says which of three it is: nothing rewritten at all (the pass reports a change it did not make), a rewrite a later pass deletes (two passes fighting), or real work that tapers (the pass takes one step per round where its own fixed point is one sweep away).

Workflow for output that is far larger than the level below it

-O3 emitting several times -O2's wasm is the inliner, not the loop — check the iteration count first (WADO_TRACE=opt_loop) and stop suspecting convergence once it is small.

1. Sweep --optimize-inline-threshold. A cliff rather than a curve means one callee crossed the budget and is now copied at every call site.
2. WADO_TRACE=inline reports, per round, the unit size and how many candidates the threshold admitted only because the cold discount put them under it — with what those are worth in growth. A handful of callees accounting for most of a round's growth is that pattern.
3. WADO_TRACE=cold_outline says why such a callee was not split: control leaving the region, or a local the call cannot hand over.
4. --optimize-inline-growth <pct> caps unit growth, and --log-level debug then names what the cap turned down, with both of the callee's prices.