midenc-execution-trace

greenhat 的头像作者 greenhat

使用于在Miden编译器(`midenc`/`cargo miden`)开发、调试失败的测试或实现编译器更改时,需要Miden VM MASM执行跟踪以理解每条指令后的栈状态。涵盖`MIDENC_TRACE=executor=trace`(通常与`cargo make test -- --no-capture ...`一起使用)。

📖 中文导读:使用于在Miden编译器(`midenc`/`cargo miden`)开发、调试失败的测试或实现编译器更改时,需要Miden VM MASM执行跟踪以理解每条指令后的栈状态。涵盖`MIDENC_TRACE=executor=trace`(通常与`cargo make test -- --no-capture ...`一起使用)。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: midenc-execution-trace description: | Use when working on the Miden compiler (midenc / cargo miden), debugging failing tests or implementing compiler changes, and you need a Miden VM MASM execution trace to understand the stack state after each instruction. Covers MIDENC_TRACE=executor=trace (typically with cargo make test -- --no-capture ...).

MIDENC Trace (MASM execution trace)

Quick start

  • Run a single Rust test with MASM execution tracing enabled:
    • MIDENC_TRACE=executor=trace cargo make test --no-capture <test_name_or_filter>
  • If you only care about traces on failures (and want faster parallel execution), omit --no-capture:
    • MIDENC_TRACE=executor=trace cargo make test <test_name_or_filter>
  • If you want parallel execution but still want output on passing tests, prefer --success-output:
    • MIDENC_TRACE=executor=trace cargo make test --success-output immediate <test_name_or_filter>

What MIDENC_TRACE=executor=trace gives you

  • A step-by-step trace of MASM execution from the VM executor.
  • For each executed instruction/op, it prints the current stack state (practically: the quickest way to answer “what was on the stack right after this instruction?”).
  1. Reproduce the issue on the smallest possible test (or add a focused test).
  2. Run with live output so you can see the trace stream as the test executes:
    • MIDENC_TRACE=executor=trace cargo make test --no-capture <test_name_or_filter>
  3. Compare the trace against the expected stack discipline for the procedure(s) you’re debugging:
    • When you see a mismatch, jump to the corresponding emitted MASM (pair with the emit skill if you also need MIDENC_EMIT=masm=...).

Practical tips

  • Prefer a single test when tracing: executor=trace is extremely verbose and slows runs down.
  • If you’re running via cargo nextest directly, the equivalent “live output” flag is --no-capture:
    • MIDENC_TRACE=executor=trace cargo nextest run --no-capture <filter>