AgentSkillsCN

emit

在使用 Miden 编译器（`cargo miden`、`cargo-miden`）及其集成测试套件、调试编译器问题或失败测试、或实施编译器变更时，若需检查中间产物，可使用此功能。涵盖 `MIDENC_EMIT`（相当于 `--emit` 的环境变量设置），用于输出 WAT/HIR/MASM（及相关输出），以及 `MIDENC_EMIT_MACRO_EXPAND`，用于通过 `cargo expand` 转储宏展开后的 Rust 代码，以供集成测试用例使用。

SKILL.md
--- frontmatter
name: emit
description: |
  Use when working on the Miden compiler (`cargo miden`, `cargo-miden`) and its integration test suite, debugging compiler issues or failing tests, or implementing compiler changes and you need to inspect intermediate artifacts. Covers `MIDENC_EMIT` (the environment-variable equivalent of `--emit`) for emitting WAT/HIR/MASM (and related outputs), plus `MIDENC_EMIT_MACRO_EXPAND` for dumping macro-expanded Rust via `cargo expand` for integration-test fixtures.

MIDENC Emit (Intermediate Artifacts) + Macro Expand

Quick start

  • •Emit all intermediate IRs (WAT + HIR + MASM) into a ir_dump directory:
    • •MIDENC_EMIT=ir=ir_dump
  • •Emit HIR to stdout:
    • •MIDENC_EMIT=hir=-
  • •Emit MASM to a specific file:
    • •MIDENC_EMIT=masm=out.masm
  • •Dump macro-expanded Rust for integration tests into a ir_dump directory:
    • •MIDENC_EMIT_MACRO_EXPAND=ir_dump cargo make test

MIDENC_EMIT (same syntax as --emit)

Syntax

  • •Set MIDENC_EMIT to a comma-delimited list of KIND[=PATH] specs, e.g.:
    • •MIDENC_EMIT=wat,hir,masm
    • •MIDENC_EMIT=ir=ir_dump

Useful kinds for pipeline debugging

  • •wat: WebAssembly text format (.wat)
  • •hir: Miden High-level IR (.hir)
  • •masm: Miden Assembly text (.masm)
  • •Shorthands:
    • •ir: emits wat,hir,masm together (WAT + HIR + MASM)

PATH rules (practical)

  • •Omit =PATH to use the CWD.
  • •Use =DIR to emit DIR/<stem>.<ext> for each requested output type:
    • •Example: MIDENC_EMIT=ir=target/emit writes target/emit/<stem>.wat, target/emit/<stem>.hir, target/emit/<stem>.masm.
  • •Use =- to write textual outputs to stdout (e.g. hir=-, wat=-, masm=-).
    • •Note: ir=- is invalid; ir expects a directory (or no path).
  • •Use =FILE to write a single output to a specific file path:
    • •Example: MIDENC_EMIT=hir=my_dump.hir.

MIDENC_EMIT_MACRO_EXPAND (integration tests only)

When you need to see the actual Rust code after macros have expanded (helpful when debugging fixtures that use proc-macros, attribute macros, derives, or cfg-gated code), enable macro expansion dumps.

Behavior

  • •If MIDENC_EMIT_MACRO_EXPAND is unset: nothing happens.
  • •If set to an empty value or 1: writes *.expanded.rs files into the current working directory.
  • •If set to any other non-empty value: treats it as an output directory (created if missing).
  • •The integration test harness runs cargo expand and writes one file per fixture/test:
    • •<test_name>.expanded.rs

Debugging workflow (recommended)

  1. •Reproduce on a single test case if possible.
  2. •Emit intermediate artifacts to a dedicated folder:
    • •MIDENC_EMIT=ir=target/emit/<case> ...
  3. •If the failing test involves Rust fixtures/macros:
    • •MIDENC_EMIT_MACRO_EXPAND=target/expand/<case> ...