Getting started with ASDF

Written by Michael Anckaert
Last updated on and originally published on
Posted in Lisp Tagged with asdf

In this article I will try and explain what ASDF is from a beginner point of view. As a new Lisp developer you're bound to run into ASDF sooner than later. ASDF is a defacto standard in the Lisp world so a basic understanding is essential to being productive.

Let me just note that the modern way of managing Lisp systems is using QuickLisp. This does not mean that ASDF is superceded or out of date, on the contrary. It is the basis for more user friendly tools such as QuickLisp.

Introduction

ASDF stands for Another System Definition Facility, a mouthful. Basically ASDF allows you to create and use software libraries written in Lisp.

Seasoned Lisp developers will notice that my definition is not exactly correct, but this is gentle introduction to ASDF so it will suffice for now.

What is a Lisp system?

Note that in the Lisp world the term Software Library is not used often. Normally we talk about Lisp systems.

If you're not very familiar with Lisp just yet, the term system will confuse you.

In the Lisp world, a system is a collection of Lisp source code that is related to each other, such as an application or a software library. A system can be organized into packages which in turn can contain multiple source files.

Comparing to other programming languages, a Lisp system can be thought of as a software library.

Getting ASDF

Good news everyone! ASDF is such a great tool that it is included in virtually all major Lisp compilers. I will be using sbcl but there is a very good chance your compiler also has ASDF included.

To check if ASDF is available to you, enter the following expressions in a Lisp session:

(require "asdf")
NIL
(asdf:asdf-version)
"3.3.1"

The first line loads ADSF into your Lisp system. The second line displays the ASDF version that is available to you.

If for any reason you don't have ASDF available, you can simply download it from the ASDF website: https://www.common-lisp.net/project/asdf/#downloads

I would recommend however, if possible, to download a modern Lisp compiler such as SBCL and use that.

Installing systems using ASDF

Installing systems using ASDF is quite easy. From your Lisp session just call the asdf:load-system function:

(asdf:load-system "alexandria")

This will try to load the system alexandria in your Lisp session.

Now, most likely the example above will have thrown an error since your computer doesn't have the Alexandria system available for ASDF to load.

This raises the question: Where does ASDF look for systems?

Where does ASDF find systems?

By default ASDF searches a couple of standard locations on your computer for matching Lisp systems, such as:

  • ~/common-lisp/
  • ~/.local/share/common-lisp/source/

If you place a Lisp system in one of these directories, ASDF can then load it for you.

Let's give it a try with the Alexandria system from the previous example. Move into the directory ~/.local/share/common-lisp/source (create it if you have to), and download the latest version of Alexandria using git:

git clone https://gitlab.common-lisp.net/alexandria/alexandria

This will checkout that latest version of Alexandria. If you check in the alexandria directory, you'll see a bunch of files and directories, including the file alexandria.asd. We'll see all about .asd files later, but this file tells ASDF everything it needs to know to load this system.

Back in your Lisp session, try and load the system again:

(asdf:load-system "alexandria")
;; some output removed
T

The return value from asdf::load-system is T, an indication the system was loaded successfully.

We just saw how we can add the source for a Lisp system to our system and load it using ASDF. Fortunately, there are better options to download and load Lisp systems, the best (IMO) being QuickLisp. Stay tuned for a followup post on how to install and use QuickLisp.

Creating systems for use with ASDF

Now that we know how to use ASDF, it's time to learn how to create systems that can be loaded by ASDF.

For this, we'll create a library that contains a hello-world function that can be used by other applications.

Start by creating directory hello-world in ~/.local/share/common-lisp/source/. Remember that if we place our system here then ASDF will be able to find it and load it for us.

In the hello-world directory, we'll create a file called hello-world.asd that will contain our system definition. The contents will be as follows:

(defsystem "hello-world"
    :description "A hello world library"
    :version "0.0.1"
    :author "Michael Anckaert <michael.anckaert@sinax.be"
    :license "MIT"
    :components ((:file "hello-world")))

This file contains a single Lisp function call to the defsystem function. I won't go over all possible parameters or possiblities here. Check out the ASDF documentation if you want all information.

But the important parts are very easy to understand. What we've done here is define a system called hello-world, added some metadata (such as description, version, etc) and defined the components of our system. In this case our hello-world system is made up of one file, hello-world.lisp (the .lisp extension is implied).

Now to finish up our hello-world system, we'll create the hello-world.lisp file and add our package and function:

(defpackage :hello-world
    (:export :hello)
    (:use :cl))

(in-package :hello-world)

(defun hello (name)
    (format t "Hello, ~A~%" name))

Save the file hello-world.lisp and verify that your directory now has both the system definition in hello-world.asd and the source code in the .lisp file.

Next you can load the hello-world system using ASDF in your Lisp session:

(asdf:load-system "hello-world")
compiling file "/home/michael/.local/share/common-lisp/source/hello-world...
; compiling (DEFPACKAGE :HELLO-WORLD ...)
; compiling (IN-PACKAGE :HELLO-WORLD)
; compiling (DEFUN HELLO ...)

; wrote /home/michael/.cache/common-lisp/sbcl-2.0.3-linux-x64/home/michae...
; compilation finished in 0:00:00.002
T
(hello-world:hello "Michael")
Hello, Michael
NIL

Great! You just created your first Lisp system that can be loaded through ASDF!

More resources

For more information I can highly recommend the ASDF Manual which contains everything you need to know about ADSF.