Topazdocs
Build & Delivery

Packages & Distribution

Use package roots, manifests, locks, local dependency bytes, and managed products in the right order.

A package gives ordinary Topaz modules one root, entry, dependency graph, and build target. It does not add syntax or relax module visibility and cycle rules.

1. Create the package root

BASH
topaz init --root my-app

The root contains topaz.toml and src/main.tpz. The manifest names the package, current language, entry, default build target, and dependencies. Commands with --root my-app and no entry use that manifest entry.

Web Application and HTTP scaffolds are selected at creation:

BASH
topaz init --target web-app --root my-web-app
topaz init --target http-service --root my-service

2. Lock a package without registry dependencies

BASH
topaz lock --root my-app
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.lock records the root manifest and resolved local dependency content. --locked refuses to continue when the manifest, lock, or local bytes differ. Update the manifest intentionally, run lock again, review the diff, then restore --locked.

3. Add local or registry dependencies

A path dependency is added with its relative path and content identity:

BASH
topaz add utility --path ../utility --root my-app
topaz lock --root my-app

A registry dependency must exist in a local registry input before it can be locked:

BASH
topaz add utility@1.2.0 --root my-app
topaz vendor --root my-app --from ./registry
topaz check --root my-app --locked

vendor verifies the selected package, copies it to vendor/utility/1.2.0, and writes the lock. Running lock before the registry package has a recorded hash or vendored content fails rather than contacting a network registry. fetch accepts the same explicit local --from boundary; neither command performs ambient network resolution.

4. Build from local inputs

BASH
topaz build --root my-app --locked --release --out-dir product

Package resolution now uses only the root, path dependencies, locked vendored bytes, and bundled toolchain inputs. Native and Web compilation also invokes Cargo in its locked offline mode internally; no extra Topaz switch is required.

The finished managed product is the distribution unit. It does not need topaz.toml, topaz.lock, vendor, package source, or the Topaz CLI at runtime. Copy the complete product directory and any application data required by declared filesystem capabilities.

Recover without weakening the lock

  • If --locked reports manifest drift, decide whether the manifest change is intended, regenerate the lock, and review it.
  • If a registry package is missing, obtain the explicit local registry input and run vendor or fetch; do not remove --locked.
  • If vendored content changed, restore the recorded bytes or intentionally vendor and review the new dependency.
  • If build output drifted, use a new empty output directory rather than deleting unknown files.