A Layman’s Guide to Weblocks

After reading through the first half of Practical Common Lisp, I wanted to check out some real lisp applications to get hands-on experience. I thought I’d start out with a web framework and stumbled across weblocks (CLiki entry). Unfortunately, ‘t is a big step from the book to reality, and for me, having practically zero experience with Lisp library-management, it was not exactly obvious how I should get started. So here’s a tutorial that I wish existed a few hours ago.

First, you need a Common Lisp implementation. Download Steel Blank Common Lisp (SBCL) and install it. Installing it on an x86 Linux machine was as easy as doing:

$ wget http://heanet.dl.sourceforge.net/sourceforge/sbcl/sbcl-1.0.20-x86-linux-binary.tar.bz2
$ tar xjf sbcl-1.0.20-x86-linux-binary.tar.bz2
$ cd sbcl-1.0.20-x86-linux
$ INSTALL_ROOT=$HOME sh install.sh
$ echo 'export SBCL_HOME=$HOME/lib/sbcl' >> ~/.zshrc

Don’t blindly run these commands though, it’s just an illustration of what I had to do on this system. Anyway. Now sbcl is installed, great. Time to install clbuild, a system that takes care of downloading, installing and updating a lot of common Lisp libraries (like a package manager). This was, if possible, even easier than installing sbcl:

$ darcs get https://common-lisp.net/project/clbuild/clbuild
$ cd clbuild
$ chmod +x clbuild
$ ./clbuild check

If you are missing dependencies, resolve them (a matter of installing packages with your package manager, like darcs, subversion, etcetera). Now you’re all set to install weblocks with clbuild!

$ ./clbuild update weblocks

Yay. Next step: automatically loading all the libraries you install with clbuild. There is a system in Common Lisp called ASDF: it’s a way to manage importing libraries and other files portably (a library for loading libraries). The trick is to:

  1. Automatically load ASDF every time SBCL is started, and
  2. automatically tell ASDF the location of all clbuild’s installations.

This is done by putting the following lines in the ~/.sbclrc file:

(require 'asdf)
(push #p"/path/to/clbuild/systems/" asdf:*central-registry*)

What’s happening there is that you (push) a directory on the “global variable” *central-registry* in the asdf package (read the book for clarification). Whenever you try to load a library with ASDF, it will search that list for files matching the name (exactly like Python’s import statement does with sys.path).

According to the weblocks user manual, you should now be able to start weblocks:

$ sbcl
This is SBCL 1.0.20, 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.
* (asdf:operate 'asdf:load-op 'weblocks)


debugger invoked on a ASDF:MISSING-DEPENDENCY in thread #<THREAD "initial thread" RUNNING {A6E5721}>:
component :METATILITIES-BASE not found or does not match version 0.6.6,
required by #<SYSTEM "cl-containers" {BA48F11}>

Type HELP for debugger help, or (SB-EXT:QUIT) to exit from SBCL.

restarts (invokable by number or by possibly-abbreviated name):
0: [ABORT] Exit debugger, returning to top level.


Whoops. Apparently, some library requires some specific version of some other library. So let’s install that:

$ wget https://common-lisp.net/project/metatilities-base/metatilities-base.tar.gz
$ tar xzf metatilities-base.tar.gz
$ cd metatilities-base
$ grep 0.6.6 *
metatilities-base.asd: :version "0.6.6"

Yay, it’s the right version. So: make sbcl load this package before the updated one from clbuild. Put this line in the middle of the other two in ~/.sbclrc:

(push #p"/path/to/metatilities-base/" asdf:*central-registry*)

And voila! You can now run (weblocks:start-weblocks), like it says in the manual!

P.S.: Many thanks to the folks in #lisp, who explained most of this stuff to me!

Or leave a comment below: