Topazdocs
Build & Delivery

Packages & Distribution

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

A package provides Topaz modules with a single root, entry point, dependency graph, and build target. It introduces no new syntax and does not relax module visibility or cycle rules.

1. Create the package root

BASH
topaz init --root my-app

The root contains topaz.toml and src/main.tpz. The manifest specifies the package name, language version, entry point, default build target, and dependencies. Commands executed with --root my-app without specifying an entry point use the entry point from that manifest.

Web Application and HTTP scaffolds are selected upon 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 aborts execution if the manifest, lockfile, or local bytes differ. Update the manifest intentionally, run lock again, review the diff, and 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 lockfile. Running lock before a registry package has a recorded hash or vendored content fails instead of 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 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 additional Topaz flag is required.

The finished managed product is the distribution unit. It does not require 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 the diff.
  • If a registry package is missing, obtain the explicit local registry input and run vendor or fetch. Do not remove --locked.
  • If vendored content has changed, restore the recorded bytes or intentionally vendor and review the updated dependency.
  • If build output has drifted, use a new empty output directory rather than deleting unknown files.