Download and install Common Lisp

Two versions of Common Lisp are recommended for this class. Both are free, and both are mature systems.

SBCL is popular with Unix users. It is open-source and doesn't have the memory / time limitations that the free versions of Allegro and LispWorks do.

I do not personally recommend SBCL for this course. SBCL support for Windows and MacOS is weak. SBCL forces Unix line endings onto code files on Windows, has to be re-built from source to get multithreading on MacOS, and doesn't provide a user-friendly Lisp-savvy editor out of the box.

You must use a Lisp-savvy editor that knows how to correctly indent Lisp. If you try to indent by hand, you will get it wrong. I immediately return incorrectly indented Lisp code to be fixed.

Allegro and LispWorks come with a Lisp-savvy editor. SBCL does not. Many SBCL users recommend the SLIME extension for Emacs. Do not use Sublime, unless you add lispindent, and set translate_tabs_to_spaces to true.

Use the extension .lisp for all Lisp source files. Some Lisp editors will not indent code in a file properly unless the file has been saved with a known Lisp extension.

Scheme is not suitable for this course.

Install Quicklisp

Quicklisp is a Lisp library that makes it easy to download and install other libraries.

Quicklisp depends on ASDF files to define Lisp "systems." A Lisp system is what other languages call a library or module, i.e., a set of files, and a list of any other systems that this system depends on.

Download quicklisp.lisp into some directory that is easy to find.

Check for two common mistakes:
  • Be sure the file is saved with the extension is lisp. Browsers often want to save this file as quicklisp.lisp.txt instead. That won't work. Rename the file if this happened.
  • Be sure the file doesn't contain HTML. Some browsers add HTML code when you do "Save As..." If this happens, try a different approach to downloading the file. The file should only contain Lisp code.

Start Lisp

Load quicklisp.lisp using the File | Load command in your Lisp. This file does not need to be compiled.

In the Listener, evaluate

(quicklisp-quickstart:install)

This operation will download the files that Quicklisp needs. You will not need to do this in the future. If there are any errors, ask for help.

Do not call ql:add-to-init-file as described on the Quicklisp page. The instructions below will take care of that part.

Don't quit Lisp yet.

Install Git

If you don't already have Git installed, do so now.

Install the CS325 Library

There are a number of Lisp tools used in this class. The source code is on Gitlab. To use them, you install the code as a Quicklisp local project.

Open a terminal command shell, create the folder ~/quicklisp/local-projects/ navigate there, and install the CS325 code. The following commands will do this on MacOS, Linux, Unix, or Windows WSL:

cd ~/quicklisp/local-projects
git clone https://gitlab.com/criesbeck/cs325.git

Now, in Lisp, tell Quicklisp to update its table of local projects, and try loading the 325 code.

> (ql:register-local-projects)
...
> (ql:quickload "cs325")
...

If everything is set up correctly, a number of files will be compiled and loaded. Compiling happens only when a file is added or changed. Future loads will be much quicker.

You will see warnings about some undefined functions. These are functions you will define in exercises. If you see any messages labeled ERROR, stop and check the messages to see if you can determine the problem. Make sure ~/quicklisp/local-projects/cs325/ exists. If you can't figure out the problem, post to Piazza. Include what Lisp and operating system you are using, and copy and paste the exact error message.

Updating the CS325 library

I will post to Piazza announcements about updates to the CS325 library. When you see these, open a terminal command shell, navigate to the CS325 local project, and use Git to update the code.

cd ~/quicklisp/local-projects/cs325
git pull

The next time you start Lisp, Quicklisp will automatically recompile and load the updated code.

Set Up Your Init File

Now you should automate loading QuickLisp and CS325 every time you start Lisp:

Different Lisps have platform-specific options to do this. Most Lisps can load one or more initialization files with Lisp code when they start. The location and contents of these files depends on your specific Lisp. I have created initialization files for several Lisp. Download the appropriate file for your Lisp platform and put it in your home directory.

If you're using another Lisp, post to the Q&A site what information you can find about the Lisp initialization files used by your Lisp.

Now exit Lisp and test your setup.

Starting Lisp

Start your Lisp. Allegro and SBCL will start loading the init file automatically.

LispWorks only: The free edition does not auto-load init files. Use the File | Load menu option to locate and load the file ~/lwinit.lisp every time you start Lisp.
After loading completes, hit the spacebar to switch to the Lisp listener window.

Testing Your Setup

Type:

(critique (defun foo (x) (setq x (+ x 1))))

This calls the Lisp Critic. If all has been set up correctly, several critiques of the above code should be printed.

SBCL on Windows only: If you get an error message running the Lisp Critic, it may be because SBCL can't handle Windows line endings. This affects the Lisp Critic rule file, ~/quicklisp/cs325/lisp-rules.lisp. To fix, you need to convert that file to Unix line endings with some utility, such as dos2unix. Convert that file before continuing. You will need to do this whenever I release updates to the rule file.

Then type

(get-tests)

This should return several lines of names of exercises that you will need to use to check your exercise answers with the Lisp Unit Tester before submitting.

Set Preferences

Some preferences in Lisp are more easily set with dialog boxes while running Lisp than with code in Lisp initialization files.

LispWorks Editor Keys

Unless you are an Emacs fan, you will want to change how keys work in the Lisp editor windows.

Allegro Initial User Package

You can tell Allegro to switch to the CS325 user package on startup:

Exiting Lisp

How you exit Lisp depends on what Lisp and operating system you are using.

If you are using Allegro or LispWorks on Windows, use File | Exit.

If you are using LispWorks on MacOS, use LispWorks Personal | Quit LispWorks Personal.

If you are using Allegro on MacOS, Allegro runs inside of the X11 windowing system. If you quit X11, it will automatically quit Allegro. If you quit Allegro, you will need to quit X11 separately.

If you are using SBCL, type (sb-ext:exit).

Where to get help

There's a lot of ways to make trivial errors in configuring any language environment, and most of them lead to fairly cryptic messages and behavior.

To get help, post on Piazza.

Faculty: Chris Riesbeck
Time: Monday, Wednesday, Friday: 11:30am - 12:20pm
Location: Zoom link on Canvas

Contents

Important Links