emit

Arguments and rejection

topaz emit [entry] accepts one optional source entry. Without an entry it loads the package at --root <dir>, defaulting to the current directory. With an entry, the default root is its directory.

The output target is rust. --target rust selects it explicitly and any other target is rejected. Without --out-dir, the primary source is written to standard output. With --out-dir <dir>, the directory value must be nonempty.

--compiler selects self or rust. --backend selects boxed or native. The defaults are self and boxed. Native lowering requires --compiler rust.

--native-report-json <file> requires native lowering and a nonempty file path. It requests a separate lowering report and does not select JSON presentation for emitted source.

A package with a reached Lispex application requires --out-dir so that its runtime closure can accompany the generated source. Program arguments, --run, --release, output-format options, missing values, repeated options, attached values, and additional entries are rejected.

Output

Without --out-dir, standard output contains the primary UTF-8 generated Rust source and no human banner. Standard error carries diagnostics and requested verbose compiler details.

With --out-dir, standard output is empty and standard error identifies the completed self-contained crate. The crate contains generated source, Cargo.toml, Cargo.lock, pinned toolchain information, the vendored runtime closure, and source-distribution notices.

--format json is rejected because emit has no JSON report mode. The optional native lowering report is written to its requested file with schema identifier topaz.native-lowering-report.v1. It does not change ordinary output channels.

No source output is produced for an argument, package, resolution, checking, or lowering failure. A later output I/O error can leave a partial stream or partially written crate and is reported as failure.

Exit status

Exit code 0 means the requested source stream or complete crate was emitted successfully.

Exit code 1 covers invalid arguments, input or lock failures, parsing, resolution, checking or lowering failures, unsupported compiler or profile combinations, resource exhaustion, missing runtime components, and output or report write failures.

Filesystem effects

The command reads the selected source and applicable package inputs. Emitting to standard output creates no output crate. Compiler workspaces may be created by the selected compiler.

--out-dir creates the crate directory and writes the generated crate files and admitted runtime closure. Existing files with generated paths may be replaced. Files outside the chosen output directory are not crate outputs.

The optional native report is staged and published at its explicit path. It does not grant authority to modify the input manifest or lock. A failed crate write can leave files already written during that invocation.

Network access

Emission uses local package content and the installed runtime closure without network access. It neither invokes Cargo to build the crate nor executes the generated program.

Reproducibility

Identical source and package bytes, lock identities, compiler, language mode, backend, and runtime components produce identical generated source and crate content. Generated content does not depend on enumeration order, wall-clock time, or a random workspace name.

Diagnostics can include input paths and the completion line includes the chosen destination. Comparing those streams requires the same path inputs.

Packages and locks

--locked verifies an existing package lock before compilation. Registry dependencies and Lispex configuration require it. Missing or mismatched dependencies fail rather than being materialized.

Emission leaves topaz.toml and topaz.lock unchanged. The generated crate's Cargo.lock binds its embedded Rust runtime closure and does not replace the Topaz package lock.

The invocation topaz emit main.tpz --language-version 5.21 --target invalid is expected to exit with 1.