Lori Holden

A newbie guide to getting started on Common Lisp

Getting into the world of Common Lisp programming can be a daunting one, even for the experienced programmer. The language is beautiful and powerful yet has many sharp edges and no real commonly understood starting point.

This guide will likely be a work in progress for a while, but hopefully it will make the task of getting into Common Lisp a less daunting one.

Understanding Common Lisp

The Common Lisp article on Wikipedia is amazingly comprehensive.

Ariel Networks has a reasonable style guide for Common Lisp.

The HyperSpec has the complete documentation on the Common Lisp language.

CLQR is a nice downloadable quick reference booklet for Common Lisp.

L1sp.org is a great redirect service for Common Lisp documentation.

Know your tools


Emacs is very much the definitive editor for working with Lisp. It allows for a live development process very much unique to Lisp. Check out this lightning talk by David O'Toole working on a game with Emacs and his Blocky.io game development system to see an example of live development in action. Pretty cool right?

Steel Bank Common Lisp

While there are many different Common Lisp implementations available, SBCL is very much the standard implementation to use these days. It is very actively developed, has a decent debugger, native threading, and support for many platforms.


Quicklisp makes it easy to get started with a rich set of community-developed Common Lisp libraries. It allows you to download, install, and load any of over 700 libraries with a few simple commands and has entirely replaced it's predecessor ASDF-Install. If you are familiar with RubyGems, it is very similar.


CL-Project bootstraps new projects for new Common Lisp following modern best practices. While it is certainly not required, it does provide a reasonable starting point when creating a project.


Buildapp makes it easier to create executables with SBCL.


ASDF allows you to define the structure and dependencies of your project. You could think of it as a hybrid between Rake and a Gemfile from the Ruby world.

Building your first app

I am going to leave the task of obtaining Emacs ans SBCL up to you, but you can find versions of both for Linux, Windows, and MacOS.

Installing Quicklisp and SLIME

$ curl -O http://beta.quicklisp.org/quicklisp.lisp
$ sbcl --load quicklisp.lisp
This is SBCL, an implementation of ANSI Common Lisp.
More information about SBCL is available at <http://www.sbcl.org/>.

SBCL is free software, provided as is, with absolutely no warranty.
It is mostly in the public domain; some portions are provided under
BSD-style licenses.  See the CREDITS and COPYING files in the
distribution for more information.

==== quicklisp quickstart loaded ====

To continue, evaluate: (quicklisp-quickstart:install)

Get things installed:

(ql:quickload "quicklisp-slime-helper")

Now edit your Emacs configuration to automatically load SLIME:

(load (expand-file-name "~/quicklisp/slime-helper.el"))
(setq inferior-lisp-program "sbcl")

Bootstrap that app!

Load up Emacs and type <esc> x slime <enter>. You should now be looking at the REPL, an interactive lisp prompt.

Creating the skeleton for your project:

(ql:quickload "cl-project")
(cl-project:make-project #p"~/myapp"
 :author "Your name"
 :email "[email protected]"
 :license "BSD or whatever")
  (ql:quickload "myapp")
(in-package :myapp)

cl-project may generate a warning about your version number. While this can be ignored for now, you can edit the newly generated .asd file to change it to something like "0.1".

Now in the Emacs 'window' labeled scratch type <esc> x cd <enter> myapp <enter> followed by <control>x <control>f src/myapp.lisp <enter> and you should have the newly created myapp.lisp file ready for awesome coding.

Let's go ahead add toss something in there and try it out!

(defun hello-world ()
 (format t "Hello world.~%"))

Now we can inject our changes into the REPL by putting the cursor at the end of the line and typing <control>c <control>c. Go ahead and execute our new function by switching to the repl and typing:


Congrats! You are programming with Common Lisp.

Loading your app again after restarting Emacs

CL-Project modifies the current load path at run time to make loading your application the first time easy.

You have 3 ways of putting your application back into your load path.

  1. Make the application your current directory. Either start Emacs from the application directory or change the directory while in Emacs before loading slime.
  2. Move your app to ~/quicklisp/local-projects and it will always be accessible.
  3. Add the project to your load path.

Personally I use option #1 for applications and option #2 for libraries.

Building an executable

While it's certainly not required to build executables to make useful Common Lisp programs, it certainly can be handy for stand alone distribution of our app. The executable you generate is going to have an entire lisp environment embedded, so don't be surprised at the size of the binary.

First, lets define a point of entry for our executable

(export 'main)
(defun main (args)

You will need to download and install the buildapp tool, directions for which are on it's website.

Now on the command line from your myapp directory we can run buildapp to compile your program!

buildapp --asdf-tree $HOME/quicklisp/dists/quicklisp/software \
           --load-system myapp --entry myapp:main --output hello
> Hello world.

What's next?

Practical Common Lisp provides a great introduction to Common Lisp and was my first real introduction to the language.

Common Lisp the Language, 2nd Edition is the definitive book on Common Lisp.

On Lisp provides a comprehensive study of advanced Lisp techniques.

Land of Lisp is both very funny and a rather enjoyable read.


2012-06-26 2:39 PM: Description for how to put slime to into your load path. Corrected the export for the main function for generating your own executable. Added section for loading your app after restarting emacs.

2012-06-26 2:52 PM: Added more books and references.