Core Rust, MLIR, and C/FFI boundary code should include explicit comments whenever safety assumptions, phase contracts, missing support, or non-obvious invariants would otherwise be unclear.
Zmeu is a Rust compiler prototype with staged HIR, MIR, MLIR, and native
backend paths. Core Rust lives in src/, including src/mir_v1, src/mlir,
src/runtime, and src/syntax_v1. Runtime C support is in runtime/, standard
library sources are in std/, and MLIR dialect/pass code is under mlir/.
Tests are grouped through tests/phase0.rs and tests/phase0/. Examples live
in examples/; benchmark fixtures live in benchmarks/. Use STATUS.md and
docs/README.md as the active documentation map.
cargo fmt --check: verify Rust formatting.cargo test: run the default interpreter/frontend regression suite.cargo clippy --all-targets -- -D warnings: run default lint checks.cargo build --features mlir-backend: build MLIR support.env -u MLIR_DIR -u LLVM_DIR -u ZMEU_MLIR_DIR -u ZMEU_LLVM_DIR cargo test --features mlir-backend: run MLIR tests.cargo run -- check examples/core/control_flow.zmeu: check a sample program.cargo run --features mlir-backend -- build examples/core/control_flow.zmeu -o /tmp/zmeu-control-flow: build natively.ZMEU_BIN=target/release/zmeu benchmarks/ir_counts.sh: collect IR counters.
Use standard Rust formatting and keep lints warning-free. Prefer names that
match existing compiler phases: HIR, MIR, CFG MIR, MLIR, and runtime. Rust
modules/functions use snake_case; types/variants use UpperCamelCase.
Every feature can expand across HIR, MIR, diagnostics, borrowing, MLIR, runtime, and examples, so design the full path first. If a feature, syntax change, or implementation path appears likely to harm Zmeu's goals, say so before implementing it. Explain the downside, then propose better-scoped variants that preserve the compiler contract, safety boundary, diagnostics, and trajectory.
The core pipeline rule is:
checker proves safety
lowering preserves facts
backend assumes facts
runtime defends only where needed
diagnostics retain source spans through every frontend phase
LLVM codegen must not become the safety checker. Invalid programs should never reach codegen.
Add semantic tests before backend-only changes. Put phase0 coverage in
tests/phase0/*.rs, and use small examples/ fixtures. Diagnostics need stable
rule IDs, deterministic text, source spans, expected/found wording, and concrete
fix guidance. Run default and mlir-backend tests when touching lowering,
runtime, native builds, or MLIR.
PR titles must use Conventional Commit format because squash-merge titles feed
Release Please changelogs and version bumps. Use lowercase types such as
feat:, fix:, perf:, docs:, refactor:, test:, chore:, ci:, or
build:; add ! for breaking changes. Do not include [codex] in PR titles.
Use descriptive commit messages that make the implemented change inferable from
history. Prefer an imperative subject plus a body for non-trivial work, and use
Conventional Commit subjects for merge-bound commits: feat: add Result CLI fixture followed by bullets explaining parser/checker/runtime effects and
tests. PRs should explain motivation, changed compiler phases, verification
commands, benchmark threshold updates, and intentional diagnostic wording
changes.
Do not treat archived plans as permission to broaden the language surface. When
MLIR syntax, dialect design, lowering, TableGen/ODS, or Rust/C++ MLIR boundary
details are unclear, consult both docs/zmeu-mlir-skill.md and the official MLIR
documentation at https://mlir.llvm.org/docs/ before guessing. Prefer small
executable milestones, deterministic output, and inspectable compiler facts.