Invocation, options and results
링크topaz run
topaz run [entry]
입력
Accept zero or one entry operand and the listed compiler, lock, verbosity, root, language, and resource options. Without an entry, use the package entry under the selected root.
Arguments after - belong to the program and retain their order and spelling. They are not parsed as Topaz options. Program arguments require the admitted explicit main signature.
Reject -, -, -, and - before execution. Invalid source, dependency identity, lock content, or entry signature also prevents execution.
옵션과 충돌
| 옵션 | 기본값 | 계약 | 충돌 |
|---|---|---|---|
--compiler rust|self | self | compiler selector (default self); rust selects the reference compiler Also rejects combination with --producer, --self-source. | 없음 |
--locked | false | Verify topaz.lock before compiling the selected package. | 없음 |
--verbose | false | Reports the selected compiler and whether it was explicit or the default. For | 없음 |
--root <dir> | entry directory; . in package mode | The explicit source root or package root for this invocation. | 없음 |
--language-version <5.21> | 5.21 | language version selector | 없음 |
--compiler-memory-mib <MiB> | 8192 | self compiler worker memory budget (8192); overrides TOPAZ_COMPILER_MEMORY_MIB A positive integer is required. Environment input: TOPAZ_COMPILER_MEMORY_MIB. | 없음 |
--compiler-time-ms <ms> | 1800000 | self compilation wall-clock budget (1800000); overrides TOPAZ_COMPILER_TIME_MS A positive integer is required. Environment input: TOPAZ_COMPILER_TIME_MS. | 없음 |
-- <args...> | 미지정 | run/build --run: explicit program args passed to exported main(args, stdin) ( | 없음 |
출력 채널
stdout
stderr
종료 상태
0
Top-level execution succeeds or explicit main returns Ok(0), and no deferred error occurs.
1
Arguments, loading, checking, runtime execution, or process-result validation fails.
nonzero
An admitted explicit main returns Ok(code) with an integer from 1 through 255 and no deferred error forces exit 1.
효과
Compilation reads project inputs and may use an owned temporary workspace. The tool does not edit source, manifest, lock, or vendor files. After successful checking, the program can perform the filesystem effects admitted by its host. Those runtime effects are not rolled back on failure.
The compiler and package loader do not use the network or fetch dependencies. The executed program may contact services through the capabilities provided by its host.
Compilation is repeatable for fixed source, dependencies, options, and toolchain. Program output and exit status also depend on program arguments, standard input, environment, filesystem, time, randomness, and external services. Equal source bytes alone do not imply equal runtime output.
Resolve the selected package and verify required lock identity before execution. Registry dependencies must already be materialized. No implicit add, lock, or vendor operation occurs.
Registry dependencies or Lispex configuration require explicit -, even when a matching lock exists. Without that option, a local-only package can load declared path dependencies by their expected hashes. Locked loading rejects missing or stale state and never repairs it.
Standalone entry mode rejects -. Selected-entry test is the exception when an explicit root contains the package manifest and the entry belongs to that package.
Operation
링크Arguments after the argument separator belong to the program. Package configuration and the selected compiler determine the available execution path.
Option conditions
링크--locked applies to package-mode check, run, emit, build, test, doc, bench, compiler observe, compiler preview. Selected-entry test also accepts it when --root contains topaz.toml.
- cannot be combined with bootstrap - or -
Behavior contract
링크Command behavior
Arguments and rejection
Accept zero or one entry operand and the listed compiler, lock, verbosity, root, language, and resource options. Without an entry, use the package entry under the selected root.
Arguments after - belong to the program and retain their order and spelling. They are not parsed as Topaz options. Program arguments require the admitted explicit main signature.
Reject -, -, -, and - before execution. Invalid source, dependency identity, lock content, or entry signature also prevents execution.
Output
Program standard output remains standard output. Runtime diagnostics, command errors, and verbose compiler selection use standard error. The command does not wrap program output in a JSON object or add a check success banner.
- is rejected. A program may itself print JSON, which remains program data.
Exit status
Successful top-level execution or an explicit main result of Ok(0) exits 0. An explicit main returns Result<int, string>. Ok(code) uses an integer from 0 through 255 as the process exit code. Err(message) writes the string to standard error and exits 1. An out-of-range code or an invalid result shape fails with exit 1.
Argument, package, compile, runtime, deferred-action, worker, and host-operation failures exit 1. Output and program effects that occurred before a runtime failure remain observable.
A deferred runtime or host error forces exit 1 even when main returned Ok(0). Earlier program output and effects remain observable.
Filesystem effects
Compilation reads project inputs and may use an owned temporary workspace. The tool does not edit source, manifest, lock, or vendor files. After successful checking, the program can perform the filesystem effects admitted by its host. Those runtime effects are not rolled back on failure.
Network access
The compiler and package loader do not use the network or fetch dependencies. The executed program may contact services through the capabilities provided by its host.
Reproducibility
Compilation is repeatable for fixed source, dependencies, options, and toolchain. Program output and exit status also depend on program arguments, standard input, environment, filesystem, time, randomness, and external services. Equal source bytes alone do not imply equal runtime output.
Packages and locks
Resolve the selected package and verify required lock identity before execution. Registry dependencies must already be materialized. No implicit add, lock, or vendor operation occurs.
Registry dependencies or Lispex configuration require explicit -, even when a matching lock exists. Without that option, a local-only package can load declared path dependencies by their expected hashes. Locked loading rejects missing or stale state and never repairs it.
Standalone entry mode rejects -. Selected-entry test is the exception when an explicit root contains the package manifest and the entry belongs to that package.
이유
Running requests program effects after checking. Rejection must happen before execution so an invalid tool request cannot still perform the program's work.
The linked public CLI recipe checks the exact displayed argument rejection before the requested operation. It does not execute the successful operation or verify its effects.
The safe recipe proves rejection of the unsupported JSON selector. Successful program execution, process input, and runtime effects are outside that reviewed argument vector. The deferred-error scenario requires successful main completion followed by a failing cleanup and is not executed by the safe recipe.
Example contract
링크Example contract
The invocation topaz run main. is expected to exit with 1.
This command does not provide a JSON report format. The invocation is rejected during argument validation before processing the program.
이유
This command does not provide a JSON report format. Rejecting the option prevents a successful exit from silently ignoring the requested output format.
Example
링크Argument-rejection example
링크function identity<T>(value: T) -> T {value}
기대 결과
기대 결과
Textual rejection details remain Pending in the reference model. The independent Tools example gate expects exit 1.
This command does not provide a JSON report format. The invocation is rejected during argument validation before processing the program.
Verification scope
링크Observed with Topaz 5.21.3 on 2026-11-06T08:36:29.642Z. This invocation passed; exit 1. 3 assertions were evaluated against the independent expected result. Execution record. This result covers the displayed invocation.