ASDF is a tool for specifying how systems of Common Lisp software are made up of components (sub-systems and files), and how to operate on these components in the right order so that they can be compiled, loaded, tested, etc.
How to define a test operation for a system
(in-package #:asdf-user) (defsystem #:foo :components ((:file "foo")) :in-order-to ((asdf:test-op (asdf:load-op :foo))) :perform (asdf:test-op (o c) (uiop:symbol-call :foo-tests 'run-tests))) (defsystem #:foo-tests :name "foo-test" :components ((:file "tests"))) ;; Afterwards to run the tests we type in the REPL (asdf:test-system :foo)
- We are assuming that the system :foo-tests defines a package named "FOO-TESTS"
run-testsis the entry point for the test runner
- uoip:symbol-call allows as to define a method that calls a function that hasn't been read yet. The package the function is defined in doesn't exist when we define the system
In what package should I define my ASDF system?
ASDF provides the package
ASDF-USER for developers to define their packages in.
Simple ASDF system with a flat directory structure
Consider this simple project with a flat directory structure:
example |-- example.asd |-- functions.lisp |-- main.lisp |-- packages.lisp `-- tools.lisp
example.asd file is really just another Lisp file with little more than an ASDF-specific function call. Assuming your project depends on the
clsql systems, its contents can be something like this:
(asdf:defsystem :example :description "a simple example project" :version "1.0" :author "TheAuthor" :depends-on (:clsql :drakma) :components ((:file "packages") (:file "tools" :depends-on ("packages")) (:file "functions" :depends-on ("packages")) (:file "main" :depends-on ("packages" "functions"))))
When you load this Lisp file, you tell ASDF about your
:example system, but you're not loading the system itself yet. That is done either by
(asdf:require-system :example) or
And when you load the system, ASDF will:
- Load the dependencies - in this case the ASDF systems
- Compile and load the components of your system, i.e. the Lisp files, based on the given dependencies
packagesfirst (no dependencies)
packages(as it only depends on
packages), but before
main(which depends on it)
functions(as it depends on
Keep in mind:
- Enter the dependencies as they are needed (e.g. macro definitions are needed before usage). If you don't, ASDF will error when loading your system.
- All files listed end on
.lispbut this postfix should be dropped in the asdf script
- If your system is named the same as its
.asdfile, and you move (or symlink) its folder into
quicklisp/local-projects/folder, you can then load the project using
- Libraries your system depends on have to be known to either ASDF (via the
ASDF:*CENTRAL-REGISTRYvariable) or Quicklisp (either via the
QUICKLISP-CLIENT:*LOCAL-PROJECT-DIRECTORIES*variable or available in any of its dists)