Systems (asdf)

The asdf package provides a limited, API-compatible subset of ASDF, the Common Lisp build facility: you describe a multi-file project once in a NAME.asd file with asdf:defsystem, and asdf:load-system loads the files in dependency order — on every backend. Real ASDF is not ported (it depends on CLOS, the condition system and the pathname API, none of which exist here); instead, .asd files are parsed as plain data and the supported defsystem subset drives the same machinery as load/require. A .asd that stays inside the subset works unchanged.

A complete project

app/
  my-app.asd
  package.lisp
  main.lisp
  run.lisp
registry/base/
  base.asd
  base.lisp

;; app/my-app.asd
(defsystem :my-app
  :version "0.1.0"
  :depends-on (:base)
  :serial t
  :components ((:file "package")
               (:file "main")))

;; app/package.lisp
(defpackage :my-app (:use :cl) (:export :run))

;; app/main.lisp
(in-package :my-app)
(defun run () (print (base:double 21)))

;; app/run.lisp
(asdf:load-system :my-app)
(my-app:run)

Run or compile the entry file; the same directive works on all four backends:

rontolisp app/run.lisp --system-path registry/base                 # interpret
rontolisp app/run.lisp --system-path registry/base -o Prog.class   # JVM
rontolisp app/run.lisp --system-path registry/base -o app.wasm     # WASM

my-app.asd is found next to run.lisp; the :base dependency system is found through --system-path. On the compile path the whole system (its dependency first) is spliced into the program at compile time, exactly like the compile-time load include, so the JVM and WASM compilers see every defun natively.

The system search path

asdf:load-system looks for NAME.asd in, in order:

1. the directory of the file doing the load-system (like load),
2. the directories given with --system-path (several can be joined with the platform path separator, like PATH),
3. the directories in the RONTOLISP_SOURCE_REGISTRY environment variable (same format).

A dependency system's .asd is searched starting from the depending system's directory, so sibling systems in one registry directory find each other.

Downloading with quickload

To skip the manual download, ql:quickload fetches a system (and its dependencies) from the real Quicklisp distribution and then loads it through exactly the machinery above:

$ rontolisp
CL-USER> (ql:quickload "split-sequence")
(split-sequence)
CL-USER> (split-sequence:split-sequence #\, "a,b,c")
("a" "b" "c")

The Quicklisp dist metadata drives the download (systems.txt for dependency resolution, releases.txt for the tarball URLs); each release is extracted and cached under ~/.rontolisp/quicklisp/ (override with RONTOLISP_QUICKLISP_HOME), so a repeat quickload does no network I/O. The download runs at interpret time or compile time (Java-side): a compiled program has the sources spliced in and never fetches at runtime, so ql:quickload works on all four backends. Because loading still goes through the asdf subset, the same limitations apply — a downloaded library only loads if its sources stay inside the supported subset below.

Adding a dist (Ultralisp)

Quicklisp's dist format is spoken by more than one distribution, and Ultralisp — rebuilt every few minutes, so a library lands in it the day it is published — is the usual second one. It is opt-in: a program installs it with ql-dist:install-dist, the same call real Quicklisp takes,

$ rontolisp
CL-USER> (ql-dist:install-dist "http://dist.ultralisp.org/" :prompt nil)
"ultralisp"
CL-USER> (ql:quickload "circular-buffer")
(circular-buffer)

and an invocation with nowhere to put a form (rontolisp test SYSTEM, a build script that must not edit the sources it compiles) names it on the command line instead — --dist ultralisp, several comma-separated, or the RONTOLISP_DISTS environment variable. Either channel also takes the URL of any other Quicklisp-format distinfo.

The dists are searched in installation order, per system: ql:quickload takes each system — and each dependency — from the first dist that lists it, so adding one supplies the names Quicklisp does not have and changes where nothing else comes from. Quicklisp is installed first unless it is named explicitly, so --dist ultralisp,quicklisp is how Ultralisp's copy of a library both dists carry wins. A dist's index is downloaded only when a lookup actually reaches it, and each dist caches under its own ~/.rontolisp/<dist>/ (RONTOLISP_DIST_HOME overrides the base; RONTOLISP_QUICKLISP_HOME still overrides the quicklisp one). Because the index is then cached forever, ql:update-dist is what makes a fast-moving dist worth having:

$ rontolisp -e '(ql:update-dist "ultralisp")'

Everything else is unchanged: the download happens at interpret time or compile time, so an installed dist works the same on all four backends, and a downloaded library still has to stay inside the supported subset below.

What is (and is not) supported

• .asd files are parsed as data: defsystem (bare or asdf:-qualified), in-package/defpackage forms (skipped), register-system-packages forms (which record "this package lives in that system" — read when a package-inferred system turns a defpackage dependency into a system name, and otherwise inert, since a package is found through its own defpackage), and top-level defparameters of pure literal/conditional values (evaluated into a parse-time environment) may appear. #+/#- feature conditionals work (evaluated against the target backend's features, see Data Types), a #. read-time-eval form is resolved where its value is used: in a clause that decides what gets loaded it is resolved against those defparameters (the (:file #.*string-file*) idiom), and an unresolvable one is an error naming the file and the clause; in ignored metadata (:long-description, :version, :perform, …) and at top level (an ASDF version guard) it is dropped unevaluated and unremarked. A :depends-on entry may be (:feature EXPR DEP), contributing its dependency only when the feature expression holds, or (:version NAME "1.2.3"), resolving to the plain dependency (the version constraint is not checked — the :version option is ignored metadata here, so there is nothing to check against). A top-level (defmethod perform ...) hook is tolerated and ignored (there is no operate machinery for it to run on; any other method name is an error), and a top-level defclass whose superclasses are documentation component classes (ASDF's doc-file, or one declared earlier in the same file) declares its name as a component type whose entries participate in ordering but contribute no source, like :static-file — :doc-file and :html-file work without a defclass. Any other top-level form is an error naming the file.

• A .asd may announce features: a top-level (eval-when (:load-toplevel :execute) (pushnew :my-feature *features*)) (or a bare pushnew/push) before a defsystem declares that feature for every system defined after it in the file — the same effect as writing :rontolisp-features (:my-feature) on those systems. The declaration reaches the system's own :if-feature / (:feature ...) clauses and the reading of its component files — carrying the announcement out of the .asd, which is the half the reader cannot do for itself. (A #+/#- in the same .asd sees the push too, but through the reader's own handling of a source's announcement — see Data Types.) It does not reach a dependency, which declares its own. An eval-when whose situations are only (:compile-toplevel) is inert (ASDF loads a .asd, it never compiles one), and any other form inside the eval-when is an error naming it.

• defsystem supports the metadata options (ignored, except that a plain-string :version is read back by asdf:component-version), :depends-on, :defsystem-depends-on (systems real ASDF loads while the .asd is read: located the same way, loaded before :depends-on, never a sideway dependency of the system, and a built-in shim named there announces its features to this system — ("trivial-features") puts :unix and :little-endian in force for its clauses and component files), :serial, :pathname (a literal directory prefixed to every component, so a system whose sources live in src/ can name them bare) and :components with :file/:module/:static-file entries; a component may carry :if-feature expr, which drops the component's files when the feature expression does not hold (how libraries gate CLOS-only files behind (:or :sbcl ...)) while keeping its place in the dependency order. The test-op wiring options are the one op with machinery behind them: :in-order-to ((test-op (test-op ...))) and :perform (test-op (o c) ...) are recorded and driven by asdf:test-system (any other operation, a qualified test-op :after method, or a #. in the body stays tolerated and ignored — there is still no general operate machinery). A :version value may be any literal form including ASDF's (:read-file-form ...) indirection (never inspected — only a plain string is recorded). Anything else (:around-compile, ...) is an error naming the clause.

• :class :package-inferred-system is supported — the style ningle, rove and array-operations use. Such a system has no :components at all: a sub-system name is a file path under the system's directory (my-lib/main is main.lisp, my-lib/util/text is util/text.lisp, both below :pathname when the system has one), and that file's own defpackage names its dependencies — every package in :use, :mix, :reexport, :use-reexport and :mix-reexport, plus the first argument of each :import-from / :shadowing-import-from. A package name becomes a system name: what a register-system-packages form declared, otherwise the downcased package name itself (cl and friends drop out). Only the forms up to the first package definition form of each file are read, so the common (in-package #:cl-user) header before the defpackage is fine; a file with no defpackage/uiop:define-package at all is an error. No other :class is supported, and a package-inferred system that also lists :components is an error.

• Loading a system twice is a no-op; circular :depends-on chains are detected and reported — including one written as a cycle between two sub-systems' defpackage forms.

• The compile path requires a literal, top-level (asdf:load-system NAME); the interpreter also accepts a computed name at runtime. Both accept and ignore trailing keyword options (:verbose nil, :force t, :silent t), which real libraries pass when they load a system at runtime. A nested or computed load-system/ql:quickload in a compiled program answers nil when the system was already spliced and signals otherwise — nothing can be loaded at run time there.

• The component metaobjects are real at run time. asdf:find-system answers a memoized CLOS instance per system (eq across calls) over real classes — asdf:component, asdf:child-component/asdf:parent-component, asdf:module, asdf:system, asdf:package-inferred-system, asdf:source-file, asdf:cl-source-file, asdf:static-file — so typep, typecase and defmethod specializers over them work on every backend. The readers asdf:component-name, asdf:component-version (the declared :version string, when it was written as a plain string), asdf:component-pathname, asdf:component-children (one cl-source-file per component file, in load order), asdf:component-sideway-dependencies, asdf:component-parent and asdf:component-system walk the model; asdf:registered-systems lists every registered name, and asdf:*user-cache* is external and nil (there is no fasl cache). This is the component model rove's system-driven test runner reads.

• asdf:test-system runs the recorded test-op wiring. asdf:test-system loads the system, follows its :in-order-to test-op chain, and runs each recorded :perform (test-op (o c) ...) body with the component bound to the system metaobject. On the compile paths a literal top-level call splices the test systems too.

• Compiling tree-shakes the system. A function, variable or constant a loaded system defines but your program never reaches — following names through the source, including quoted symbols and whole string literals — is left out of the .class/.wasm — classes, generic functions, methods, conditions and structures included (a method also leaves when no reachable code can create an instance it applies to). Compile with --no-prune (or --dynamic) to keep every definition; see Compiling to the JVM for the one consequence.

• The load-context variables hold the file being loaded, on every backend. While a file is being loaded, *load-pathname* holds the path load was called with and *load-truename* the path it resolved to; the enclosing file's values come back when it finishes, and outside a load both are nil — read at top level or from a function the load defined and your program calls later. A component is loaded by its resolved path, so both variables hold what asdf:component-pathname answers for it, which is what lets a test framework correlate the definitions of a file with the system that owns it. This works the same on the compile backends: a spliced file's forms are compiled with its own load context, because nothing is being loaded at run time there for them to read otherwise. *compile-file-pathname* and *compile-file-truename* are always nil — there is no compile-file here. Libraries use the (or *compile-file-truename* *load-truename*) idiom to find data files beside their own sources. That works at read time too: a #. form — the way that idiom is normally spelled, so the file is read while the source is being read — sees its own file's load context on every backend, so a library can bake in a data file that ships next to it.

Built-in shim systems

Some Quicklisp libraries depend on per-implementation portability layers that cannot know rontolisp from their side. rontolisp ships those as built-in ASDF systems: asdf:load-system/ql:quickload (and a :depends-on from a real library) resolve the name to a bundled shim instead of downloading it.

The shims are deliberately thin: they satisfy what the loadable libraries actually call, not the full upstream APIs.

What can I actually load?

The real-world libraries below load unmodified today. The Backends column says where each one is verified — "all four" means the interpreter, the JVM, WASM Preview 1 and --component. Notes covers what is special about the load and what does not work.

The size opt-in: tiny-routes/lite

(ql:quickload "tiny-routes/lite") loads the same tiny-routes tree with one component substituted — path-template.lisp, whose matcher upstream is a cl-ppcre scanner — and the :cl-ppcre dependency dropped with it. It exists because routing keeps the regex engine live: a route template compiles to a scanner when the route is built, so in a compiled module no amount of tree-shaking can remove cl-ppcre, and on a size-limited target that is most of the module — the routed Worker example measures 974,530 B raw with the full system and 408,448 B with the lite one, same routes, same answers, request for request.

The substitution never changes what a template matches — it matches identically to the full system, or it refuses loudly when the route is built:

• Accepted: templates made of literal characters and :name tokens — a token is : followed by a letter or _, continuing over letters, digits, _ and -, anywhere in the template: /users/:id, /files/v:version, /pair/:a/:b. Within this subset the lite matcher reproduces the full system's semantics exactly, greedy backtracking and upstream's greedy token-name scan included (in /a/:x-:y the first token is named x-); the two engines are pinned template-for-template by the test suite.
• Refused at route-build time, with an error naming the escape: a template containing any regex metacharacter — . \ [ ] ( ) { } | ^ $ * + ? — and every :regex t template. (A template with no :name token is never a regex upstream either — it is compared with string= — so metacharacters there are fine on both systems.)

Plain (ql:quickload "tiny-routes") is untouched — the verbatim library, cl-ppcre included — and the two systems refuse to load into one program, in either order (whichever loaded last would silently redefine the matcher). tiny-routes/lite is not in the Quicklisp index; the name downloads the tiny-routes release and resolves against its .asd.

cl-ppcre's load drove the widest feature batch so far — local (declare (special ...)), CLOS slot accessors as generics, initialize-instance :after, &environment + get-setf-expansion, psetf, (setf (subseq ...)), subst/search/copy-tree and the descending/case-insensitive character comparisons.

uax-15's load drove the second widest: compile-time folding of the ASDF/UIOP pathname primitives, inlining a bundled data file read with with-open-file into the artifact, a per-clause rewrite of the LOOP macro, and the UTF-8 byte model behind WASM GC strings.

alexandria's is the batch every other library inherits, because everything above that has dependencies depends on it: &whole in defmacro/destructuring-bind, a destructuring pattern after &rest/&body (if-let), lambda-list-keywords, do-external-symbols, intern with a package designator, the hash-table introspection readers (hash-table-test/-size/-rehash-size/-rehash-threshold), mismatch, arrayp, with-open-stream and #'open as a first-class value — plus, for mappend, #'mapcar as a value over more than one list.

Runnable demos for sixteen of them — with the per-backend commands and expected output — live in examples/asdf/.

A library qualifies today roughly when it stays inside: plain defun/defmacro/defpackage code, loop, multiple-value-bind over values-tailed functions, check-type/etypecase with the supported type specifiers, declarations (parsed no-ops, deftype included), the CLOS static subset (defclass/defgeneric/defmethod/make-instance/slot-value with single dispatch, plus (defun (setf name) ...) setf functions), the condition and restart system (define-condition/handler-case/handler-bind/restart-case/ invoke-restart), return-from, and dynamic (special) variable binding (let/let* over a defvar special). Libraries built on the full metaobject protocol or the interactive debugger (break, *debugger-hook*) do not load yet (see Unsupported CL Features). For anything else, the practical use is structuring your own multi-file rontolisp projects — with .asd files that real ASDF can read too.