Download and install Common Lisp
Two versions of Common Lisp are recommended for this class. Both are free, and both are mature systems.
- The free (Express) version of Franz, Inc.'s Allegro Common Lisp . The Windows version includes a graphics development environment. The MacOS version has an IDE that uses the X11 Windowing system. For Unix, Franz recommends SLIME as an IDE. This is beyond the scope of this tutorial.
- The free (personal) version of Lispworks. This provides a graphical IDE for Windows, MacOS, and GTK+ (Linux).
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 recommend SBCL for this course. Support is particularly weak on Windows and MacOS. SBCL forces Unix line endings onto code files on Windows, has to be re-built from source to get multithreading on MacOS, just plain doesn't seem to support the portable AllegroServe web server, 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
translate_tabs_to_spaces to true.
Be sure to use the extension
.lisp for all
Lisp source files. Many Lisp integrated development environments (IDEs),
like other IDEs, use the extension to determine what indentation rules to
Scheme is not suitable for this course.
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.
- Be sure the file is saved with the extension is
lisp. Browsers often want to save this file as
quicklisp.lisp.txtinstead. 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.
Load quicklisp.lisp using the File | Load command in your Lisp. This file does not need to be compiled.
In the Listener, evaluate
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.
QuickLisp will check for and install ASDF2 if your Lisp doesn't ASDF already. Unfortunately, some libraries these days want ASDF3, so we need to upgrade.
In Lisp, the global variable
*features* is a list of names of installed
features. To see if ASDF3 is installed already in your Lisp, execute this line of code in your
Lisp listener window:
(member :asdf3 *features*)
If it returns
nil, you need to upgrade. If it returns a list, you can skip this step.
Several files need to be replaced in the QuickLisp directory, ~/quicklisp/, and a subdirectory needs to be cleared.
- Replace ~/quicklisp/asdf.lisp with ASDF3
- Replace ~/quicklisp/setup.lisp with this version that checks for ASDF3
- Remove everything in the directory ~/quicklisp/cache/asdf-fasls/.
- This should cause an updated ADSF3 to be loaded when you restart Lisp, after you do the remaining setup tasks.
On Unix and MacOS, the file syntax
~/quicklisp/ refers to
quicklisp subdirectory in
your home directory.
On Windows XP and later, the equivalent way to write this is
%USERPROFILE%\quicklisp\. For brevity,
we'll use Unix syntax. In Lisp code, use the Unix syntax to refer to files
and directories. That works on all platforms.
Don't quit Lisp yet.
Install the CS325 Library
There are a number of Lisp tools used in this class. They are set up as a QuickLisp local project.
- Download and extract cs325.zip
- Put the entire
SBCL on Windows only: SBCL uses Unix line endings, even on Windows, a major SBCL bug IMO. This breaks the Lisp Critic rule file, lisp-rules.lisp. To fix, you need to convert lisp-rules.lisp 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.
Now, in Lisp, tell Quicklisp to update its list of projects, then 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.
If you see any messages labeled ERROR, stop and check the messages to see if you can determine the problem. If you can't, post your problem. Be sure to include what Lisp and operating system you are using, along with the exact error message, copied and pasted.
If you see compiler messages labeled warnings, these may be OK. Continue.
Set Up Your Init File
You now have at least two things you want to do every time you start Lisp:
In addition, in each Lisp there are some platform-specific options you can customize that will make things more convenient.
Most Lisps 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.
- Select Tools | Options
- Change Initial Package from
- Click OK
Now exit Lisp and test your setup.
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 select the file ~/lww-init.lisp every time you start Lisp.
The first time you test your setup, check that the ASDF3 upgrade worked.
Lispworks only: After loading completes, hit the spacebar to switch to the Lisp listener window. Type (in-package :cs325-user) to change to the package with the CS325 tools.
Testing Your Setup
(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.
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.
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).
Windows tip (optional)
To have File | Open in Lisp automatically open in ~/quicklisp/local-projects/cs325/,
- In Windows, right-click on the icon that starts your Lisp
- select Properties
Start in:to the 325 code directory.
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 the 325 Piazza site.
- Look to see if someone else had the same problem you did, and what answers they got.
- If your problem is a new one, POST your problem. Be specific about what platform you're on, e.g., Windows XP, Linux, ... Copy and paste the error message, if any.
- If you've seen that problem and know the solution, POST the answer. Helpful postings can increase your grade!