Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 38 ยท Libraries and Tooling

Packages and ASDF Systems

Organize Common Lisp code with defpackage, in-package, export and import, then describe projects with ASDF .asd files, dependencies, load order and test systems.

A real project is many files, many names and several libraries. Common Lisp solves namespaces with packages and build and load order with ASDF, the de facto system definition tool bundled with every major implementation. This lesson shows both and the conventional project layout.

No Common Lisp implementation or ASDF runs on this site. The Lisp and .asd code is read-only. The JavaScript examples are labelled stand-ins modeling symbol interning and dependency ordering.

What a package is

A package is a table mapping symbol names to symbols. The reader looks up each name in the current package (*package*) and creates the symbol if needed (interning). The same text can therefore mean different symbols in different packages. package:symbol names an exported symbol, and package::symbol an internal one (a code smell when used on someone else's package).

LISP
(defpackage :myapp.geometry
  (:use :cl)
  (:export #:area #:perimeter #:make-shape))

(in-package :myapp.geometry)

(defun area (w h) (* w h))
  • (:use :cl) makes the standard symbols available without prefix.
  • (:export ...) lists the public interface. #:name uses an uninterned symbol so the definition does not itself intern names in the wrong package.
  • in-package sets *package* for the rest of the file.

Another package can use it:

LISP
(defpackage :myapp.cli
  (:use :cl)
  (:import-from :myapp.geometry #:area)
  (:local-nicknames (#:g #:myapp.geometry)))

(in-package :myapp.cli)

(area 3 4)         ; imported symbol
(g:perimeter 3 4)  ; via a local nickname

:import-from brings specific symbols in; :local-nicknames (supported by SBCL, CCL, ECL, ABCL and others) gives short per-package aliases for packages. Avoid :use-ing large third-party packages: two packages exporting the same name cause a name conflict error. :shadow resolves a conflict by creating a local symbol:

LISP
(defpackage :myapp.util
  (:use :cl)
  (:shadow #:search))    ; define our own SEARCH, not CL:SEARCH
JS Stand-in: packages as symbol tables

Press Run (or Ctrl + Enter) to see the console output here.

No output.

ASDF systems

A system is a named collection of files with dependencies. You describe it in a .asd file:

LISP
;; myapp.asd
(asdf:defsystem "myapp"
  :description "A small example application"
  :version "0.1.0"
  :license "MIT"
  :depends-on ("alexandria" "cl-ppcre")
  :serial t
  :components ((:module "src"
                :components ((:file "package")
                             (:file "geometry")
                             (:file "main"))))
  :in-order-to ((asdf:test-op (asdf:test-op "myapp/tests"))))

(asdf:defsystem "myapp/tests"
  :depends-on ("myapp" "fiveam")
  :components ((:module "t" :components ((:file "tests"))))
  :perform (asdf:test-op (op c)
             (uiop:symbol-call :fiveam :run! :myapp-tests)))

Key parts:

Option Purpose
:depends-on other systems loaded first (found via ASDF's registry, often from Quicklisp)
:components files and modules; (:file "x") means x.lisp
:serial t each file depends on the previous one
:module a subdirectory with its own components
:pathname override the default location

Without :serial t you state each file's order explicitly with :depends-on inside the component, which allows parallel compilation in some setups but needs more typing. Systems with / in the name (myapp/tests) are secondary systems defined in the same .asd, which is the standard way to keep test dependencies out of the main system.

A typical layout:

TEXT
myapp/
  myapp.asd
  src/
    package.lisp
    geometry.lisp
    main.lisp
  t/
    tests.lisp
  README.md

Loading and testing

LISP
(asdf:load-system "myapp")      ; compile if needed and load
(asdf:test-system "myapp")      ; run test-op
(asdf:compile-system "myapp" :force t)

For ASDF to find your system it must be in a registered location, for example ~/common-lisp/ (scanned by default in modern ASDF), a directory in ~/.config/common-lisp/source-registry.conf.d/, or a project under Quicklisp's local-projects. Compiled .fasl files go to a cache under ~/.cache/common-lisp/ so source trees stay clean.

package-inferred systems

ASDF also supports package-inferred systems, where each file foo/bar.lisp starts with a defpackage whose :use and :import-from clauses name other files/systems; ASDF infers dependencies from them. It removes the component list but has some tooling trade-offs; many projects still use classic .asd files.

JS Stand-in: dependency-ordered loading

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common mistakes

  • Reading a file before its package exists: package.lisp must load first; with :serial t list it first.
  • Typing (in-package :foo) before the package is defined: put defpackage in its own early file.
  • Forgetting to export: functions work inside the package but fail from others with "not external".
  • Circular dependencies between files: restructure or split a shared package.
  • Naming your package utils: collides with other projects; use a project prefix (myapp.utils).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does (:export #:area) do?

    Exported symbols can be referred to with a single colon from other packages.
  2. 2. What is :serial t in an ASDF component list?

    It is a shortcut for a linear dependency chain, which suits most small projects.
  3. 3. Why put tests in a secondary system like myapp/tests?

    Users of the library load myapp without pulling in fiveam.
  4. 4. How do you resolve a name conflict between two used packages?

    Shadowing makes your package's own symbol (or a chosen one) take precedence over the conflicting inherited symbols.

Summary

  • Packages are namespaces mapping names to symbols; defpackage, in-package, export, import-from and local nicknames control visibility.
  • ASDF .asd files list components, dependencies and test systems; load-system and test-system drive them.
  • Keep one package per major subsystem, an early package.lisp, and tests in a secondary system.
  • The JavaScript snippets only model interning and dependency ordering.

Next: Quicklisp and Common Libraries