Topazdocs
Tools & Execution

Toolchain Overview

The standard Topaz authoring and delivery workflow, with next steps for each task.

The Topaz toolchain provides a single, verified path from source files and packages 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 code follows canonical formatting.
  2. check resolves modules and reports syntax, name, and type diagnostics without executing the program.
  3. test executes verified test entries on the deterministic test host.
  4. run executes a command-line application directly through the interpreter.
  5. build creates the single product target intended for delivery.

For a locked package, the complete command sequence 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 official extension. It recognizes .tpz files, adds the Topaz file icon, highlights language syntax, configures comments and brackets, provides basic snippets, and starts the installed topaz lsp server for editor diagnostics. The default topaz.compiler setting follows the compiler policy of the installed Topaz product. Choose rust only for explicit comparison or recovery, or self to request the installed self-hosted compiler explicitly.

The extension does not bundle a compiler. If it cannot find the configured Topaz executable, static highlighting and editing support remain available while the editor reports the missing executable. Use topaz.executablePath when Topaz is not on PATH.

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 non-zero exit code 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