Playground
(Lispex)
KOENRU

Install an Optional Extra Engine

Fetch an exact official Topaz virtual machine or ahead-of-time compiler companion, install a reviewed local archive, and select the route explicitly.

Start with the ordinary runtime

Lispex starts with its built-in reference interpreter.

SH
lispex rule.lspx

This reads your source directly. It is the default and the semantic reference. Install a companion when you choose the exact Topaz virtual machine or the admitted Topaz compiler that builds ahead of time.

Fetch an official companion

Native contains an exact, immutable route catalog. The current catalog has two macOS ARM64 entries. They are the Topaz 5.11 virtual machine and the exact Topaz 5.11 compiler that Lispex uses to build ahead of time. Choose a new absolute destination.

SH
lispex routes fetch \
  --route topaz-vm \
  --target aarch64-apple-darwin \
  --out /absolute/tools/lispex-topaz-vm

The command uses the immutable URL, channel, version, registry, and catalog in the Native route catalog. It checks the response length, SHA-256, accepted stored-ZIP shape, every installed file, and the closed Topaz product identity before publishing the destination. Target admission is resolved before the download begins.

Fetching publishes the installed product. Route selection happens at Use the product explicitly, where you pass /absolute/tools/lispex-topaz-vm/product.

Fetch the compiler companion separately when you intend to build a product compiled ahead of time.

SH
lispex routes fetch \
  --route aot-compiler \
  --target aarch64-apple-darwin \
  --out /absolute/tools/lispex-aot-compiler

Its closed product contains the exact compiler and release manifest. aot build combines that installed compiler executable with the absolute Rust tool directory selected by the caller.

SH
lispex aot build \
  --source rule.lspx \
  --topaz-compiler /absolute/tools/lispex-aot-compiler/product/bin/topaz-bin \
  --rust-tool-bin /absolute/rust/bin \
  --out /absolute/products/rule-aot

Install a handed-off archive offline

Obtain these two immutable local files from the same provider handoff.

  • a lispex.route-catalog/v1 file in its one accepted form, together with its exact SHA-256
  • the stored-ZIP archive named by the exact route and target entry

The catalog is a closed allowlist. It names the provider product, language mode, manifest hash, archive hash and length, and every installed file. The installer reads exactly the catalog and archive paths supplied by the caller.

Install one exact entry

Choose a new absolute destination that does not exist.

SH
lispex routes install \
  --route topaz-vm \
  --target aarch64-apple-darwin \
  --catalog /absolute/handoff/routes.json \
  --catalog-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --archive /absolute/handoff/topaz-vm-aarch64-apple-darwin.zip \
  --out /absolute/tools/lispex-topaz-vm

Replace the sample hash with the hash delivered alongside your exact catalog. The command reads local files only. On success it prints the same receipt that it writes here.

/absolute/tools/lispex-topaz-vm/
├── installation.json
└── product/

installation.json is a lispex.route-installation/v1 receipt in its one accepted form. It contains no absolute path or timestamp, so moving the unchanged directory preserves its identity. The product/ directory remains closed for the existing exact product validator.

For an admitted ahead-of-time compiler archive, change --route.

SH
lispex routes install \
  --route aot-compiler \
  --target aarch64-apple-darwin \
  --catalog /absolute/handoff/routes.json \
  --catalog-sha256 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef \
  --archive /absolute/handoff/lispex-topaz-aot-compiler-aarch64-apple-darwin.zip \
  --out /absolute/tools/lispex-aot-compiler

The admitted ahead-of-time compiler product targets macOS ARM64. The caller supplies Rust, the linker, the platform development kit, and system libraries for that exact target.

Use the product explicitly

Installation publishes the product while the reference interpreter remains the default. Select the route by supplying the closed product root.

SH
lispex routes inventory \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product

You can then create a lock and diagnose it. A lock records the identity of the installed product you chose independently from its filesystem path.

SH
lispex routes lock \
  --route topaz-vm \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product \
  --out topaz-route.json

lispex routes doctor \
  --selection topaz-route.json \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product

If you relocate the installation, pass the new absolute product/ path. Neither the lock nor the installation receipt remembers a filesystem path.

Run the complete installed journey

After building the compiled product, take an inventory of both optional engines and create one lock for each.

SH
lispex routes inventory \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product \
  --aot-product /absolute/products/rule-aot

lispex routes lock --route aot \
  --aot-product /absolute/products/rule-aot \
  --out aot-route.json

Use routes measure --samples 1 for one four-way comparison under fixed limits, then execute only the chosen lock.

SH
lispex routes run \
  --selection aot-route.json \
  --aot-product /absolute/products/rule-aot \
  --input input.datum \
  rule.lspx

You can move the virtual machine installation or the finished compiled product. Supply its new absolute root to routes doctor and routes run while keeping the lock unchanged. Doctor revalidates the bytes at that root, and the lock preserves the selection identity across relocation. The maintained portable route journey shows fetch, build, inventory, locks, doctor, measurement under fixed limits, locked execution, and relocation together.

What the archive is allowed to contain

Lispex accepts only one uncompressed stored-ZIP shape, fixed down to the byte. It rejects compression, Zip64, descriptors, encryption, timestamps, extras, comments, directories, duplicate or unsorted names, path traversal, absolute paths, backslashes, symbolic links, special files, excess files or bytes, and every hash mismatch. It writes through a private sibling stage and publishes only to a destination that still does not exist.

Exit 2 reports command usage, exit 1 reports an identity or byte-form contract, and exit 3 reports local input and output, a resource value, or atomic publication. Every result records the selected entry, target, version, path, and engine.

Artifact roles

A valid catalog and installation receipt establish exact byte integrity for installation. Signed distribution policy identifies the provider, comparison receipts record agreement with Rust, and the host application owns external actions. Vouch derives its evidence from authenticated exact source and a consumer-pinned request. The route receipt records automatic_fallback:false to preserve the selected engine.

Keep going

Use the runtime chooser for the simple default and the route doctor before any locked advanced execution.

Choosing Where to Run · Native CLI · Build a Product Compiled Ahead of Time

Install an Optional Extra Engine · Lispex