Topazdocs
Tools & Execution

Toolchain Overview

The ordinary Topaz authoring and delivery loop, with the next page for each task.

The Topaz toolchain gives files and packages one checked path from source to a runnable product. You do not need to understand parser or backend internals to use it.

The ordinary loop

Use commands in this order:

  1. fmt --check confirms that committed source has canonical formatting.
  2. check resolves modules and reports syntax, name, and type diagnostics without running the program.
  3. test runs checked test entries on the deterministic test host.
  4. run executes a command application directly through the interpreter.
  5. build creates the one product target you intend to deliver.

For a locked package, the complete shape is:

BASH
topaz fmt --check --root my-app
topaz check --root my-app --locked
topaz test --root my-app --locked
topaz run --root my-app --locked
topaz build --root my-app --locked --out-dir product

Web Application and HTTP packages use topaz dev for observable loopback development instead of topaz run, then use the same package-mode build.

Editor support

The official Topaz extension is available from both the Visual Studio Marketplace and the Open VSX Registry. Use the Marketplace listing for VS Code and the Open VSX listing for VSCodium or another compatible editor.

Both stores provide the same declarative TextMate extension. It recognizes .tpz files, adds the Topaz file icon, and highlights keywords, template tags, interpolation, Unicode identifiers, operators, numbers, and types. It does not run the compiler or provide completion and diagnostics; use topaz check for the authoritative result.

What success changes

fmt --check, check, test, and run do not create a deployment product. build writes a managed target directory and records its files in topaz-artifact.json. Package commands read topaz.toml; --locked also requires topaz.lock to agree with the manifest and local dependency bytes.

A nonzero exit means the requested step did not complete. Fix the first Topaz diagnostic and repeat that step. If an external compiler is missing, choose a target whose prerequisites are installed or install the required toolchain. If a managed output directory has drifted, preserve it and use a new empty directory.

Choose the next page by task