Topazdocs
Tools & Execution

Interpreter & Backends

Select a Topaz execution or delivery target and understand how unsupported behavior fails closed.

Topaz features a single checked source language with multiple execution and delivery paths. Select the path for the environment that will host the finished program.

Choose by product

  • Use topaz run for direct interpreter execution during development.
  • Use native build to produce a platform-specific executable.
  • Use --target python to generate a bundle that runs without .tpz source or the Topaz CLI on Python 3.11 or newer.
  • Use --target web when an existing ES-module host calls selected Topaz exports.
  • Use --target web-worker when that host requires generated Worker transport.
  • Use package target web-app when Topaz manages the browser lifecycle and UI.
  • Use package target http-service for an HTTP/1.1 handler with declared request and response budgets, overload behavior, loopback binding, and graceful shutdown.

Raw Web and Worker are WASM targets. The managed Web Application includes the same checked Web facade inside a complete static product.

BASH
topaz run main.tpz
topaz build main.tpz --out-dir native-product
topaz build --target python --root my-app --locked --out-dir python-product
topaz build main.tpz --target web --out-dir web-product
topaz build main.tpz --target web-worker --out-dir worker-product

web-app and http-service are package-only targets selected by [build].target in topaz.toml.

Target and lowering are different choices

--target selects the product. --backend native provides an optional lowering strategy inside Rust-based products. It first attempts eligible scalar work and the Bytes or ByteBuffer operations supported by native lowering. Other shapes use the general boxed path. Python and Web products retain their selected targets.

When lowering decisions require inspection, a checked native emit or build can write --native-report-json <path>. The report records which functions used native, hybrid, or boxed lowering without changing product bytes.

Fail closed at the target boundary

Targets share parsing, module resolution, and static checking. Each target defines its host operations explicitly. If a selected target cannot preserve an operation, code generation reports a source-located error and rejects before artifact output.

For example, deterministic fixed-Huffman DEFLATE, fixed zlib, and RS(255,223) protection are available through the interpreter, generated Rust, Raw Web, Worker, and Playground, but generated Python rejects those operations before artifact creation. Hash.crc32 is available on Python as well.

Concurrent task ordering is intentionally unspecified. A program must not rely on a backend selecting a particular interleaving.

Rust, Python, and LIT boundaries

Generated Rust and Python are delivery artifacts, not extended Topaz syntax or stable APIs for manual editing. Their dedicated pages describe prerequisites, runtime files, and explicit exceptions symmetrically.

LIT is a Lispex test and integration surface. It exercises a single Topaz-written interpreter source through direct execution, generated Rust, generated Python, and Web routes. LIT remains separate from shipped output backends, and its records identify the exact program, routes, inputs, and observed results.