AgentSkillsCN

midenc-execution-trace

在使用 Miden 编译器（`midenc` / `cargo miden`）、调试失败的测试或实现编译器变更时，若需要通过 Miden VM 的 MASM 执行轨迹来了解每条指令执行后的栈状态，可使用此功能。涵盖 `MIDENC_TRACE=executor=trace` 设置（通常配合 `cargo make test -- --no-capture ...` 使用）。

SKILL.md
--- frontmatter
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?”).

Recommended workflow for debugging compiler changes

  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>