Where Your Program Runs

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

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 implements the complete language profile.

The four routes

The browser Playground, npm package, and downloadable Native program are Lispex products. A route is the engine that runs your program inside a product. The Playground and npm package use the tree route. Native can use all four routes.

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 Topaz 5.11 virtual machine installed as a separate macOS ARM64 product. You pass its absolute product location to the Native command.

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 record their observations for one exact request together with the source, input, products, and resource values.

Two route identity rules

Two rules preserve the producer identity of every route result.

Use the exact location. Execution, inventory, diagnosis, and comparison commands use the external product location you provide. The separate routes fetch command acquires one exact official companion, and route selection happens when you supply that installed product.

Preserve the selected engine. Every run records the requested route in its result or error. A Topaz VM result carries the exact Topaz virtual-machine product identity.

Together these rules identify 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.

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 takes both exact external products and reports all four observations. Agreement records the result for that source, input, product set, and resource profile. The receipt names each field directly.

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.

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.