So it turns out getting set up to write Clojure code can be a little tricky. There are a lot of disconnected tidbits about how folks have figured out how to configure things, but it can be a bit tricky to tell the difference between, "hey, this is how I finally got it to work" and "this is how you really should be doing it". I figure I know about as much about using Clojure with Emacs as anybody, so here's a run-through of how I've done my setup. There are a lot of moving parts, but bear with me; most of the installation is automated.
Update: This is all super old and you should just use Monroe instead.
The Pieces
- ELPA
- The Emacs Lisp Package Archive functions as a centralized store for Emacs libraries and provides automated installation and upgrades.
- clojure-mode
- This gets you syntax highlighting, indentation, and other basic goodies for editing .clj files.
- SLIME
- The Superior Lisp Interaction Mode for Emacs was originally written to support interacting with Common Lisp subprocesses from within Emacs, but it's been extended to work with other lisps.
- swank-clojure
- An adapter for SLIME that allows it to work with Clojure.
- clojure-test-mode
- This provides support for running Clojure tests from within Emacs buffers and seeing the results displayed inline.
- paredit
- Paredit auto-balances parentheses and other matched chars to make sure you don't end up with structurally invalid expressions.
Installation
The easiest way to get started is to grab ELPA. If you
use Emacs
Starter Kit you've already got ELPA. (If you're new to Emacs,
you might want to use the Starter Kit anyway as a base for your
own customizations; also check out
the PeepCode
screencast.) Use M-x package-list-packages to pull
up the package list. Move down to clojure-mode and
press i to mark it for installation, then
press x to go.
Once it's installed you should be able to work with .clj files, and you may be happy with just this. It has rudimentary subprocess support with M-x run-lisp, which is good enough for many, including Rich Hickey, the creator of Clojure. But most of us find it much more convenient to interact more richly with a running Clojure process as we code.
Pressing M-x clojure-install will kick off the
Clojure installation process. Once you choose a download location,
it will download a number of repositories and compile Clojure
itself, so it will take a few minutes. (It requires having git,
Java 1.5+, and ant installed.) When it's done, it will configure
SLIME and swank-clojure, and it will give you instructions on a
few lines to add to your personal config (usually found
in Deprecated in favour
of similar functionality in
swank-clojure.$HOME/.emacs.d/init.el) so it will work for future
sessions.
Usage
Hitting M-x slime will launch a new Clojure session in
a *slime-repl* buffer. You can also interact with
the *inferior-lisp* buffer, but the slime-repl buffer provides
a higher-level interface with a few extra niceties. The REPL
works as you'd expect, but you can hit , to activate
some shortcuts, the most useful being i to change the
current namespace (with tab-completion) and restart.
Back in your .clj buffers, C-x C-e has been rebound to execute the form under the point in Clojure instead of Elisp. This is handy, but you won't get accurate line numbers from stack traces involving functions loaded this way. Pressing C-c C-k will load the entire file and ensure stack traces come through accurately.
As you type out function calls, you should see their argument
list show in the minibuffer. This is called eldoc, and
it's a great way to get a quick refresher about what a function
expects. For full documentation lookup you'll need to get handy
with C-c C-d d though. Finally you can
use M-. to jump to the definition of any given
function.
Projects
Of course, after a while you'll be done with just playing at the
REPL and want to hack on a real project. Since the JVM doesn't
allow you to modify the classpath at runtime, you need to specify
up front where it should look for code. The simplest thing to do
is add src/, test/, lib/,
and classes/ (for AOT compilation, if desired)
directories in your project root to the classpath. Then you place
your dependency jars in the lib directory. If
you've got complicated dependencies, you could
use maven to
manage them, but if you've only got a couple it's not hard to
do by hand.
Use Leiningen
for dependency management and other build needs.
Invoking M-x swank-clojure-project will prompt you for a project root and start SLIME with the classpath configured appropriately.
Tests
If you've written automated tests for your project using
the clojure.test library (which you should), you can
use clojure-test-mode to run them. Install it
via M-x package-list-packages, and then you can
use C-c C-, to run the tests in the current
buffer. Failures and errors get highlighted, so if you want to see
details about a failure, move the point to the red region and
press C-c C-'.
Happy Hacking
I hope this is helpful and clears up some confusion. Now get out there and write some code.
Update: If you are using Slime with both Clojure and Common Lisp, refer to the instructions at http://felipero.posterous.com/1446961.
๛