Skip to content
ak-coramPublic

About

Common Lisp for Wasm runtimes

Topics

Resources

Stars

12 stars

Watchers

1 watching

Forks

Latest commit

 

History

58 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

miricl (미리CL)

Build Status

Q&A

What is miricl?

Miricl is a Common Lisp implementation for browsers, Node.js and Wasmtime, with an interactive interpreter, a self-hosted native Wasm compiler, and a whole-program optimizer. Try the browser REPL, Game of Life, Maxima, FriCAS, ACL2, Coalton or McCLIM demonstrations. Compiler and prover statistics cover the runtime and application builds.

The runtime implements CLOS, conditions and restarts, packages, streams, ASDF/UIOP integration, JavaScript interop and cooperative green threads.

Is it slop?

Absolutely! I didn’t even read most of the source.

Why?

As usual this project intends to fill a void: the current interpreter is a fraction of the size of ECL compiled with Emscripten to Wasm. This enables deployment of Common Lisp programs in environments where size can be an issue (such as websites).

How?

I’ve set up a cage fighting match between an LLM and ansi-test which lasted for days. You can view the results here. Now the cage fight endlessly continues with a few large applications (see the submodules in this repository) and image sizes, performance and snapshot sizes keep incrementally improving.

Don’t you care how the sausage is made?

I prefer an unethical sausage to no sausage.

Are you asking for funding?

Yes, tokens don’t grow on trees and that’s what I spend any funding on.

Usage

Distribution

The miricl-runtime build artifact includes:

  • miricl.js: browser adapter and Node terminal command.
  • miricl-cold.wasm: interpreter and source compiler for bootstrap work.
  • miricl-interpreter.wasm: interpreter with minimal compilation, without the optimizing Wasm compiler. Also published as miricl-interpreter.
  • miricl.wasm: import-free interpreter with the size-optimized, bootstrapped native compiler ready at startup, for browsers and Node.
  • miricl-repl.wasm: Wasmtime terminal command and precompiled compiler for Node.
  • miricl-asdf.wasm: optional ASDF/UIOP library.

Keep these files together. Node and Wasmtime commands below work without a MIRICL checkout; browser applications import miricl.js directly. ASDF is needed for development and bundling, but ordinary production applications only need the adapter, interpreter and their application FASL.

Building from source

Prerequisites

  • A host Common Lisp implementation and Quicklisp. The commands below use SBCL and expect Quicklisp at ~/quicklisp/setup.lisp.
  • The Wasmtime C API shared library, version 50 (CI uses 50.0.1). Install the C API library separately from the Wasmtime CLI. Make libwasmtime.so, libwasmtime.dylib or wasmtime.dll discoverable by your system’s library loader; use LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS or PATH on Windows for a custom location.
  • Git and just for the checkout and build commands.
  • Node.js 26 (used by CI) for the Node REPL and size reports.
  • The Wasmtime 50 CLI and rlwrap for the terminal examples below.
  • A browser supporting WasmGC and Wasm exception handling. Async filesystem access and green threads also require JavaScript Promise Integration (JSPI). Browser tests use Chromium (CHROMIUM selects the executable).
  • Native stack switching and WASI 0.3 are currently enabled explicitly for the Wasmtime command. The WASI stack-switching adapter does not support ARM yet.

Build

Run the following from a terminal:

git -c core.autocrlf=false clone --recurse-submodules https://github.com/ak-coram/miricl.git
cd miricl
just build-asdf

Keep LF line endings in Lisp sources, including submodules. On Windows, CRLF conversion can break multiline FORMAT strings in upstream ASDF.

This produces miricl.wasm, the import-free interpreter with its compiler already compiled to native Wasm; miricl-cold.wasm, the cold bootstrap image; miricl-interpreter.wasm, the smaller compiler-free scripting image; and miricl-repl.wasm, the WASI 0.3 terminal REPL and development command. The adapter and WASI command provide the development bridge. It also writes miricl.js and the optional miricl-asdf.wasm.

The default miricl.wasm avoids first-use compiler bootstrapping. Its native compiler and runtime receive the shared size optimizations during the build; no external optimizer is required. Its raw size budget is below 1 MiB (1,048,576 bytes). Browser application builds also package images as .gz files using Node’s maximum gzip level. The adapter uses native browser decompression, so static hosts need no Content-Encoding configuration. The same generic instruction and module passes apply to native application bundles. Optimization includes constant folding, dead-code removal, local simplification and module compaction; it does not require application specific compiler rules. Quicklisp loads the Lisp dependencies automatically. If your Quicklisp setup file is elsewhere, set QUICKLISP_SETUP when building:

QUICKLISP_SETUP=/path/to/quicklisp/setup.lisp just build

Tests

just test runs compact soundness, implementation and optimization checks against existing build artifacts. Rebuild explicitly with just build when the runtime or compiler changes. just test-implementation-wasi also exercises the WASI adapter. Set MIRICL_BUILD_DIR to test a separate build directory.

These checks cover compiler input validation and recovery, optimization soundness, green threads, Wasm integration and virtual filesystems. just test-optimizations checks observable compiler capabilities such as deep tail calls on Node. WASI cannot load generated code at runtime and is exempt from all compiler optimization tests. ANSI language conformance stays in just ansi-full and just full-ansi-compiler; application-specific checks keep their separate test-* commands.

Terminal REPL

Start a local terminal REPL with either command:

node miricl.js miricl.wasm
wasmtime run -W stack-switching=y -S p3=y miricl-repl.wasm

These commands evaluate locally and open no network listeners.

A small HTML page

Save this as hello.html beside the distribution files:

<!doctype html>
<meta charset="utf-8">
<title>Common Lisp hello world</title>

<script type="text/x-common-lisp">
  (js:invoke (js:global "console") "log" "Hello, world from Common Lisp!")
</script>

<script type="module">
  import {Miricl} from "./miricl.js";

  const bytes = await (await fetch("./miricl.wasm")).arrayBuffer();
  const lisp = await Miricl.instantiate(bytes);
  for (const script of document.querySelectorAll('script[type="text/x-common-lisp"]')) {
    lisp.evaluate(script.textContent, {eof: true});
  }
</script>

The adapter enables JS interop automatically. The loop evaluates every text/x-common-lisp script in document order, sharing one interpreter, so later scripts can use definitions from earlier ones.

Serve the current directory so the browser can load the JavaScript module and Wasm file:

node miricl.js miricl.wasm --dev-server

Open hello.html and check the browser’s developer console for Hello, world from Common Lisp!. This calls the browser’s console.log from Common Lisp via js:invoke.

Development mode

Save this as dev.html beside the distribution files:

<!doctype html>
<meta charset="utf-8">
<title>Common Lisp development</title>
<script type="module">
  import {Miricl} from "./miricl.js";

  const bytes = await (await fetch("./miricl.wasm")).arrayBuffer();
  const lisp = await Miricl.instantiate(bytes, {dev: true});
</script>

Start the terminal browser REPL and serve the current directory with either Node or Wasmtime. These commands enable HTTP and WebSocket; the TCP REPL listener is disabled unless --repl-bridge is also supplied:

node miricl.js miricl.wasm --dev-server

wasmtime run -W stack-switching=y -S p3=y -S inherit-network=y \
  --dir .::. miricl-repl.wasm --dev-server

Open dev.html, then evaluate this in the terminal to show a browser alert:

(js:invoke (js:global "window") "alert" "Hello, world!")

The bridge forwards forms to the browser and displays its output; the browser selects compilation or interpretation using miricl-compiler:*compile-evaluations*. The precompiled image defaults to native compilation. Connection status appears in the terminal. Use --browser-repl instead of --dev-server if files are served elsewhere. Omit dev in production to disable the adapter and connection. Enter :quit to stop the host command and detach the development adapter.

Development mode reads host files through the dev server automatically. The served directory appears as / to Lisp; load, open, directory and file timestamps work through evaluateAsync and the terminal REPL. Writes and compiled files stay in the browser. Use {dev: {filesystem: false}} to disable file access, or set filesystem to the dev server’s HTTP URL when serving the webapp elsewhere.

Ports default to HTTP 8000, WebSocket 4006 and TCP 4005 (when enabled); override them with --http-port, --websocket-port and --tcp-port. For a custom WebSocket port, use {dev: {url: "ws://127.0.0.1:PORT/repl"}}. Enter :quit in the terminal to stop the development server, including while waiting for a browser or after it disconnects. This also works from the TCP REPL.

Emacs

Add --repl-bridge to either command to enable the TCP REPL on 127.0.0.1:4005. Evaluate this in your Lisp source buffer to connect directly, keeping the REPL selection buffer-local:

(progn
  (require 'inf-lisp)
  (setq-local inferior-lisp-buffer "*miricl*")
  (pop-to-buffer (make-comint "miricl" '("127.0.0.1" . 4005)))
  (inferior-lisp-mode))

This provides an inferior Lisp buffer and source evaluation commands. The buffer shows browser connection status and stays connected across browser reloads. TCP submissions and responses also appear in the terminal. Interrupts and Swank/Slynk are not implemented.

ASDF

Build the optional ASDF/UIOP library from the pinned upstream Git submodule:

just asdf-init
just build-asdf

This applies patches/asdf/series to a source copy under build/asdf/source/ and compiles it to miricl-asdf.wasm. The submodule stays clean; a failed patch stops the build. The distribution already includes this optional file; ASDF is not included in the base interpreter images.

With the application directory served by the dev server and {dev: true} in the browser, load ASDF and your application’s system from the terminal:

(load "/miricl-asdf.wasm")
(asdf:load-asd #P"/app/app.asd")
(asdf:load-system "app")

Use asdf:initialize-source-registry to discover systems under a directory. Host source edits are visible on subsequent loads; compiled .wasm FASLs stay in memory and can be loaded in another interpreter without ASDF. Outside dev mode, supply files explicitly with mountFile. Run just test-asdf to check the port and just test-browser-dev for browser access through both servers.

Production bundles

Select ASDF’s monolithic bundle operation to include the system and its dependencies in one loadable file:

(asdf:defsystem "app"
  :depends-on ("some-library")
  :serial t
  :components ((:file "package") (:file "app"))
  :build-operation "monolithic-compile-bundle-op"
  :build-pathname #P"dist/app.wasm")

(asdf:make "app")

The shipped terminal REPLs can build the system without a browser:

node miricl.js miricl.wasm --bundle app --output dist/app.wasm
wasmtime run -W stack-switching=y -S p3=y --dir . miricl-repl.wasm --bundle app --output dist/app.wasm

Place miricl-asdf.wasm beside the application (or in runtime/) and optionally provide systems.lisp to configure its source registry and output translations. Wasmtime also needs named preopens for directory symlinks outside the root. Builds use a fresh interpreter, write the requested FASL, then exit. No entry point is called, and no adapter, interpreter or other assets are copied. ASDF may load earlier components while compiling later ones; keep browser side effects in startup code or use eval-when to control evaluation.

The same Lisp operation is available in a terminal REPL:

(miricl-bundle:dump-system "app" :output "dist/app.wasm")

With :save nil, the bundle remains in the interpreter’s virtual filesystem; await lisp.readFile("/dist/app.wasm") retrieves its bytes. The adapter and interpreter are separate distribution files that can be referenced or symlinked into applications.

In production, mount and load only the bundle, then start the application:

const lisp = await Miricl.instantiate(interpreterBytes);
lisp.mountFile("/app.wasm", await (await fetch("./app.wasm")).arrayBuffer());
await lisp.evaluateAsync('(load "/app.wasm") (app:start)', {eof: true});

ASDF and source files are not needed at runtime unless the application itself uses them. If needed, mount and load miricl-asdf.wasm explicitly before the application bundle. Bundling does not add ASDF/UIOP automatically. Bundles retain interpreter code and load-time initialization; they are not standalone executables or whole-program optimized Wasm. Declare and supply non-Lisp resources separately. compile-bundle-op bundles only one system; monolithic-compile-bundle-op includes its dependencies.

Saved images

miricl-core:save-image writes the current Lisp state to a Wasm file in the virtual filesystem. Its optional :toplevel argument accepts a zero-argument function or its symbol. Miricl calls it after restore.

(miricl-core:save-image "/app-image.wasm" :toplevel #'app:start)

Retrieve the image with await lisp.readFile("/app-image.wasm") and pass its bytes to Miricl.instantiate in a browser or in Node. The image includes the runtime, Lisp definitions, data, and virtual files. Host imports are supplied when opening the image. Save from a single Lisp thread with no live JavaScript values in the saved data.

Snapshots preserve each function’s current representation, including compact HIR, its debug metadata and shared closure cells. They do not convert source functions to HIR. The snapshot object graph preserves identity and cycles; octet-valued storage arrays are packed as bytes, and zero or NIL object fields are omitted using presence masks. Repeated type and field-mask headers share compact descriptors without merging the objects themselves. Object references use signed distances from their containing object’s ID. Headers also share repeated low bits of leading integer fields, preserving complete tag words and identity hashes. Wider integers and exact floating-point bits, including negative zero, are retained.

Compiler

The miricl-interpreter.wasm variant performs minimal compilation through the shared HIR frontend. compile expands macros and resolves load-time values; its results satisfy compiled-function-p and execute in the interpreter. compile-file preserves compile-time and load-time phases and writes portable FASLs, including literal identities and make-load-form recipes. File compilation emits executable HIR, with an internal source stepping fallback for DEBUG 3. Native FASLs also load normally. The image omits optimization, Wasm generation and compiler bootstrap. disassemble prints HIR instructions, capture names and packed instruction size, including for functions loaded from FASLs. Existing source closures keep their lexical cells through the compact source compiler; DEBUG 3 retains source stepping. Setting miricl-compiler:*compile-evaluations* has no effect in this image, and block-compilation directives are ignored.

Interpreter-mode ANSI tests use this compiler-free image, including the just ansi and just ansi-full commands. Compiler-mode ANSI tests use miricl.wasm and verify native compilation separately.

The other runtime images include the compiler, which shares the interpreter’s Lisp objects:

miricl-compiler:*compile-evaluations* selects the default for local REPL input, eval, and source load. It defaults to nil in miricl-cold.wasm and the WASI command, and t in miricl.wasm. A true value compiles expressions and function definitions to native Wasm. Literals and environment definitions such as defmacro and defclass retain their interpreter handling. Loading an existing FASL executes its stored code directly. Native compilation errors are reported; evaluation does not retry execution through the interpreter. To interpret a form explicitly, use a dynamic binding:

(let ((miricl-compiler:*compile-evaluations* nil))
  (eval '(some-form)))

Use setq to change the default for subsequent inputs. Enabling it in the ordinary image bootstraps the compiler on first compilation. Explicit compile-native calls work independently of this default. Development REPL input follows the browser’s setting, just like local input.

const lisp = await Miricl.instantiate(interpreterBytes);
lisp.evaluate("(defparameter *f* (miricl-compiler:compile-native '(lambda (x) (+ x 2))))");
lisp.evaluate('(funcall *f* 40)'); // 42

The browser image carries compact compiler source; the first compilation self-compiles the frontend and emitter once and reuses their native functions. The REPL deliverable includes the self-compiled compiler for Node and Wasmtime. Development REPL expressions and defun bodies compile in the browser when its evaluation policy is enabled, preserving its macros, objects and REPL history. The server only forwards forms and output. Forms that establish packages, macros, classes and methods still use the browser evaluator. The native backend currently supports a subset of Common Lisp. Browser and Node adapters can instantiate generated Wasm; the WASI compiler can emit and optimize files. ASDF remains a separate, explicitly loaded library.

File compilation supports SBCL-style block compilation. Pass :block-compile t to compile a file as one block, or :block-compile :specified to delimit blocks with (declaim (miricl-compiler:start-block entry ...)) and (declaim (miricl-compiler:end-block)). With no named entries, every function receives a global definition. :entry-points selects the global definitions for a whole-file block. Calls within a block use its lexical function bindings, so later global redefinitions do not change those calls. The interpreter ignores the boundary declarations. The default, miricl-compiler:*block-compile-default*, is nil.

Cold compiler bootstrap uses small blocks while retaining the progressive installation order. Calls to kernels outside each block remain global. The precompiled compiler image already compiles its kernels together.

Whole-program optimization

The optimizer removes unreachable definitions and constants. Specify the production entry points:

node miricl.js --optimize app --entry APP:START --output dist/app.wasm --report dist/retention.txt
wasmtime run -W stack-switching=y -S p3=y --dir . miricl-repl.wasm --optimize app --entry APP:START --output dist/app.wasm

Repeat --entry for other public functions and --keep PACKAGE:NAME for definitions accessed dynamically. JavaScript callbacks referenced by Lisp are retained automatically. Package exports alone do not retain definitions. Initialization effects and potentially applicable methods are preserved; unbounded reflective lookup conservatively retains the supplied program. The report explains each retained or removed definition. FASL units without compiler metadata prevent pruning. No entry point is invoked by the optimizer.

Pass --no-strip with --optimize to retain all definitions while compacting the FASL. Entry points are optional in this mode:

node miricl.js --optimize app --no-strip --output dist/app.wasm
wasmtime run -W stack-switching=y -S p3=y --dir . miricl-repl.wasm --optimize app --no-strip --output dist/app.wasm

Add --native to compile the retained initializers and function bodies to WASM for the browser or Node adapter. The application loads without starting its Lisp compiler. The build can still run under Wasmtime:

wasmtime run -W stack-switching=y -S p3=y --dir . miricl-repl.wasm --optimize app --native --entry APP:START --output dist/app.wasm

The corresponding Lisp API is miricl-compiler:optimize-system with :entry-points, :keep, :output, :report, :native and :save options. Use :strip nil to disable definition stripping. Existing FASLs can be compiled with miricl-compiler:compile-native-bundle after loading their system in the build environment. Conversion does not rerun their top-level initializers. Native bundles require a host that can instantiate generated WASM modules; ordinary FASLs continue to load in Wasmtime as well. miricl-compiler:shake-file operates on an existing bundle without executing it and is also available to the host Common Lisp system. See compiler architecture.

Game of Life

The Game of Life example uses the FSet 2 API, an ASDF application bundle, and a browser/terminal development REPL. Run just setup-game-of-life, then cd game-of-life && just dev. Development loads miricl.wasm in the browser, with the WASI command forwarding terminal input and serving files. Production builds run the precompiled compiler image in Node. just build writes build/index.html, miricl.js, miricl.wasm and game-of-life.wasm as separate files. Play the production build.

Run just benchmark-game-of-life from the repository root to measure production sizes and fresh application loading; results are in game-of-life/build/sizes.json.

The TODO source demonstrates lightweight scripting in the browser: DOM access, events, callbacks and persistence through JS interop. Its standalone page embeds the smaller interpreter-only image, without the compiler. See the justfile for more build and test targets.

Legal

About

Common Lisp for Wasm runtimes

Topics

Resources

Stars

12 stars

Watchers

1 watching

Forks

Sponsor this project

Contributors

Languages