in which are found tricks of the trade concerning clojure authorship

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 $HOME/.emacs.d/init.el) so it will work for future sessions. Deprecated in favour of similar functionality in swank-clojure.

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.

« older | 2009-05-28T00:35:46Z | newer »