Playground
(Lispex)
KOENRU

Where Your Program Runs

One program can run on four engines, the default needs no setup, and every other route is an explicit choice that never substitutes itself silently.

Result. You will name the four routes, which are the four engines that can run one program. You will explain which one you have been using all along and predict what happens when a requested route is not available.

What you need first. You should know how to run a .lspx file. The First Program lesson covers that, and nothing on this page requires installing anything new.

You have been using a route all along

Every time you ran a program like this

SH
lispex rule.lspx

you used the tree route. This built-in interpreter is written in Rust and reads your source directly. It ships inside the ordinary Lispex product as the default. It serves as the reference for what the language means, and it is the route you can always come back to. If you never touch another route, you are not missing anything. The language is complete on this route alone.

The four routes

A route is not one of the three places named on the home page. Those three places are the browser Playground, the npm package, and the downloadable program, which are the products you can run Lispex in. A route is the engine that runs your program once you are inside one of them. The Playground and the npm package carry no virtual machine and no ahead-of-time build, so they run the first route below. The downloadable program can use any of the four.

The same program can run on four engines.

  1. Tree. The built-in interpreter that reads your source directly and evaluates it. Always present, no setup.

  2. Rust virtual machine. Also built in. A virtual machine is a program that runs prepared instructions instead of source text. Native builds those instructions from your source, writing them the same way every time, and checks them before running. You ask for this route explicitly with --engine vm. Topaz is a separate language from Lispex and has a compiler of its own. The two routes below borrow those tools. A Lispex rule is written out as Topaz and then run or compiled by the Topaz side, so this is borrowing a toolchain rather than mixing the languages.

  3. Topaz virtual machine. An exact, separately installed Topaz 5.11 virtual machine on macOS ARM64. It is not built into the Native binary. You install it separately and pass its absolute product location when a command needs it.

  4. Ahead-of-time build, or AOT. An executable built ahead of time from your program, which then needs no source to run. Building one requires the exact installed Topaz compiler and a Rust tool directory. The installed product then runs without any source tree.

Every route implements the same Lispex language rather than a separate dialect. These routes are designed to preserve the same meaning. Comparison commands check whether their observations agree for one exact request, but one agreement is not a proof that every program behaves identically everywhere.

Two honesty rules

The routes are made trustworthy by two rules that are easy to state.

No discovery during execution. Execution, inventory, diagnosis, and comparison commands do not search your PATH, checkout, environment, or the network. An external route participates only when you provide its exact location. The separate routes fetch command can acquire one exact official companion, but fetching neither selects nor runs it.

No fallback. If you request a route and it fails or is missing, the run stops with an error. It never quietly switches to another route. A result labelled Topaz VM was produced by the Topaz virtual machine or not produced at all.

The two rules protect the same thing. When a run succeeds, you know exactly which route produced the answer.

Checking that routes agree

After installing the exact Topaz virtual machine and building a matching ahead-of-time product, Native can run all four routes for one exact request and write one diagnostic receipt, a report file it never writes over an existing file.

SH
lispex compare-routes \
  --topaz-vm /absolute/tools/lispex-topaz-vm/product \
  --aot-product /absolute/products/rule-aot \
  --receipt route-comparison.json \
  rule.lspx

This command requires both exact external products. If a product is missing or mismatched, the command fails instead of shrinking the comparison to whichever routes happen to be available. The receipt reports the four observations. Agreement is evidence for that source, input, product set, and resource boundary. It is not a proof that the routes are equivalent everywhere, and the receipt never claims otherwise.

Try this

Suppose a teammate's script requests the Topaz virtual machine route, and the machine it runs on has no Topaz virtual machine installed. Predict what happens before opening the answer.

Show answer

The run fails with an error naming the missing route. It does not fall back to the built-in interpreter, so it cannot produce an answer with a wrong label. The fix is explicit. Either install the exact companion and pass its location, or change the script to request a route the machine actually has.

Ready to move on when

You are ready when you can name the four routes, state which one runs with no setup, and explain both honesty rules in your own words.

When you want to choose a route for real work, continue with Choosing Where to Run. When you want to install a companion, follow Install an Optional Extra Engine.