A script to update/install the latest versions of all the most important Common Lisp packages.


clbuild is a shell script helping with the download, compilation, an invocation of Common Lisp applications. It defaults to SBCL but otherwise tries to be somewhat independent of your local environment.

clbuild was originally written by Luke Gorrie. (Idea from jhbuild by James Henstridge, a Gnome hacker).

Please send patches bug reports to clbuild-devel@common-lisp.net (list information).

Adding projects

Add projects or submit corrections like this, please:

  1. Add new projects to clbuild/wnpp-projects. Fix clbuild/projects or clbuild/wnpp-projects for existing projects.
  2. Use darcs record to make the change permanent.
  3. Make your repository available over http. This is where others can get the change from you.
  4. Send a pull request to the list, so that we can pull from the patch from your repository. This means to send an email stating your repository URL and what you have changed.


How does clbuild differ from asdf-install?

clbuild includes a list of selected libraries and applications and their well-known locations, and downloads the newest version or CVS/SVN/darcs repositories if possible. It can also build SBCL for you and includes convenient commands to start various applications.

In contrast, asdf-install can install any software listed on Cliki. It always downloads release tarballs. (It is up to the user to hunt down the trustworthy PGP keys as a protection agains malicous wiki entries.)

My favourite application is not supported. How can I add it?

Yes, please see above.

Why did you get rid of all tarball-only downloads?

We use version-controlled download mechanisms to avoid losing local changes when updating.

clbuild's source directory is meant as an area where hackers can do their work, and we wouldn't feel confident recommending it for that purpose if we had to delete and move directories or extract tarballs in there.

Instead, we have the clbuild mirror with darcs conversions of tarball-only projects.

(Future versions of clbuild might do that darcs conversion on-the-fly somewhere in a new directory clbuild/import, and then use darcs pull from that directory into clbuild/source. The downside of that approach would be that different users (and separate clbuild checkouts by the same user) would have incompatible darcs checkouts for the same project.)

It doesn't load my ~/.sbclrc!

Yes, that's the default. But you can change it in clbuild.conf using the USER_INIT configuration variable.

"clbuild lisp" doesn't seem to use my monster.core!

Yes, use "clbuild preloaded" if you want that.

Can I start the lisp with swank already preloaded? (Or: "clbuild slime" doesn't seem to load my monster.core)

Yes, you can change that behaviour in clbuild.conf using the START_SLIME_USING_CORE configuration variable. To preload swank, you can run "clbuild dumpcore slime" before doing that.

Can I run emacs and slime without going through "clbuild slime"?

Yes, just run "clbuild slime-configuration". It prints a .emacs excerpt. Copy&paste it into your .emacs.

Is the "dependencies" file autogenerated?

Yes, using "clbuild record-dependencies", which requires a complete check-out of all projects, including wnpp-projects.

You don't have to run this command when sending us patches for new projects. Anyone merging such a patch will rebuild the dependencies before comitting anyway.

The "dependencies" file is broken!

This file is an educated guess and sometimes not perfect. We prefer to err on the side of too many dependencies rather than too few.

However, the following situations are not necessarily bugs:

Make sure to distinguish between project dependencies and system dependencies.

The following process computes the "project dependencies" of a project FOO:

This process implies that dependencies between projects are not transitive.

For example, the project `babel' depends on the project `rt' because the system BABEL-TEST depends on the system RT.

But the system HUNCHENTOOT depends only on BABEL, not BABEL-TEST, so the project `hunchentoot' does not depend on the project `rt'.

Think about "clbuild update hunchentoot" as "install everything I need to use/hack all parts of hunchentoot", which doesn't include BABEL-TEST or RT. "clbuild update babel" means "install everything I need to use/hack babel", which includes BABEL-TEST and hence RT.

Why is clbuild written in shell? Lisp is so much better.

There are many answers to this question. Here are just a few of them:

Does it work on cygwin?

It used to work on cygwin. Beware that cygwin support is tested only occasionally and might not be complete or functional anymore. (In any case, you need to recompile SBCL with an ASDF patch for shortcut support first.) To start clbuild's slime, make sure to use the Windows version of Emacs, not cygwin's Emacs.

Download and Usage

clbuild is maintained in darcs.

$ darcs get http://common-lisp.net/project/clbuild/clbuild

You might want to make the shell script executable:

$ cd clbuild
clbuild$ chmod +x clbuild

clbuild depends on various helper applications. Try check to make sure they are installed:

clbuild$ ./clbuild check
Checking for helper applications...
found /usr/bin/X11/cvs
found /usr/bin/X11/svn
found /usr/bin/X11/darcs
found /usr/bin/X11/wget
found /bin/tar
found /bin/mktemp
Success: All helper applications found.

Checking Lisp startup...
Success: Lisp starts up using "sbcl"

Looking for installable systems...
0 systems definition files registered

Use list to search for projects:

clbuild$ ./clbuild list web
i cl-webdav              WebDAV server
i closure                CLIM-based web browser
i hunchentoot            web server formerly known as TBNL

Run update to download the userland:

clbuild$ ./clbuild update --main-projects
cvs co flexichain...
cvs co mcclim...
... lots of output not shown ...
update complete                                                   
46 systems definition files registered

You do not have to download all default projects (and in particular, wnpp-projects are not part of the default download anyway). Instead, you can specify a particular project, and download it with its dependencies only:

clbuild$ ./clbuild update climacs
clbuild update climacs
climacs depends on: climacs clx flexichain mcclim slime spatial-trees 
include dependencies in update? (Y/n)y
cvs co climacs...
cvs co clx...
... lots of output not shown ...

To reduce start up times, you can dump a core file including all main projects (or the projects specified on the command line, just like with update):

clbuild$ ./clbuild climacs   # slow, from fasls
clbuild$ ./clbuild dumpcore climacs
clbuild$ ./clbuild climacs   # fast, using monster.core

Building SBCL

You can also download and recompile SBCL using buildsbcl or buildworld:

clbuild$ ./clbuild buildsbcl

Command line arguments

For other options, see help:

clbuild$ ./clbuild help
  check         check availability of all necessary helper applications

  list [PATTERN]  list all projects, or projects matching PATTERN

  update [--dependencies|--no-dependencies] PROJECT_NAME
                download/update this project
  update [--resume]
                download/update main projects.  With --resume, consider
                only projects that a previous update run failed to fetch.
                mark this project as done for the purposes of update --resume

  recompile [PROJECT_NAME] recompile main applications (or just PROJECT_NAME)
  dumpcore [PROJECT_NAME]  recompile and dump a core file for faster startup
  build [PROJECT_NAME]     update && dumpcore

  diff          show local changes (for all version-controlled projects)
  check-urls    compared installed repository urls agains current locations
  clean-links   remove broken symlinks in systems/
  update-missing  download only projects not present yet
  register-asd PROJECT  add .asd file symlinks for PROJECT

  buildsbcl [XC_HOST]  download/update and compile SBCL
  world         buildsbcl && build

  clean         delete all compiled object files
  mrproper      delete all downloaded source and fasl files

  slime         run the Superior Lisp Interaction Mode in a fresh Emacs
  lisp          run Lisp in the terminal

  record-dependencies   rebuild dependency information file

Starting applications:

  run APPLICATION   run this application
  run --help        show help for applications

If you do 'world' or 'buildsbcl' then SBCL will be installed in
target/ and used for future commands. If you don't run these commands
(or you remove target/) then clbuild uses the 'sbcl' in your PATH.

For configuration options (including for non-SBCL lisps), see clbuild.conf.

Application startup

clbuild$ ./clbuild run --help
clbuild run APPLICATION [ARGS...]

  run listener      run the McCLIM listener
  run gsharp        run the Gsharp score editor 
  run climacs       run the Climacs text editor
  run closure [HOME_PAGE_URL]   run the CLOSURE web browser
                    (required Debian packages: gif2png,libjpeg-progs)
  run beirc         run the Beirc IRC client
  run climplayer    run the CLIMPlayer music player
                    (required Debian packages: mplayer, fileschanged, fam)
  run demodemo      run some random CLIM examples
  run clim-alerts   run CLIM alerts
  run eclipse [DPY] run the eclipse window manager

  run hunchentoot   run the Hunchentoot web server test
  run webdav DIR    run the CL-WEBDAV server, serving directory DIR
                    (required Debian packages: libssl-dev)

  run parse-xml FILENAME
                    check XML for well-formedness
  run validate-xml FILENAME
                    check XML for validity
  run validate-relax-ng [--compact yes] XML-FILENAME SCHEMA-FILENAME
                    check XML for validity against a Relax NG Schema
                convert between HTML 4 and XHTMl

  run vecto-demo    generate a test image using vecto