Check whether your program follows Topaz's rules, then test its behavior in the environment where it will run. If compiler results differ, choose a comparison layer that answers your question.
Install the Topaz CLI. Use Toolchain Status to check the installed compiler and supported targets.
Check and run a file
Create an empty working folder and save this as main.tpz.
import std.io
io.writeLine("ready")
Run these commands from that folder.
topaz check main.tpz
topaz run main.tpz
Both exit with code 0. The first command reports these results.
main.tpz: types-ok (2 modules)
main.tpz: resolve-ok (2 modules)
The second prints ready. check finds syntax, name, type, and selected-profile errors. A profile defines supported features and execution rules. Test the program's outputs, file changes, and exit status with inputs that matter to your application.
For a deployable program, follow First Application to build and run outside the source project. Check the target's requirements. An unsupported operation must fail before product output. Keep the exact inputs, toolchain, environment, profile, and resource limits with a test result.
Find the right source of information
| Question | Where to look |
|---|---|
| What does this syntax or type mean? | The language specification, SPEC, defines syntax, types, and behavior |
| Does this file pass the selected checks? | The checker reports errors or accepts the file |
| What happens when this input runs? | Run it with the interpreter or generated product in the intended environment |
| How do I use a supported feature? | The manual's examples connect inputs, commands, and results |
| What did a particular test exercise? | Its recorded inputs, environment, limits, and observed results |
Choose what to compare
A compiler observation saves the source and compiler records from one compilation. Toolchain Status explains its files and validation. compiler compare reads two saved observations without reopening the original source.
| Layer | Comparison |
|---|---|
semantic | Source files and successive compiler records through diagnostics and outcome. Stops at the first differing step |
generated-source | Exact generated Rust bytes |
provenance | The compiler and inputs that produced the result |
native-binary | Exact executable bytes for the same target. Takes executable paths instead of observation folders |
Generated source and provenance are compared independently. A different producer identifier changes the provenance comparison. Check the semantic result separately, and run application tests to compare behavior.
Read a difference in JSON
Continue in the folder containing main.tpz above. Observations contain source code, so protect them accordingly. Choose unused output folders outside the source folder.
topaz compiler observe main.tpz --out-dir ../before-observation
The command exits with code 0, creates ../before-observation, and prints ../before-observation: compiler-observation-ok. Now replace ready with done in main.tpz, keeping the rest of the file unchanged.
topaz compiler observe main.tpz --out-dir ../after-observation
topaz compiler compare --layer semantic ../before-observation ../after-observation
The observation command exits with code 0 and prints ../after-observation: compiler-observation-ok. The comparison exits with code 1 because the source changed. These fields are excerpted from its JSON output.
{
"equal": false,
"firstFailingPhase": "source-set",
"layer": "semantic"
}
equal answers whether the selected layer matched. firstFailingPhase identifies the first difference, here the input source set. Read mismatches in the full output for file paths and details. If the change was unintended, restore ready in main.tpz and create a new observation. Keep the original folders when reporting an unexpected difference.