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 to configure a single HTTP/1.1 handler.

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 bounded Bytes or ByteBuffer operations. Unsupported shapes remain on the general boxed path. It does not convert Python targets into native code or change a Web product into another target.

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, but they do not guarantee unqualified support for every host-dependent operation. If a selected target cannot preserve an operation, code generation reports a source-located error before writing the product.

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 several Topaz routes, but it is not a shipped backend and does not prove whole-language equivalence.