Links to other sites
Lisp: the programmable programming language

Prepare your Lisp environment(s)

You want to get started with Lisp today and just want a short set of instructions to get started beyond what you might find in other excellent Common Lisp tutorials.

This page will help if you're using MacOSX or Linux (Ubuntu or Debian distributions, specifically) and may be extrapolated for Windows.

That is, there's nothing specific to Windows here, but Bill Clementson's blog entry, Configuring SLIME for 3 Win32 CL Implementations may help. (Linked from SLIME-HOWTO page)

This page primarily focuses on SBCL as the open source Lisp system.

For commercial work, LispWorks is recommended, and they provide documentation on their product better than would be maintained here.

You'll want a few components:

  1. an interactive Lisp compiler (not necessarily interpreted)
  2. an editor with syntax highlighting and Lisp interaction hooks
  3. Lisp interaction mechanism (i.e., SLIME)
  4. a running Lisp based web app with which to interact, possibly on a remote server!

Follow the steps below, and you'll be running soon enough.

Installation packages may have changed since this document was originally written. Please validate file paths along the way!

Documentation

The SBCL manual extends and complements the original CMU CL manual. Some commands, particularly some Unix integration and other OS interaction requires the latter.

The de facto standard reference manuals are Common Lisp the Language, 2nd Edition (CLtL2) and the HyperSpec.

Download each, respectively: (Debian Linux has its own packages for these)

The example configuration below puts these under /usr/local/share/doc/.

Installing SBCL

Packaged Versions of SBCL

Recommended: skip this section and get the latest version (below) instead.

The least effort approach may be to get pre-compiled versions for your OS, but this will most certainly lag behind the current released versions.

Getting the compiler and other basic tools:

MacOSX pre-compiled packages:
Install Fink (Get installer) 
export PATH=/sw/bin:/usr/local/bin:$PATH
sudo apt-get update
sudo apt-get install sbcl
MacOSX ports collection: (compile from source)
Install MacPorts (formerly, Darwin Ports; see also PortAuthority) 
export PATH=/opt/local/bin:/usr/local/bin:$PATH
sudo port sync
sudo port install sbcl
Ubuntu Linux:
sudo apt-get update
sudo apt-get install sbcl
Debian Linux:
su -
apt-get update
apt-get install sbcl

However, the standard packages have been as much as a year old, such as the ones for Debian or Ubuntu. Having those to install may be a good alternative should you run into problems with more current versions, perhaps.

Read on if you'd like current versions...

Current Versions of SBCL

Using SBCL: While the version number is merely v1.0.x, this is after six years in 0.x land following the fork from CMU CL. Think of it as really v19.0.x since the two continue to share features, fixes and user land contributions.

Select official binaries to download.

Extract to a temp directory, and install:

MacOSX or Ubuntu Linux:
export INSTALL_ROOT=/usr/local
sudo sh install.sh
Debian Linux:
su -
export INSTALL_ROOT=/usr/local
sh install.sh

Your executable will be here: /usr/local/bin/sbcl Use the --noinform flag to suppress the start-up banner.

Configuring the run-time config file for SBCL

Think of it as defining the PATH environment variable, but instead of for Bash, it's for SBCL and called *central-registry*.

Save the following as ~/.sbclrc file: 

;;;; -*- Lisp -*-
(require 'asdf)

(dolist (path '( ;"mod_remoteApp/src/"
		 ;"play.org/utils/"
		"lisp/"))
	 (pushnew `(merge-pathnames ,path (user-homedir-pathname))
		  asdf:*central-registry* :test #'equal))

(pushnew #p"/Users/Shared/lisp/" asdf:*central-registry* :test #'equal)

;; set default opimzation levels for compiling:
(declaim (optimize (safety 3) (debug 3) (speed 0) (space 0)))

It's probably bad practice to put all your projects' source locations into this path, but this is just an example to illustrate some of the possibilities.

Editors

Using Eclipse as your editor:

Most Lisp hackers use Emacs, and now many interactive features are available through an Eclipse plug-in for writing Lisp. (Example from IBM on SBCL with Eclipse)

Using Emacs as your editor:

You'll want the combination of Emacs and SLIME for interactive Lisp development and dynamic compilation.

(Also applies to commercial Lisp systems such as Lispworks use of emacsclient)

Installing Emacs -- the Lisp system that allows you to edit text!

MacOSX:

Also run:
sudo apt-get install w3m

Ubuntu Linux:
sudo apt-get install emacs w3m
Debian Linux:
su -
apt-get install emacs w3m hyperspec cltl

Lisp Interaction

Getting SLIME

Recommended: use Option 2 (below).

Option 1: Unless you have multiple developers connecting to the same very long running process where each person connects, disconnects and reconnects repeatedly, you may simply use the following.

(When prompted, select Personal installation then omit the GPG check since the default location lacks a package signature file.)

sbcl --eval "(require 'asdf-install)" --eval "(asdf-install:install 'slime)" --eval "(quit)"

Next, compile the Swank package within SLIME so it loads faster the first time you need it-- and to validate that it was properly installed!

sbcl --eval "(progn (require 'swank) (quit))"

However, SLIME versions beyond 2.0 have more robust features, so it may be worth getting directly from CVS.

Option 2: Getting SLIME directly from CVS is the recommended approach according to the Common Lisp wiki: SLIME.

Once you go down this path, however, you must ensure both your editor and deployed app have the exact same versions; otherwise, you may get prompted about mismatched protocol versions.

You'll need a location that's writable to your non-privileged user, so ~/lisp is used here.

Installing SLIME:

mkdir ~/lisp
cd ~/lisp/
cvs -d :pserver:anonymous:anonymous@common-lisp.net:/project/slime/cvsroot co slime
ln -s slime/swank.asd .
sbcl --eval "(progn (require 'asdf) (require 'swank) (quit))"

Configuring Emacs for SLIME

Put the following into your .emacs file:

(global-font-lock-mode 1)  ;enable syntax highlighting

;; possibly OS-specific values:
;(setenv "SBCL_HOME" "/usr/local/lib/sbcl") ;for non-standard location
(setq inferior-lisp-program "/usr/local/bin/sbcl"
      ;slime-path (expand-file-name "~/.sbcl/site/slime-2.0/") ;ASDF-install
      slime-path (expand-file-name "~/lisp/slime/") ;CVS version
      w3m-command "/sw/bin/w3m"   ; Fink version
      ;w3m-command "/opt/local/bin/w3m"  ; MacPorts version
      ;w3m-command "/usr/bin/w3m" ; Ubuntu or Debian version
      cltl2-url "file:///usr/local/share/doc/cltl/clm/node1.html"
      hyperspec-prog (concat slime-path "hyperspec")
      hyperspec-path "/usr/local/share/doc/HyperSpec/")

;; settings for Common Lisp development:
(setq lisp-indent-function 'common-lisp-indent-function
      ;slime-complete-symbol-function 'slime-fuzzy-complete-symbol
      slime-startup-animation nil
      common-lisp-hyperspec-root (concat "file://" hyperspec-path)
      common-lisp-hyperspec-symbol-table (concat hyperspec-path "Data/Map_Sym.txt")
      w3m-default-homepage common-lisp-hyperspec-root
      ;browse-url-browser-function 'w3m
      w3m-symbol 'w3m-default-symbol
      w3m-key-binding 'info
      w3m-coding-system 'utf-8
      w3m-default-coding-system 'utf-8
      w3m-file-coding-system 'utf-8
      w3m-file-name-coding-system 'utf-8
      w3m-terminal-coding-system 'utf-8)

(add-to-list 'load-path (concat slime-path "slime"))
(add-to-list 'load-path (concat slime-path "slime/contrib"))
(require 'slime)
;; next two lines only apply to Autumn 2007/post-2.0 versions of SLIME from CVS:
(require 'slime-editing-commands)
(add-hook 'slime-mode-hook 'slime-bind-editing-commands)
(slime-setup)

Validate that each path exists on your system, such as the value for inferior-lisp-program and hyperspec-prog.

Optional items for your .emacs file:

(add-hook 'lisp-mode-hook '(lambda () (show-paren-mode t)))

;;http://mumble.net/~campbell/emacs/paredit.html
(add-hook 'lisp-mode-hook '(lambda () (paredit-mode 1)))

(add-hook 'lisp-mode '(setq font-lock-maximum-decoration t))

;; recognize ASDF files used by newer CL systems:
(add-to-list 'auto-mode-alist '("\\.asd$" . lisp-mode))

Evaluate each of those s-expressions in order or simply restart Emacs.

You may evaluate each block within almost any Emacs buffer via the key sequence C-x C-e (Control x then Control e) on or after the closing parentheses.

The browse-url-browser-function value above references w3m, which is a web browser within Emacs. By commenting-out that line, your default web browser should launch instead. If you're a hard-core Emacs junkie, you may want your Lisp documentation delivered within Emacs, so optionally uncomment that line.

Using Emacs + SLIME + Lisp

Following the instructions above should have given you all the pieces.

Load a Lisp source file or open a new buffer with the .lisp file extension, and Emacs will have the correct mode.

When ready to work on your local Lisp code, type: M-x slime

For connecting local Emacs+SLIME to a remote Lisp app:

  1. Create SSH tunnel: ssh -L 4005:localhost:4005 user@host
  2. Then within local Emacs, type: M-x slime-connect using default values when prompted.

Within you Lisp source (other than elisp source buffer), use these key sequences:

Within your Lisp application, just add the following lines to make it SLIME-aware. (Actually, this enables the Swank service such that an editor with SLIME may connect to it.)

;; enable remote SLIME connections:
(require 'swank)
(setf swank:*use-dedicated-output-stream* nil
      swank:*communication-style* :fd-handler)
(swank:create-server :dont-close t)

MacOSX + Apache2 + mod_lisp + SBCL

More cheat-sheet than tutorial, this is the least you need to get started with hosting a web app.

(Substitutes from MacOSX to Ubuntu or Debian Linux commands should be straight-forwared based upon examples given earlier.)

Copy & paste into your Bash shell:

sudo port selfupdate
sudo port sync
sudo port install apache2 subversion wget
export PATH=/opt/local/bin:$PATH

mkdir ~/build
cd ~/build/

svn co http://www.fractalconcept.com:8000/public/open-source/mod_lisp/ mod_lisp
cd mod_lisp
sudo /opt/local/apache2/bin/apxs -i -c mod_lisp2.c

mkdir ~/lisp
cd ~/lisp/

wget http://files.b9.com/cl-modlisp/cl-modlisp-latest.tar.gz
tar zxf cl-modlisp-latest.tar.gz
ln -s cl-modlisp-*/modlisp.asd .

wget http://files.b9.com/kmrcl/kmrcl-latest.tar.gz
tar zxf kmrcl-latest.tar.gz
ln -s kmrcl-*/kmrcl.asd .

cat <<_EOF_ >> /opt/local/apache2/conf/httpd.conf
LoadModule lisp_module modules/mod_lisp2.so
LispServer 127.0.0.1 3000 "www"
<Location /lisp>
	SetHandler lisp-handler
</Location>
# don't use these: (file extensions in URLs are ugly)
#AddHandler lisp-handler .lsp
#AddHandler lisp-handler .lisp
_EOF_

##Generic## /usr/local/apache/bin/apachectl start
##Debian## apache2ctl start
sudo launchctl load -w /Library/LaunchDaemons/org.macports.apache2.plist

cat <<_EOF_ >> ~/.sbclrc
(require :asdf)
(pushnew (merge-pathnames "lisp/" (user-homedir-pathname))
	  asdf:*central-registry* :test #'equal)
_EOF_

cat <<_EOF_ > /tmp/test.lisp
;; enable remote SLIME connections:
(require 'swank)
(setf swank:*use-dedicated-output-stream* nil
      swank:*communication-style* :fd-handler)
(swank:create-server :dont-close t)
;; Start Lisp app:
(asdf:operate 'asdf:load-op 'modlisp)
(ml:modlisp-start :port 3000)
_EOF_

sbcl --load /tmp/test.lisp

Then point your web browser to http://localhost/lisp/demo

While that's running, connect SLIME to the process via Swank.

Within Emacs with SLIME, type: M-x slime-connect and accept the default values when prompted.

If, however, Apache and SBCL are running on a remote system, you'll need to connect to that server with an SSH tunnel first before using the above slime-connect command.

Run:

ssh -A -L 4005:localhost:4005 user@host

Then use M-x slime-connect within Emacs, accepting default values when prompted.

When done playing in your web browser, type the following within SLIME's REPL:

(in-package :ml)
(modlisp-stop-all)

Alternatively, hit Control-C in SBCL, as some builds seem to lack threads. Or if threads are enabled, type within the REPL prompt:
(ml:modlisp-stop-all)

Note that the URI is /lisp/demo, yet the file is found via asdf:operate method and lives within the cl-modlisp subdirectory.

Conclusion

Installation packages may have changed since this document was originally written. It must be assumed also that there are inevitably mistakes in the above text, so some effort is required on your part to ensure the file paths are correct for your particular system and preferences for installation locations.

The point of this page is to help you become operational with a Lisp system.

There is a barrier to entry with Lisp-- make no mistake. Hopefully you've found many of the obstacles are now easily navigated.

Content on this page last updated 2009-07-05; URLs verified 2009-07-05

Additions? Corrections?
contact @ play · org 
Site maintained by Daniel Pezely every now and then