Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Tools

    bench

    Measures resolution and type checking for a selected unit.

    Invocation, options and results

    Link

    topaz bench

    Synopsis
    1. topaz bench [entry]

    Input

    Accept zero or one entry operand and the listed compiler, lock, verbosity, root, language, resource, and format options. Select the package entry when the operand is absent.

    Accept --format human and --format json, with human output by default. Reject --json, invalid formats, program arguments, and unrelated build or execution options.

    Options and conflicts

    OptionDefaultContractConflicts
    --compiler rust|selfself

    compiler selector (default self); rust selects the reference compiler Also rejects combination with --producer, --self-source.

    		None listed
    --lockedfalse

    Verify topaz.lock before compiling the selected package.

    		None listed
    --format human|jsonhuman

    Selects human output or one JSON report. The default is human output.

    		None listed
    --verbosefalse

    Reports the selected compiler and whether it was explicit or the default. For version, prints the detailed release report.

    		None listed
    --root <dir>entry directory; . in package mode

    The explicit source root or package root for this invocation.

    		None listed
    --language-version <5.21>5.21

    language version selector

    		None listed
    --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.

    		None listed
    --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.

    		None listed

    Output channels

    stdout

    stderr

    Exit status

    0

    Checking succeeds and the benchmark report is produced.

    1

    Arguments, loading, checking, compiler execution, or report generation fails.

    Effects

    Read the selected source graph and existing dependencies. Do not execute the program, write build artifacts, or change project inputs. Compiler-owned temporary workspace files may be used.

    The command performs no network access and does not fetch dependencies.

    Fixed compiler, source, dependency, and option inputs produce the same check verdict and module count. elapsedMs measures the current execution and can vary. Path spelling and host conditions remain inputs to the report.

    Package loading and --locked verification follow check. Missing registry content or an invalid lock fails before measurement completes and never starts a vendor operation.

    Registry dependencies or Lispex configuration require explicit --locked, 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 --locked. Selected-entry test is the exception when an explicit root contains the package manifest and the entry belongs to that package.

    Operation

    Link

    Benchmark results describe the compiler pipeline for the supplied inputs. The selected program is not executed.

    Option conditions

    Link

    Use --format json for the JSON report. The --json spelling is rejected.

    --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.

    --compiler cannot be combined with bootstrap --producer or --self-source

    Behavior contract

    Link
    Ruletools-commands-bench.rule.behavior

    Command behavior

    Arguments and rejection

    Accept zero or one entry operand and the listed compiler, lock, verbosity, root, language, resource, and format options. Select the package entry when the operand is absent.

    Accept --format human and --format json, with human output by default. Reject --json, invalid formats, program arguments, and unrelated build or execution options.

    Output

    Human output identifies the entry, bench check-ok, the module count, and elapsed milliseconds. JSON output is one object on standard output with status equal to check-ok, string entry, integer modules, and numeric elapsedMs.

    Module counts and elapsed milliseconds are nonnegative. Diagnostics and command failures use standard error. Failure does not emit a successful benchmark report.

    Exit status

    Exit 0 means checking completed and the timing report was written. Exit 1 covers invalid arguments, package or lock loading, source diagnostics, compiler failure, exhausted resources, and report failure.

    Filesystem effects

    Read the selected source graph and existing dependencies. Do not execute the program, write build artifacts, or change project inputs. Compiler-owned temporary workspace files may be used.

    Network access

    The command performs no network access and does not fetch dependencies.

    Reproducibility

    Fixed compiler, source, dependency, and option inputs produce the same check verdict and module count. elapsedMs measures the current execution and can vary. Path spelling and host conditions remain inputs to the report.

    Packages and locks

    Package loading and --locked verification follow check. Missing registry content or an invalid lock fails before measurement completes and never starts a vendor operation.

    Registry dependencies or Lispex configuration require explicit --locked, 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 --locked. Selected-entry test is the exception when an explicit root contains the package manifest and the entry belongs to that package.

    Why

    Benchmarking requests a measurement of compiler work, not program execution. Timing must remain variable so a repeatability promise does not turn a measurement into an invented constant.

    Examples Benchmark JSON with --format json

    Source evidence

    The pinned public release recipe checks legacy argument rejection. It does not verify the adopted JSON-success contract. The separate published JSON test retains that expectation and its named implementation limitation.

    The allowed vector selects JSON, but the preserved public 5.21.3 recipe records its legacy rejection. The adopted JSON-success expectation remains in the existing published test and its precise limitation. No observation replaces that expectation.

    Example contract

    Link
    Ruletools-commands-bench.rule.invocation

    Example contract

    The invocation topaz bench main.tpz --language-version 5.21 --format json is expected to exit with 0.

    The benchmark checks the fixture without running it and writes a JSON report. Timing values vary between executions.

    Why

    Benchmarking produces timing measurements. The common format selector exposes those measurements as structured data without executing the program.

    Examples Benchmark JSON with --format json

    Source evidence

    Example

    Link

    Benchmark JSON with --format json

    Link

    check · command-validation · Verification: not-run

    main.tpzBenchmark JSON with --format jsonOpen in Playground
    1. function identity<T>(value: T) -> T {
    2. value
    3. }
    Expected outputexit 0
    $ topaz bench main.tpz --language-version 5.21 --format json · target product 5.21.3
    Expected result

    Expected result

    Checking accepts the program. Exit code 0.

    No stderr.

    Standard output is a JSON object. Its complete schema is not specified.

    This exact example has not been executed.

    The benchmark checks the fixture without running it and writes a JSON report. Timing values vary between executions.

    Source evidence

    Verification scope

    Link

    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.

    Related references

    Link

    Compiler selection

    Packages, locks and targets

    Menu

    Download