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.
Absolutely! I didn’t even read most of the source.
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).
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.
I prefer an unethical sausage to no sausage.
Yes, tokens don’t grow on trees and that’s what I spend any funding on.
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 asmiricl-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.
- 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.dyliborwasmtime.dlldiscoverable by your system’s library loader; useLD_LIBRARY_PATHon Linux,DYLD_LIBRARY_PATHon macOS orPATHon 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
rlwrapfor 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 (
CHROMIUMselects 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.
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-asdfKeep 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 buildjust 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.
Start a local terminal REPL with either command:
node miricl.js miricl.wasm
wasmtime run -W stack-switching=y -S p3=y miricl-repl.wasmThese commands evaluate locally and open no network listeners.
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-serverOpen 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.
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-serverOpen 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.
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.
Build the optional ASDF/UIOP library from the pinned upstream Git submodule:
just asdf-init
just build-asdfThis 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.
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.wasmPlace 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.
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.
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)'); // 42The 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.
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.wasmRepeat --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.wasmAdd --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.wasmThe 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.
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.
- Released under the GNU Lesser General Public License
- Developer Certificate of Origin
- Source for README photo