build

Arguments and rejection

topaz build [entry] accepts one optional source entry. Without it, the command loads topaz.toml from --root <dir>, which defaults to the current directory. With an entry, the default source root is the entry directory.

--out-dir <dir> is required and its value must be nonempty. The target is native, web, or web-worker. An explicit --target overrides the package manifest. Otherwise a package uses [build].target and an entry build uses native.

--release selects the optimized profile. Without it the native output uses the debug profile. --run executes a successfully built native artifact. Web targets reject --run before a build starts.

Program arguments follow -- and are accepted when --run is present. They are passed unchanged to the built program. A program receiving explicit arguments must provide the supported exported entry contract.

--compiler selects self or rust and defaults to self. --backend selects boxed or native and defaults to boxed. Native lowering requires --compiler rust. --native-report-json <file> requires native lowering and a nonempty path.

The common compiler resource options require positive integer values. Unknown targets or backends, unsupported language modes, unsupported compiler combinations, output-format options, repeated options, attached values, extra entries, and missing values are rejected before compilation.

Output

The build writes compiler diagnostics, build progress, warnings, and the final artifact path to standard error. A build without --run leaves standard output empty.

With --run, standard output and standard error from the program are inherited after the build succeeds. Build diagnostics remain on standard error.

--format json is rejected because build has no JSON report mode. The optional native lowering report is a separate file with schema identifier topaz.native-lowering-report.v1. It reports lowering decisions without replacing build output or the produced artifact.

A native build installs target/debug/program or target/release/program under the output directory, with the executable suffix required by the host. A web build installs topaz-web.wasm, topaz-web.js, and topaz-web.d.ts. A worker build also installs its worker entry and client glue.

The destination includes topaz-artifact.json and the required license and notice files. A reached Lispex application adds its identified runtime payload and host glue to the artifact.

Exit status

Exit code 0 means the requested artifact was installed and no requested native execution failed.

Exit code 1 covers invalid arguments, package or lock failures, parsing, resolution, checking or lowering failures, unsupported target or profile combinations, unavailable installed build tools, resource exhaustion, build-tool failure, and artifact publication failure.

After a successful build with --run, the command returns the program exit code when it is representable from 0 through 255. A failed process start, signal termination, or unrepresentable process status returns 1. Program failure does not remove the built artifact.

Filesystem effects

The command reads source, manifest, locked dependency content, and declared extern or Lispex inputs. It builds in a Topaz-owned temporary workspace and copies the final artifact into the requested destination.

An existing topaz-artifact.json must name the same target. Managed output paths must remain inside the destination and must not traverse symlinks. Existing unrelated files are preserved, and collisions with unowned paths are rejected.

New artifact bytes are staged before installation. Stale files recorded by the previous artifact manifest may be removed. The new manifest is installed after the managed files. An I/O failure during installation can leave incomplete output without a completed artifact manifest and returns failure.

Temporary workspaces and build logs may remain for storage inspection after a failed build. --run adds the filesystem and other host effects of the executed program. Those effects are governed by the applicable program host and package capabilities.

Network access

Compilation and artifact construction use installed components and offline locked build tools. Missing build inputs cause failure rather than a registry request, toolchain download, or compiler fallback.

Automatic native execution may perform the network operations allowed by the program host. A build without --run does not execute the application.

Reproducibility

The compilation identity includes the selected compiler, language mode, backend, target, build profile, source bytes, locked dependencies, runtime components, host build toolchain, and build configuration. Byte reproducibility compares artifacts with all of those inputs fixed.

Different host toolchains, target platforms, compiler choices, or build profiles are different inputs. Temporary paths, progress timing, and build logs are not stable artifact content. Program output under --run additionally depends on its arguments, input, and host effects.

Packages and locks

Package mode uses the manifest entry, dependency declarations, target configuration, and capabilities. --locked verifies the existing lock before compilation and does not create or repair it.

Registry dependencies and Lispex package configuration require locked compilation. Missing, stale, duplicate, or undeclared lock entries fail before artifact production. An entry-file build outside package mode rejects --locked.

Build does not edit topaz.toml, update topaz.lock, or vendor missing dependency content. The emitted native build crate has its own locked offline runtime closure, separate from the package lock.

The invocation topaz build main.tpz --language-version 5.21 --target invalid is expected to exit with 1.