Skip to content
Tutorials Center
My learning

Topics

Lesson 35 of 38 ยท Libraries and Tooling

Testing, Debugging and Delivering Common Lisp Programs

Test Common Lisp code with FiveAM, debug with trace, step, inspect and the interactive debugger, profile with sb-sprof and deliver a standalone executable with save-lisp-and-die.

Lisp development is interactive: you grow a program inside a running image, test each function as you write it and fix errors from the debugger without restarting. This lesson covers the habits and tools that make that workflow reliable, from unit tests to shipping an executable.

No Common Lisp implementation runs on this site, so Lisp and shell code is read-only and I show only outputs I am sure of. JavaScript examples are labelled stand-ins for a tracer, a timer and a test runner.

The editor loop

Most Lisp programmers use SLIME or SLY in Emacs, or Vlime (Vim) and Alive (VS Code) elsewhere; the Emacs and Vim tools talk to an implementation's REPL through a Swank server. The loop is: write a function, send it to the REPL with one keystroke (C-c C-c in SLIME), call it, inspect the result, and repeat. Because you compile single definitions into the live image, there is no full rebuild.

Debugging tools in the standard

LISP
(trace factorial)          ; print each call and return
(factorial 3)
(untrace factorial)

(break "look here")        ; enter the debugger on demand
(inspect (make-instance 'account :owner "Ada"))   ; interactive object browser
(describe 'factorial)      ; documentation, arglist, type
(step (factorial 2))       ; step through evaluation (implementation-dependent)
(time (fib 30))            ; run time and memory report
(disassemble 'factorial)   ; machine code (SBCL)

trace output format differs between implementations; SBCL prints indented 0: (FACTORIAL 3) lines with return values. time prints elapsed real and run time and bytes consed, a quick first benchmark.

The debugger opens on an unhandled error and lists the backtrace and restarts. In SLIME you can select a stack frame, inspect its local variables, evaluate expressions in that frame (e), restart the frame, fix the function definition and continue. That ability to fix the bug in the middle of the failing run is a signature Lisp experience.

JS Stand-in: a trace wrapper

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

No output.

Unit testing with FiveAM

FiveAM is a popular test framework. Tests are grouped in suites and use is, signals and finishes:

LISP
(ql:quickload "fiveam")
(defpackage :myapp-tests (:use :cl :fiveam))
(in-package :myapp-tests)

(def-suite myapp-tests :description "Tests for myapp")
(in-suite myapp-tests)

(test addition
  (is (= 4 (+ 2 2)))
  (is (equal '(1 2) (list 1 2))))

(test errors
  (signals division-by-zero (/ 1 0)))

(test with-fixtures
  (let ((acct (make-instance 'account :balance 100)))
    (is (= 100 (balance acct)))))

(run! 'myapp-tests)

is checks a boolean expression and, on failure, reports the expression and its evaluated pieces; signals asserts that a condition class is signaled. run! runs a suite and prints a summary; debug! opens the debugger on the first failure so you can examine the failing state interactively. Hook run! into your ASDF test-op (the systems lesson) so asdf:test-system works, and call it from CI with sbcl --non-interactive --eval '(asdf:test-system "myapp")'.

Other frameworks (Parachute, Rove, lisp-unit2) differ in syntax but share these ideas. The mini test framework project builds one from scratch with macros.

JS Stand-in: a tiny test runner with is and signals

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

No output.

Profiling and performance

For hot spots use the statistical profiler in SBCL:

LISP
(require :sb-sprof)
(sb-sprof:with-profiling (:report :flat :max-samples 40000)
  (run-expensive-job))

It samples the stack and prints where time went. (time ...) shows consing, which often explains slowness: reducing allocation by reusing arrays or declaring types usually beats micro-optimizing arithmetic. Add declarations only after profiling:

LISP
(defun sum-floats (v)
  (declare (type (simple-array double-float (*)) v)
           (optimize (speed 3) (safety 1)))
  (let ((s 0d0))
    (declare (type double-float s))
    (loop for x across v do (incf s x))
    s))

(declaim (inline f)) and (declare (type ...)) give the compiler the facts it needs to generate fast code. Compilers such as SBCL print optimization notes at (speed 3) that tell you what blocked an optimization.

Image-based delivery

An implementation can save its entire running state, loaded code included, as an image. With SBCL, that yields a standalone executable:

LISP
(defun main ()
  (format t "Hello from a saved image~%")
  (sb-ext:exit :code 0))

(sb-ext:save-lisp-and-die "myapp"
  :toplevel #'main
  :executable t
  :compression nil)

Run sbcl --load build.lisp and you get ./myapp, which starts quickly (it maps the image) but is large (tens of MB, since it contains the compiler and runtime). Use :compression t if SBCL was built with zlib/zstd support. Command-line arguments are in sb-ext:*posix-argv*; libraries like Clingon or unix-opts parse them. Other options: ASDF's program-op with :build-operation "program-op" and :entry-point "myapp:main" in the .asd file, Roswell's ros build, ECL (compile to C/executable) or buildapp.

Before saving, close threads, files and foreign handles, since images cannot save live ones: save-lisp-and-die refuses to run with other threads still active and runs sb-ext:*save-hooks*, which you can use to clean up.

A project checklist

  • Keep a test system and run it in CI on every push.
  • Use (declaim (optimize (debug 2))) during development for good backtraces; (speed 2) for release.
  • Treat compiler warnings as bugs: style warnings about undefined variables and functions usually mean a typo.
  • Keep a build.lisp or Makefile that loads Quicklisp, quickloads the system and saves the image.
  • Pin dependencies (Qlot/OCICL or a dist version).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does trace do?

    (trace f) wraps f so calls and returns are logged until you call (untrace f).
  2. 2. How does FiveAM's debug! differ from run!?

    debug! lets you investigate a failing check interactively; run! just reports.
  3. 3. What does sb-ext:save-lisp-and-die produce?

    The whole heap is written to disk; with :executable t it is bundled with the runtime.
  4. 4. When should you add type declarations and (optimize (speed 3))?

    Correct, readable code first; optimize measured hot spots with declarations.

Summary

  • Develop in a live image with SLIME or SLY; compile small pieces and fix errors from the debugger.
  • trace, inspect, describe, time, step and the debugger are the standard diagnostics.
  • FiveAM provides suites, is, signals, run! and debug!; connect it to asdf:test-op.
  • Profile before optimizing (sb-sprof), then add declarations to hot code only.
  • Deliver an executable with save-lisp-and-die or ASDF's program-op.
  • The JavaScript tracer and runner are stand-ins that imitate the interface.

Next: Project: A Mini Test Framework