Until this week, I had been putting off setting up a CL/Emacs/SLIME environment from scratch ever since I had trouble getting ASDF to work with Lispbox. Every time I tried, I ran into some will-sapping problem like needing to find a good Windows program for .tar.gz files, or finding the command line flags to get CLISP to run right, or figuring out the best way to setup a folder structure that matches the Unix folders used by most Lispers. Every time I fixed one problem, I ran into another. For someone out there trying to do a setup like this, there are lots of good resources, but they are either incomplete or outdated.

For instance, the Common Lisp Cookbook has a very thorough page on Setting Up an IDE with Emacs on Windows or Max OSX, but as far as I can tell, it’s from 2004 or earlier because it doesn’t mention SBCL or SLIME, two of the most popular pieces of CL development software today. Or when you run into a specific problem, it’s usually not too hard to find an answer, but it might not match the setup you’re using. That’s why I had to quit using Lispbox, because no one had any clue how it was configured, especially not on Windows. n00bs didn’t know the answers and the wizards had a traditional setup.

Here are some of the variables that contribute to the combinatorial explosion of configuration, in order or pain caused:

• Operating system: Linux (many flavors), Mac, Windows, Cygwin
• CL implementation: most common are SBCL, CMUCL, Allegro, LispWorks, CLISP
• CL implementation version (I ran into a problem here)
• SLIME version (stable 2.0 release or CVS snapshot)
• Emacs version (I didn’t run across any problems with this)
• I almost forgot, now there’s Cusp/Eclipse if you don’t want to use Emacs/SLIME, but right now Cusp is only tested on SBCL.

Maybe someday someone will try out all of those combinations and report, but for today, I did exactly one: Windows XP, CLISP 2.44, SLIME CVS, and Emacs 22.2 Why CLISP? After reading lots of internet, I came to the conclusion that (aside from the commercial CLs), CLISP is the best implementation for Windows users. The knocks against it are that it’s slow because it’s byte-code compiled, it doesn’t have threads, and on some points, it’s ideologically different from CL and other implementations.

Well, the performance isn’t a big concern for me (plus as I went to press, 2.45 was released with experimental JIT compilation), the threads also aren’t a big deal right now, and I think the differences will help me be aware of the considerations for writing portable code. Also regarding the SBCL windows port, it’s still considered experimental (currently v1.013 for Windows) but people are saying it’s stable and everything works except the threads. There’s even an msi installer for the Windows version. One of my next projects will be to dive into the SBCL documentation and mailing lists to get a better feel for it.

As far as the philosophy behind this (and future) setup guides, I want them to be a) thorough and b) instructive. Instructive? If you just want to take my word for everything, that’s fine, but I want you to know where I got my info from, so I’ve tried to include links to references for each step. On to the setup guide!

0. Files to Download

If you want to get started on downloading the setup files, here are the links:

• 7-zip (download v4.57 – 840K) – for unpacking .tar and .tar.gz files commonly used in *nix.
• Emacs (download v22.2 – 37MB)
• CLISP (download v2.44 – 4MB)
• SLIME (download CVS snapshot – 700K) – CLISP recently removed a function used in the 2.0 version of SLIME, but the SLIME CVS snapshot has that fixed

1. Setup Directories

Windows XP loves extremely long pathnames like C:\Documents and Settings\Username\Application Data. This is okay if for GUI-driven apps, but in Emacs, you’re not clicking, you’re typing, and you want short path names. Also, much (most?) of the open source Common Lisp tools are developed on *nix, so there’s less impedance mismatch when using stuff off the net if you have a *nix-ish folder structure.

Start with a root folder. In the pathnames in the rest of this guide, I’ll refer to it as [HOME]. I used C:\home\ to match the *nix convention of having user files be in /home/username/. You also need a username directory – I called mine peter and I’ll refer to it as [USR]. So in my case, [HOME]/[USR] would be C:\home\peter\.

Emacs NOTE #1: One important point about filenames in Emacs is that they CAN be entered with ‘/’, but if you prefer to use ‘\’, you have to escape it with another back slash, so in Emacs buffers and files, you would enter “C:/home/” or “C:\\home\\” but never “C:\home\”. The trailing slash is also important because it indicates that it’s a directory. Now that you have chosen your [ROOT] and [USR] values, these are the folders you should setup:

• [HOME]\[USR]\
• [HOME]\[USR]\site\
• [HOME]\[USR]\docs\
• [HOME]\[USR]\lisp\
• [HOME]\[USR]\info\
• [HOME]\bin\

2. Setup Emacs

Emacs does not need to be “installed” like most Windows apps – it just runs from its directory. Extract it to [HOME]\bin\. I changed the folder name from emacs-22.2 to just emacs, so my path was c:\home\bin\emacs\. You run emacs by running the file [HOME]\bin\emacs\bin\runemacs.exe.

Emacs settings are stored in a configuration file called “.emacs”. On Windows, the default working folder and .emacs location is C:\Documents and Settings\Username\Application Data, but that’s too painful to type and it’s a hidden folder so it’s not even easy to get through with the GUI. To have Emacs work in a different folder, create a file called site-start.el in the emacs\site-lisp folder. In that folder, put the following line (but change the path to match yours):

(setenv "HOME" "[HOME]/[USR]/")

(Thanks Nathaniel! This was probably the biggest annoyance of mine that made me put off finishing setup for so long.)

Emacs NOTE #2: Emacs has lots (and lots and lots) of keyboard shortcuts, many more than there are letters in the alphabet. Many of them require multiple keys or a sequence of keys called a “chord”. The two modifier keys used are Control and Alt (also called Meta). The common way to write chords is to use C- and M- for Control and Meta, so to run the command to close Emacs, you hold down Control and X, then let go, then hold down Control and C. This is written as C-x C-c. Sometimes a chord is followed by another letter or the name of a command. For instance, to undo, you hold Control and x, then let go and hit u. This is written as C-x u. Dashes mean press at the same time, space means let go. Easy! I made a cheat sheet for common commands in Emacs and SLIME.

Now it’s time to create your .emacs file. Run emacs and hit C-x C-f. This is the find command, which is used to create or open a file. At the prompt “Find file: “, type “~/.emacs” (without quotes). Right now just put a ; (that’s the comment marker in Emacs Lisp files) and save it by hitting C-x C-s. There’s a world of stuff you can put in a .emacs file, but that’s too much to bite off now.

3. Install CLISP

This is easy if you download the install package (that’s the one I linked to). Run the installer and choose [HOME]\bin\clisp\ as the install directory. That’s it!

4. Setup SLIME

CLISP changed recently (around version 2.44 – not sure exactly) and broke compatibility with the SLIME 2.0 release. This was fixed in development and the CVS snapshot works. If you try to use the 2.0 release, you’ll get an error that looks like this:

INTERN(“FRAME-UP-1”): #<PACKAGE SYSTEM> is locked

So use the CVS snapshot (which I linked to) and you should be fine.

Extract the SLIME folder to [HOME]\bin\emacs\site-lisp. (Here’s a tip about putting emacs code in site-lisp).

Now in Emacs, open your .emacs file (C-x C-f, ~/.emacs) and enter the following (general SLIME instructions, CLISP specific parameters), changing your pathnames as usual:

(setq inferior-lisp-program “[HOME]/bin/clisp/full/lisp.exe
-B [HOME]/bin/clisp/full
-M [HOME]/bin/clisp/full/lispinit.mem
-ansi -q”)
(add-to-list ‘load-path “[HOME]/bin/emacs/site-lisp/slime/”)
(require ‘slime)
(slime-setup)

Save the .emacs file (C-x C-s), then run the eval-buffer command (M-x eval-buffer). This will run the code that you just entered and tell Emacs how to run SLIME.

Now, you start slime with M-x slime and you’re ready to go!

————————————–

I hope this works for you – I ran through it on another computer and it worked the first time, so if you use exactly these parts you should be OK. Please let me know if you run into problems so I can incorporate the fix into my doc. Many thanks to everyone who I linked to, since they did the coding, testing, and writeups that I used to get here. More resources to come – tell me what you’d like to see. If it’s something I was planning on doing anyway, I’ll move it up my queue.

The next guide will probably be setting up your built-in documentation (Hyperspec, etc).