Check which Topaz compiler is installed and choose where to run your program. For compiler investigations, the detailed sections below show how to save and read compilation records.
Check your installation
Install the Topaz CLI, then run this command in a terminal.
topaz version --verboseThe output lists the compiler version, language mode, runtime version, and Rust backend. These two lines identify the language mode and backend.
Language mode: topaz-5.20
Rust backend: rust (CDR-006)Rust backend means that native builds generate Rust. The default compiler is written in Topaz. Include the complete output when reporting an installation problem. If the terminal cannot find topaz, reopen it and check the installation folder in PATH.
Topaz 5.20.4 is the current product. The current language mode is topaz-5.20. Official releases are available on topaz.ooo and npm. Find the source at topaz.ooo/dl.
The npm package includes the compiler in one executable and needs no repository checkout. The executable keeps the Lispex application sources and the compiler program image compressed and decompresses each one the first time a command needs it. Built products run after the Topaz source is removed. If embedded compiler identifiers do not match, compilation stops and reports the mismatch. Reinstall Topaz to restore the installation.
Choose an execution environment
| Task | Product and requirements |
|---|---|
| Check and run local source | The CLI checks files and multi-file packages, then runs them with the interpreter |
| Deliver a desktop or server program | --target native builds a platform-specific executable through Rust and Cargo |
| Call Topaz from JavaScript | --target web builds a WASM package for an existing JavaScript host |
| Run calls in a browser Worker | --target web-worker adds Worker request and response modules |
| Try code without installing the CLI | The browser Playground checks and interprets source |
WASM builds also need Rust's wasm32-unknown-unknown target. Follow Interpreter & Backends to choose a target and find its complete example. Copy the whole build output folder when deploying.
All targets share parsing, module resolution, and static checking. Host operations depend on the target. An unsupported operation produces a source-located error before the product is written. Fix that operation or choose an environment that supports it. Concurrent tasks have no fixed execution order. Join them before producing ordered output.
Run Lispex rules
The installed evaluator runs one request with topaz lispex embed run. Lispex Evaluator and LIT provides the three input files, command, and report fields. A completed evaluation writes result.lpxvalue and report.json. A rule failure or resource limit writes report.json. A rejected request or engine failure creates no output folder.
The installed product fixes the evaluator, profile, resource rules, and input checks. It does not download another evaluator or invoke callbacks, imports, or a fallback. The CLI report records the Topaz execution. Application artifact APIs create portable Lispex-format records.
Use the locked std.lispex API to call rules from a Topaz application. It runs in the interpreter and on all five native release targets. Run Lispex Rules covers the manifest, lock, build, saved results, and replay. raw-web, worker-web, no-capability, and mcp-empty-component-set reject these calls before output or execution. --target lispex also rejects before output. LIT is a Lispex integration test program, separate from the installed evaluator and build targets.
Read the installed compiler status
topaz compiler status --jsonThe command exits with code 0 and prints JSON. These selected fields show the default compiler and reference compiler.
{
"schema": "topaz.compiler-support/v5",
"languageMode": "topaz-5.20",
"defaultCompiler": "self",
"referenceCompiler": "rust",
"silentFallback": false
}self selects the compiler written in Topaz. It handles parse, check, test, run, bench, emit, build, fmt, lsp, doc, and compiler observe by default. A compiler failure stops the command without switching to Rust.
Find the object with selector equal to self in compilers. Read its fields and the separate routes array as follows.
| Field | What to check |
|---|---|
status, executionKind | A healthy native compiler reports supported and native |
sourceSetId, runtimeSourceSetId | Identify the compiler source files and runtime source files |
nativeLinkId, generatedRustSha256 | Identify the linked compiler and its generated Rust source |
target | Names the platform of the installed compiler |
routes[].command | Names a command that the inventory describes |
routes[].self, routes[].condition | State support and the conditions for that command |
routes[].omitted | Shows the compiler used when you omit --compiler |
Save a compiler observation
A compiler observation records what the compiler did with one input, through generated Rust. Use it to investigate a compiler difference. It contains the source, so protect the folder as you would protect your source project.
Create an empty working folder. Save this as main.tpz inside it.
print("ready")From that folder, run the following commands. The ../ paths put the output beside the source folder. Choose unused output folders. Output inside the source root is rejected because a later observation could collect its own files.
topaz compiler observe main.tpz --out-dir ../topaz-observation
topaz compiler validate ../topaz-observationBoth commands exit with code 0 and print these lines in order.
../topaz-observation: compiler-observation-ok
../topaz-observation: compiler-observation-validThe bundle includes sources/, topaz-observation.json, provenance.json, and records for each compiler step. validate reads the bundle without changing it, recompiling, or reopening the source tree. It checks encoding, schemas, ordering, references, required records, sizes, and hashes. If validation fails, keep the error and create a fresh observation from the original source.
Read the compilation records
The installed executable contains native compiler code generated from Topaz source. Before compiling, its adapter checks the embedded source and runtime identifiers. A mismatch stops the command. It computes target source, diagnostics, generated source, and output files afresh for each request.
The versioned compilation result contains ordered modules, tokens, the syntax tree, resolved names and exports, types, and profile diagnostics. A profile specifies supported features and execution rules. The result also records internal code conversion (lowering), required runtime operations, generated Rust, and the request and result identifiers. The adapter validates and decodes these records. It rejects missing compiler decisions.
Native build manifests record the compiler and producer, compiler and target source sets, compilation result, and generated-source hash. A source set is the collection of files included in a compilation.
Read fixed-point and producer information
Open ../topaz-observation/provenance.json to find the compiler and inputs that produced the result. These selected fields describe separate checks.
{
"engine": "topaz-native-k",
"generatedSourceFixedPoint": "established",
"nativeBinaryReproducibility": "not-run",
"semanticFixedPoint": "not-established"
}generatedSourceFixedPoint records whether successive self-compilation stages produced identical generated Rust bytes. This is the generated-source fixed point. nativeBinaryReproducibility tracks executable-byte comparison. semanticFixedPoint tracks the compiler's intermediate records. Read each value separately. These fields are in the observation's provenance file. Use the status JSON above for the installed compiler's linkage, source identifiers, and supported commands.
Compare with the reference compiler
The installed executable also includes a Rust reference compiler for verification. From the same source folder, select it for an observation of the unchanged main.tpz.
topaz compiler observe main.tpz --compiler rust --out-dir ../reference-observation
topaz compiler compare --layer semantic ../topaz-observation ../reference-observationThe first command creates ../reference-observation and prints ../reference-observation: compiler-observation-ok. The second prints JSON. equal reports the comparison result, firstFailingPhase names the first differing step, and mismatches identifies the records. An equal comparison exits with code 0. A difference exits with code 1.
If the same input produces different compiler records, preserve both folders and the JSON report for a compiler defect investigation. --compiler rust is a verification choice. Commands never retry a failed self compilation with it. Language and Compatibility explains comparison layers and shows how an input change appears in JSON.