Clojure Setup

An always up to date guide to setup Clojure with Emacs.

Setup last checked: July, 13th, 2011

Update: Phil Hagelberg describes a very easy way to set up Clojure in his blog. It's a nice alternative to the stuff you will find below.

This started as a resource for myself to document my setup, but I thought it could help others too. This is intended to be a guide to really understand the underlying setup, opposed to a "copy and paste various commands"-guide you find on every random corner on the net.

Before we start, let me point you to the Clojure Development wiki, where the Clojure devs maintain an always up to date guide to different IDEs for Clojure. In my guide, I will focus on Clojure with Emacs on Ubuntu/Debian.

This setup will include the following tools:

Clojure

Clojure comes in one .jar Java file, but we don't need to download it explicitly. Later, it gets downloaded after setting the dependencies of the Leiningen project or by using the swank-cloure server.

The current stable version of Clojure is 1.2. But there is a quite stable but not production ready alpha version (1.3), which you can use for hacking and testing Clojure. But, as always, things can change in the development version, so be careful.

Emacs

First we need to install Emacs. On Ubuntu or Debian, get it with apt-get / aptitude: 

  sudo apt-get install emacs emacs-goodies-el

The emacs-goodies-el packages comes with many additional Emacs major-modes and extensions. For this guide, most of them are of no use, but it's nice to have them if you need other modes for other projects / languages.

Next we need the infamous package.el, a nice little tool to download custom emacs packages from different repositories. If you are using Emacs 24 or newer, you can skip this step because package.el is already included. Ubuntu 10.10 (Maverick) and 11.04 (Natty) include Emacs 23.x, so download it from technomancy's Github repository: 

  https://github.com/technomancy/package.el/raw/master/package.el
The original package.el from Tromey is not useful here, because it doesn't support different package repositories.

Next you need to add an additional repository. Just enter your .emacs file (normally located in your home directory) and insert the following line: 

  (add-to-list 'package-archives '("marmalade" ."http://marmalade-repo.org/packages/"))
Now execute the following command in Emacs (press M-x) to fetch and display the contents of the default and the added repository: 
  package-list-packages
Locate the packages named clojure-mode and slime-repl, press I with the cursor in front of each of them and press X to install these two packages. Nevermind any compile warnings, they are normal and do not affect the package installation.

clojure-mode provides syntax highlighting, indentation and support for swank/slime (see below) for Emacs. slime-repl is a REPL (read-eval-print loop) for Lisp, which works with Clojure as well. Just think of it as an interactive shell to type code into and execute it instantly (like the Python shell or Bash).

Using an older slime-repl package from your Linux package manager or one installed manually may cause problems. Use the one found with package.el to prevent problems and delete/remove the older ones.

That's it for Emacs, next up is Leiningen and the connection between Emacs and the Clojure REPL running in it's own process (swank-clojure).

Leiningen and swank-clojure

Leiningen is a build tool for Clojure. With it you can start Clojure projects, declare dependencies, fetch those dependencies, test your code, create .jar files and many more. Leiningen also has a plugin system, and one plugin for it is swank-clojure, a SLIME server running in it's own process you can connect to from inside Emacs.

Installing Leiningen is different, but easy. Download this script, place it in your PATH (add export PATH=/path/to/script/:$PATH to your .bashrc) and make it executable (chmod +x). That's it. It will be downloaded and installed the first time you use it. For more information about the usage consult the Leiningen manual.

Now we need to install the swank-clojure plugin. The command 

    lein plugin install swank-clojure 1.3.0
will do it. There are two ways to start the server, either manually or with Leiningen: 
    ~/.lein/bin/swank-clojure
(you can also add this directory to the PATH) or 
    lein swank
Now, inside Emacs, connect to the server with 
    M-x slime-connect
and, et voilá, you have a Clojure REPL inside Emacs. There are some useful commands to interact between your code in one buffer and the REPL in the other: 
    C-c TAB: Autocomplete symbol at point
    C-x C-e: Eval the form under the point
    C-c C-k: Compile the current buffer
    C-c C-l: Load current buffer and force dependent namespaces to reload
    M-.: Jump to the definition of a var
    C-c S-i: Inspect a value
    C-c C-m: Macroexpand the call under the point
    C-c C-d C-d: Look up documentation for a var
    C-c C-z: Switch from a Clojure buffer to the repl buffer
    C-c M-p: Switch the repl namespace to match the current buffer
    C-c C-w c: List all callers of a given function
(taken from here).

Previously, you had to delcare swank-clojure as a dev dependency in the Leiningen project.clj, but since lein-swank now comes witr Swank Clojure, this is not needed anymore.

Done!

So, that's it. You now have a solid Clojure development setup at your fingertips. Start a new project with Leiningen (lein new), fire up Emacs and swank-clojure, connect to it and start hacking.