How To Setup A Common Lisp Web Environment (november 2015)

The software versions we will be using for this tutorial are:

Steel Bank Common Lisp (SBCL) - 1.3.0

Quicklisp - “2015-01-28”

Hunchentoot - 1.2.34

caveman2 - 2.4.0

Setting up SBCL

There are several Common Lisp implementations available. For this tutorial we use SBCL. Steel Bank Common Lisp is one of the most popular Common Lisp implementations, very mature in development and well documented. It may also be possible to follow along with this tutorial in later parts using different Common Lisp implementations but I make no guaruntees. The installation process for SBCL looks a bit different depending on what operating system you’re using.

Installing SBCL on Debian 7.4

The latest release of SBCL can be downloaded from its website. Their getting started page is very Linux friendly. For the rest of this tutorial though we will assume that you installed your copy of SBCL under /usr/local/ rather than your home directory or any other location.

Warning: Do not install the version of SBCL in the debian repositories, as it is out of date and at the time of writing incompatible with quicklisp, which we will install further on in the tutorial.

Installing SBCL on Mac OS X

SBCL is available from the wonderful homebrew package manager. Once installed SBCL can be installed along with it using the command:

brew install sbcl

Installing SBCL on Windows

SBCL is distributed for windows as a .msi installer file, so it should be a simple matter of running the .msi and following the install menu to complete the process.

Quicklisp

Once you have SBCL up and running, you’re going to want to install Quicklisp. Quicklisp is the package management solution for Common Lisp in the vein of Python’s pip or Ruby’s rubygems. It’s distributed as a single file Common Lisp program you can download here and then install using the instructions on their website.

Remember to verify the file hash to make sure it’s the correct one:

user@low:~/lisp-dev$ sha256sum quicklisp.lisp

4a7a5c2aebe0716417047854267397e24a44d0cce096127411e9ce9ccfeb2c17  quicklisp.lisp

Installing The Dev Environment With Quicklisp

Probably the first thing you’re going to want to do is eval (ql:add-to-init-file), as this will automatically load in quicklisp on each boot of the lisp compiler.

Then you’ll want to eval all of the following forms:

(ql:quickload 'caveman2)

(ql:quickload 'clack)

(ql:quickload 'hunchentoot)

;;; These are taken from the .asd generated by caveman2

(ql:quickload 'lack)

(ql:quickload 'envy)

(ql:quickload 'cl-ppcre)

(ql:quickload 'uiop)

(ql:quickload 'cl-syntax-annot)

(ql:quickload 'djula)

(ql:quickload 'datafly)

(ql:quickload 'sxql)

Creating A Project With Caveman2

To borrow from the README file for Caveman2, a new project can be generated once it is loaded in the system by evaluating the form:

(caveman2:make-project #P"/path/to/myapp/"
                       :author "<Your full name>")

Of course, you should replace the filepath there with the path you want for your project. You don’t need to create the directory you use beforehand, it will be made for you if it does not already exist. Your name should also replace the author keyword argument.

eg. If I were making mine I might write:

(caveman2:make-project #P"/home/user/lisp-dev/caveman-test/"
	           :author "John David Pressman")

Once you have generated your project, in order to run it we’ll need to load it into the system. The project generated by caveman2 wants to load itself using quicklisp quickload. In order to make this happen we need to add the project to our asdf path. Vsevolod Dyomkin explains in full here but the short of it is that you need to add the following form to the top of your app.lisp under the project directory generated by caveman2:

(push "path/to/your/app" asdf:*central-registry*)

You want to replace “path/to/your/app” with the path of your project directory.

For example in my app my app.lisp has at the top:

(push "/home/user/lisp-dev/caveman-test/" asdf:*central-registry*) 

(ql:quickload :caveman-test)

Once you’ve saved the file, you should be able to load the project into the system:

sbcl --load app.lisp

Finally, evaluate this form and you’ll have a webserver running on port 11111:

(name-of-your-app:start :port 11111)

For example with my setup it would be:

(caveman-test:start :port 11111)

You’re done! This article is just a tutorial, if you’re not entirely sure what the packages we just installed are a good conceptual explanation of most of them can be found here.