Topazdocs
Build & Delivery

Artifacts & Deployment

Inspect exact Topaz product trees, run them without the Topaz package source, and recover safely from output drift.

emit exposes replaceable generated source for inspection or integration. build creates a managed delivery product. Deploy the build directory, not temporary compiler storage or selected generated files copied out of context.

Build products

BASH
topaz build main.tpz --release --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
topaz build --root my-app --locked --release --out-dir package-product

The final command uses [build].target from topaz.toml; web-app and http-service are package-only. topaz.lock belongs to authoring and qualification. The finished managed product records its own identity in topaz-artifact.json.

Files common to every product

Every successful build adds these files:

Output
LICENSE
NOTICE
GENERATED-OUTPUT-NOTICE.txt
topaz-artifact.json

The artifact manifest records target, toolchain and language identity, runtime requirements, invocation, and each managed file's path, size, hash, and executable requirement. It is written last.

Target-specific trees

Native adds one platform-specific file:

Output
target/debug/program[.exe]
target/release/program[.exe]

Only the selected profile exists. On Windows the filename ends in .exe.

Python adds:

Output
program.py
topaz_py_rt.py

Raw Web adds:

Output
topaz-web.js
topaz-web.d.ts
topaz-web.wasm

Web Worker adds the Raw Web files plus:

Output
topaz-web-worker.js
topaz-web-worker-client.js

A managed Web Application adds the Raw Web files plus:

Output
index.html
topaz-app.js
topaz-web-capabilities.json
styles/app.css

Declared styles and assets keep their normalized relative paths, so the last line varies with the package.

A bounded HTTP service adds:

Output
target/release/program[.exe]
topaz-service-config.json
THIRD-PARTY-NOTICES.txt

This example captures a release build. A debug build uses target/debug; on Windows, [.exe] is present.

Run without the Topaz package source

Copy the complete product directory to a fresh location. Then run from its root:

BASH
./target/release/program
python3 program.py

Use the command that belongs to the chosen native, HTTP, or Python product. Python requires version 3.11 or newer. Native and HTTP executables are specific to the platform where they were built.

Serve a managed Web Application directory over HTTP and open index.html. Raw Web and Worker products need an ES-module host that imports the generated JavaScript API. None of the Web products should rely on file:// module loading.

Native and Python package applications resolve declared filesystem capability roots from the process working directory. Copy application data/ and create writable output directories beside the managed product when the manifest requires them; package data is not added automatically. Web styles and assets are different: declared [web] inputs are copied into the managed Web product.

Output-directory safety and recovery

Rebuilding the same target first verifies existing managed bytes. Topaz rejects a target change, malformed manifest, changed managed file, symlink, or collision with a user-owned path. Files not listed in the artifact manifest are preserved.

Do not erase an ambiguous directory to force a build. Keep it for inspection and choose a new empty --out-dir. If the old product must be restored, restore the complete known-good product rather than editing hashes or deleting individual managed files.