Topazdocs
Build & Delivery

Artifacts & Deployment

Inspect Topaz product trees, execute applications without package sources, and recover from output drift.

emit exposes replaceable generated source code 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 reads [build].target from topaz.toml. Targets web-app and http-service are package-only. The topaz.lock file belongs to authoring and qualification. The finished managed product records its identity in topaz-artifact.json.

Files common to every product

Every successful build produces these files:

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

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

Target-specific trees

Native builds add 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 builds add:

Output
program.py
topaz_py_rt.py

Raw Web builds add:

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

Web Worker builds add 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 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 require 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.