The following describes the packages I install when I need to set up a Clojure development environment the way I like it on a new computer running Ubuntu 10.04. These notes are mostly for my own use, but you may also find them useful.

Ubuntu Packages

We are going to need a few pieces of support software to begin development in Clojure. Assuming that we are starting from a fresh installation of Ubuntu 10.04, run the following commands in a terminal:

sudo apt-get install ant # Ant is a build tool for Java
sudo apt-get install maven2 # Maven is another build tool for Java
sudo apt-get install git-core # git is a version control system

There are many different JVMs available for Linux. By default, Ubuntu 10.04 uses OpenJDK, but many people prefer Sun’s implementation. To see what is presently installed, run:

java -version

So far, OpenJDK has worked fine for me. But, if you want to remove all evidence of OpenJDK and install the Sun implementation, try:

sudo apt-get purge openjdk
sudo apt-get install sun-java6-jdk

If you will be using Emacs, you should install these:

sudo apt-get install emacs # Emacs is the One True Editor
sudo apt-get install emacs-goodies-el # Many useful elisp files
sudo apt-get install slime # Superior Lisp Interaction ModE (SLIME)

Finally, there are some useful Java libraries which you may want to have installed:

sudo apt-get install jogl # Java Open Game Library, a useful library

Now that the packages are installed, you will want to create your directory structure and fill it with code.

Create your Clojure Directory

Everyone has their own way of keeping files organized. What follows is the directory structure I use for clojure-related things. Feel free to use whatever organization patterns you want.

~/clj/ # The home for all things clojure
~/clj/bin/ # Things executable go here
~/clj/docs/ # Things that document go here
~/clj/docs/javadoc/ # Java documentation, used by emacs
~/clj/emacs/ # For custom .el files related to clojure
~/clj/examples/ # For snippets of code collected from the 'net
~/clj/jars/ # For hand-managed .jar files
~/clj/src/ # For my own code, for other people's code
~/clj/src/clojure/ # Where clojure core code resides
~/clj/src/clojure-contrib/ # Where clojure-contrib resides
~/clj/src/leiningen/ # Where leiningen resides
~/clj/src/swank-clojure/ # Where the swank module resides
~/clj/src/MYPROJECT1 # Hypothetical MYPROJECT1 dir

The following command will create this structure for you:

mkdir ~/clj ~/clj/bin ~/clj/docs ~/clj/docs/javadoc ~/clj/emacs ~/clj/examples ~/clj/jars ~/clj/src

Populating the Directory Tree

Directories aren’t very useful without files inside them. Let’s fill the directories we just created with useful things.

First, let’s grab Clojure itself. Because features are continually being added to Clojure — as well as bug-fixes — for my purposes there is no reason not to use the latest version of Clojure. So let’s use git to get the newest version of Clojure and clojure-contrib:

cd ~/clj/src
git clone "git://github.com/clojure/clojure.git"
git clone "git://github.com/clojure/clojure-contrib.git"

Somewhat strangely, you build Clojure with the ant build tool, you build clojure-contrib with the maven build tool, but for most of the code that you will write you will use a tool called leiningen.

cd ~/clj/src/clojure
ant # Build Clojure's .jar files
cd ~/clj/src/clojure-contrib
mvn install # Build clojure-contrib's jar files

In the future, when you want to update Clojure, just pull changes from Rich’s repository:

cd ~/clj/src/clojure
git pull # Pull the latest version from the repository
ant # Rebuild clojure's .jar files
cd ~/clj/src/clojure-contrib
git pull # Pull the latest version from the repository
mvn # Rebuild clojure-contrib's .jar files

It’s a good idea to test Clojure at this point. The basic method of interaction with a Clojure (and many other lisps) during development is through a REPL (Read Eval Print Loop). REPLs are great because they let you interact with the language in a very fine-grained way, without the annoyance of having to compile each time you want to test your code.

You can fire up a REPL by adding the clojure jar to the classpath — the ‘-cp’ argument given to the JVM which specifies where in the filesystem the JVM can look for usable .jar or .class bytecode files — and calling clojure.main:

cd ~/clj/src/clojure
java -cp clojure.jar clojure.main

Voila! You should now have a Clojure REPL! Anything you type into the REPL will be read, evaluated, and the results printed immediately. This is a great way of getting feedback from the computer about your code as you go along. Try typing something into the REPL, such as this example from the Clojure Getting Started Page:

user=> (+ 1 2 3)
user=> (. javax.swing.JOptionPane (showMessageDialog nil "Hello World"))

Take a few moments to play around with your new friend. When you are done, exit the REPL by pressing Ctl+D (end of file), or if you are less polite, Ctl+C (interrupt signal) to directly kill the jvm.

Leiningen

The third and final build tool is called Leiningen. It is basically a wrapper around the maven build tool that lets us specify dependencies and build procedures using clojure code instead of xml expressions. It is trying to put a friendly face on the huge, mighty beast called maven.

Leiningen is easily installed by downloading a small script to ~/clj/bin/lein, setting it to executable, and asking it to install itself.

cd ~/clj/bin
wget http://github.com/technomancy/leiningen/raw/stable/bin/lein
chmod 755 lein
./lein self-install

Leiningen will take a few moments to download some jars and place them under ~/.m2 where maven-related files will be stored. This is normal behavior of the beast called maven.

For convenience, it’s a good idea to add the ~/clj/bin directory to your bash $PATH, so that any scripts in this folder can be executed from anywhere and we can type just “lein” instead of “~/clj/bin/lein”.

echo 'PATH=$HOME/clj/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Now you can check that Leiningen is installed:

cd ~/clj
lein version

If you see some version information, congratulations!

Emacs Files

Emacs connects very well with Clojure using Slime and Swank. In the end, the connection between you and the hardware looks like this:

User<->Emacs <-> SLIME <->Swank-clojure<->clojure<->JVM

For the unfamiliar, Slime is a program for hacking lisp that runs in Emacs, and swank is a server program that lets you interact deeply with Clojure. Breaking that down a bit:

  • Users type code into Emacs, using clojure-mode (and paredit-mode for convenience)
  • Emacs use the SLIME mode to send user’s code over a socket
  • The swank server listens on a socket, and gives it to Clojure
  • Clojure takes data from the swank thread, compiles it to bytecode
  • The JVM executes the bytecode
  • Unhandled exceptions, debugging information, etc all propogate in the other direction as needed, of course.

Now that we know what swank is — and because we installed slime using apt-get at the beginning of this guide — let’s install swank-clojure:

cd ~/clj/src
git clone git://github.com/technomancy/swank-clojure.git
git clone git://github.com/technomancy/clojure-mode.git

Although Emacs package manager ELPA can install things automatically, I prefer to manage my emacs lisp files myself for sheer simplicity.

cd ~/clj/emacs
wget "http://mumble.net/~campbell/emacs/paredit.el"
wget "http://nschum.de/src/emacs/highlight-parentheses/highlight-parentheses.el"
cp ~/clj/src/clojure-mode/clojure-mode.el ./
cp ~/clj/src/swank-clojure/swank-clojure.el ./

Finally, you will need to configure emacs to use some of these files.

Alternate Method: ELPA

Emacs, like most good operating systems (such as Ubuntu), has a package manager to help install extra functionality. Emacs’ package manager is called ELPA, and can be done from within emacs following these instructions, which amount to pasting the following in the *scratch* buffer, placing the cursor after the last parenthesis, and pressing C-j:

(let ((buffer (url-retrieve-synchronously
"http://tromey.com/elpa/package-install.el")))
(save-excursion
(set-buffer buffer)
(goto-char (point-min))
(re-search-forward "^$" nil 'move)
(eval-region (point) (point-max))
(kill-buffer (current-buffer))))

That was it. Emacs installed ELPA by itself, and you can now launch ELPA from within emacs by typing:

M-x package-list-packages

Scroll down the list that appears, tapping ‘i’ to select packages you want to install. Finally, then hit ‘x’ (for execute) to install everything at once. Useful packages you would be interested in include: clojure-mode, gist, htmlize, paredit, slime, and w3.

Resources:

  1. Bill Clementson’s post describing his clojure setup (old, but interesting).
  2. Installing Clojure, Emacs, Slime, and Swank on Ubuntu linux.