Choose where your program will run, then select the command that creates the needed output. Use a native executable for a desktop or server, or a WASM package for JavaScript calls in a browser or Worker.
Install the Topaz CLI first. Building native or WASM products also requires Rust and Cargo. WASM builds require the Rust target wasm32-unknown-unknown.
Choose by task
| Task | Command or option | Result and complete example |
|---|---|---|
| Run source during development | topaz run | Interpreter output in the terminal. Follow First Program |
| Deploy to a desktop or server | topaz build --target native | An executable for the build machine. Follow Rust Backend |
| Call exported functions from JavaScript | topaz build --target web | WASM, a JavaScript module, and type declarations. Follow WASM & Playground |
| Run those calls outside the browser main thread | topaz build --target web-worker | The Web files plus Worker request and response modules. See WASM & Playground |
The JavaScript application supplies the UI and permissions for Web and Worker products. Copy the complete build output folder when deploying.
Output target and internal code conversion
The output target decides where the program runs. --target native creates an executable. --target web and --target web-worker create WASM packages.
Internal code conversion (lowering) turns a checked program into code the backend can execute. The Topaz compiler is written in Topaz and is selected by default. It builds native executables with --target native. It rejects the specialization option --backend native as an unsupported operation.
For reference-compiler validation, --compiler rust --backend native selects the Rust reference compiler and its specialization strategy. It specializes eligible scalar operations and supported Bytes or ByteBuffer operations. Other operations keep a general value representation that stores runtime type information (boxed). This choice keeps the output target you selected.
To inspect that conversion, add --native-report-json <path> to reference-compiler emit or build with those two options. The JSON report records native, hybrid, and boxed decisions. Writing the report does not change the product bytes. See Toolchain Status for compiler inspection commands.
Handle unsupported operations
All targets share syntax, module, and type checks. Each target also checks which operations its execution environment supports. If an operation cannot retain its behavior, code generation reports its source location and stops before writing the artifact. Fix that operation or choose an environment that supports it.
For example, the interpreter, generated Rust, Web, Worker, and Playground support fixed-Huffman DEFLATE, fixed zlib, and RS(255,223) protection. These operations produce deterministic results. Concurrent tasks can run in different orders, so do not rely on one backend repeating a particular order.
Generated Rust and integration tests
Generated Rust and its runtime files can be regenerated. Keep application changes in Topaz source. Generated files do not provide a stable API for manual extensions or add Rust syntax to Topaz. See Rust Backend for build requirements and integration conditions.
LIT is a Lispex interpreter used for integration tests. It runs the same Topaz source directly, through generated Rust, and through Web. Its records identify the program, execution paths, inputs, and results. To use it, follow Lispex Evaluator and LIT. LIT is a test program, not an output target.