Packages & Distribution

Create a package, add dependencies from local folders, and keep their contents fixed with topaz.lock. If a locked command fails, use the recovery table to find the file to correct.

Install topaz using First Program. Run the commands below from a working folder where my-app, utility, and registry-app do not yet exist.

Create and run a package

BASH

topaz init --root my-app
topaz lock --root my-app
topaz fmt --check --root my-app
topaz check --root my-app --locked
topaz run --root my-app --locked

init creates my-app/topaz.toml and my-app/src/main.tpz. lock creates my-app/topaz.lock. The checks exit with code 0, and run prints Hello from Topaz.

topaz.toml is the manifest, the package configuration file. It records the name, package and language versions, entry file, default build target, and dependencies. When you omit a file argument, commands use its entry file.

topaz.lock records the manifest and dependency contents. --locked stops a command when those inputs no longer match. If formatting differs, run topaz fmt --root my-app and repeat the formatting check. For a package with tests, select their paths as shown in First Application.

Add a local dependency

Create a second package beside my-app, then add it.

BASH

topaz init --root utility
topaz add utility --path ../utility --root my-app
topaz lock --root my-app
topaz check --root my-app --locked

add writes a utility entry in my-app/topaz.toml with its path and a content hash. The hash identifies the dependency files. ../utility is relative to my-app, so it selects the sibling folder. lock updates topaz.lock, and the final check exits with code 0.

Copy a dependency from a local registry

Use a separate registry-app for this example. First copy the utility folder from the previous section to registry/utility/1.2.0 under your working folder. In the copy's topaz.toml, keep [package].name = "utility" and set [package].version = "1.2.0". Keep its source files and other generated settings.

BASH

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

vendor verifies the package, copies it to registry-app/vendor/utility/1.2.0, and writes registry-app/topaz.lock. The final check exits with code 0. This copying of dependencies into a project is called vendoring.

The --from path is relative to your working folder. fetch accepts the same local source and also writes vendored files and a lock file. Neither command downloads from a network registry. Running lock before a registry dependency has a recorded hash or vendored contents fails.

Fix a lock mismatch

Problem	Where to fix it
Manifest changed	Review `my-app/topaz.toml`. Restore an accidental change. For an intended change, run `topaz lock --root my-app` and review the `topaz.lock` diff.
Local dependency content changed	Restore the recorded files in `utility`. To accept an intended update, remove its dependency entry from `my-app/topaz.toml`, repeat `add` to record the new hash, then run `lock`. Review both diffs.
Registry package missing	Check `registry/utility/1.2.0/topaz.toml`, its name and version, and its source files. Repeat `vendor --from ./registry`.
Vendored content changed	Restore the recorded files or intentionally vendor the reviewed dependency again. If the manifest pins a hash, update that pin to the reviewed content.

After the correction, rerun check with --locked. A package still follows the module visibility and cycle rules.

Build for distribution

BASH

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

The command creates product/ with the executable and topaz-artifact.json. Package lookup uses the root, path dependencies, locked vendored files, and bundled toolchain inputs. Native and Web builds require the target's Rust toolchain and invoke Cargo internally with its locked offline mode.

Distribute the complete product directory and any application data its filesystem permissions require. At runtime, it needs no package sources, topaz.toml, topaz.lock, vendor, or Topaz CLI. See Artifacts & Deployment for execution requirements. If generated output has changed, preserve it and choose a new empty output directory.