emit

greenhat's avatarfrom greenhat

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.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 4, 2026
[Debugging]

When & Why to Use This Skill

This Claude skill provides advanced debugging capabilities for the Miden compiler (cargo-miden) by enabling the inspection of intermediate artifacts and macro-expanded Rust code. It allows developers to emit WAT, HIR, and MASM outputs directly to files or stdout, facilitating deep analysis of compiler behavior, IR transformations, and integration test failures.

Use Cases

  • Case 1: Debugging compiler logic by emitting and inspecting intermediate representations (WAT, HIR, MASM) to identify exactly where a transformation or optimization fails.
  • Case 2: Troubleshooting complex Rust macros in integration tests by dumping expanded source code using the macro-expand feature to verify proc-macro outputs.
  • Case 3: Analyzing integration test failures by routing intermediate IR outputs to a dedicated directory for side-by-side comparison with expected results.
  • Case 4: Rapidly verifying Miden Assembly (MASM) generation by piping specific IR outputs directly to stdout during the development of new compiler features.
nameemit
description|

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
  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> ...