Topazdocs
Tools & Execution

Interpreter & Backends

Choose a Topaz execution or delivery target and understand where unsupported behavior fails closed.

Topaz has one checked source language and several execution or delivery paths. Choose the path from the environment that will own the finished program.

Choose by product

  • Use topaz run for direct interpreter execution during development.
  • Use native build for a platform-specific executable.
  • Use --target python for a generated 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 needs generated Worker transport.
  • Use package target web-app when Topaz owns the browser lifecycle and UI.
  • Use package target http-service for one bounded HTTP/1.1 handler.

Raw Web and Worker are WASM products; 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 is an optional lowering strategy inside Rust-based products. It first tries eligible scalar work and bounded Bytes or ByteBuffer operations; unsupported shapes remain on the general boxed path. It does not turn Python into native or change a Web product into another target.

When the decision matters, 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 promise unqualified support for every host-dependent operation. If a selected target cannot preserve an operation, 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 depend on one backend choosing a particular interleaving.

Rust, Python, and LIT boundaries

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

LIT is a bounded Lispex integration and dogfood surface. It exercises one Topaz-written interpreter source through several Topaz routes, but it is not a shipped backend and does not prove whole-language equivalence.