The Newbie’s Guide to Learning Clojure, Part 2 – Tooling

Since learning Clojure will most often require a lot of experience in coding in Clojure, a practical consideration for any new learner will be having an effective environment for editing code, testing, deploying, etc. On the Clojure development (developer?) website, there are instructions on getting started with Clojure. I believe that these instructions are intended to be the official help resource for everyone, and people are making good effort to keep it up-to-date and authoritative. My attempt, with this post, is to formalize what I know, and then contribute over to the official documentation whatever others might find a useful addition.

I thought real hard about which editor to use for Clojure. I thought it might be through IntelliJ, but its performance didn’t match my lofty expectations. It also hadn’t been updated in a year prior to when I tried it. I then tried Counterclockwise with Eclipse, and that was nice. I didn’t enjoy the full benefit of CCW because I didn’t turn on “Structural Editing Mode” (?), which wasn’t turned on by default when I tried it. That editing mode basically borrows the benefits of paredit mode of Emacs (“parentheses editing”). CCW continues to improve, and for people most comfortable in Eclipse, and with a good enough computer to run Eclipse, that might be a good first development environment.

Thanks to Sean Corfield and others, I installed Emacs + leiningen + plugins for Clojure, and I haven’t looked back since. Basically, I echo everything that Sean suggests and says about his own experience regarding the development environment for Clojure. The following will be an detailed map of how to get up set with such an environment and why it is advantageous. A large majority of Clojure developers use this setup for their development, and not without reason.

Developing in Clojure in Emacs

A couple of installations are necessary for Clojure support in emacs and Clojure support in SLIME. clojure-mode (available as a package via the marmalade package manager) offers Clojure language support for Emacs. swank-clojure is a plugin for Leiningen that creates a Clojure REPL in server mode. If SLIME mode is installed through the slime-repl package, then swank-clojure’s command M-x clojure-jack-in will create a SLIME REPL that talks to a Clojure REPL instantiated by Leiningen. It is nice to have Leiningen run a REPL for you since it will pull in all the Java libraries into the classpath of the REPL as defined by your project.clj file (or, at least are contained in your project’s lib folder).

Without further ado, here are the instructions…

Step Why Linux Mac OS X Windows
POSIX environment [0]

comes by default (on Debian systems’ desktops, via Accessories -> Terminal) comes by default (via Utilities -> Terminal) install Cygwin (a great intro to Cygwin)
Emacs 24 beta [1] Emacs for Mac OS X [2] emacs-for-windows – Downloads
emacs-startkit v2 + clojure-mode + paredit + slime-repl [5] Follow the instructions on Installing Emacs Start Kit v2. [4]

My package list is as

(defvar my-packages '(starter-kit starter-kit-lisp starter-kit-bindings starter-kit-eshell starter-kit-js starter-kit-ruby clojure-mode)
"A list of packages to ensure are installed at launch.")

But I think it should be bound as

(defvar my-packages '(starter-kit starter-kit-lisp starter-kit-bindings starter-kit-eshell starter-kit-js starter-kit-ruby clojure-mode paredit slime-repl)
"A list of packages to ensure are installed at launch.")
Leiningen [6] Follow the instructions on the Leiningen homepage. [7] Follow the instructions on the Leiningen homepage. [7]
In addition to the Leiningen instructions, on Windows, I think you might need to set the LEIN_JAR and CLOJURE_JAR variables in your Windows environment variables. At least I did. And I added the Java and Leiningen executables to the PATH environment variable for convenience. Note that cygwin’s filesystem uses different paths than Windows to address the exact same files.
Swank Clojure [8] Follow the instructions on the Swank Clojure homepage Sean has put step-by-step instructions for how to install everything (emacs, and every Clojure-related for emacs) on Windows, and it works on Win XP. But he hasn’t formalized it into a blog post since it hasn’t yet worked on Win 7.


[0] Of course! Or, here’s a sardonic explanation of why not: The Unix Hater’s Handbook
[1] Using Emacs 24 beta+ makes emacs plugin installation much easier (the Marmalade package manager is the default package manager, and the config file naming conventions are more unified). Currently, emacs 24 is still in beta, but it is stable enough to use with confidence (even I’m satisfied). This is partly explained by the fact that Emacs version releases typically incubate for a long time. Also, Emacs Start Kit v2 is designed for Emacs 24 and onwards, not Emacs 23 [3]
[2] Taken from Phil Hagelberg’s post about Emacs Start Kit v2 [3]
[3] Phil Hagelberg’s post about Emacs Start Kit v2
[4] When installing packages, you may see Marmalade generate compiler info messages and warnings. This is okay as long as you don’t see it stop at anything saying “error” or the like. A successful installation usually says “Done” in the window’s message area (window gutter at the very bottom) Single packages can be installed indivudally using M-x package-install, and multiple packages can be installed interactively with M-x package-list-packages.
[5] Being able to use paredit mode’s basic commands (barf, slurp, splice, jump to beginning/end of block) make refatoring as painless as it possibly can be. Compared to text-editing in other languages, paredit + Lisp is close to breezy, and thus a joy.
[6] Lineingen simplifies/automates a lot of common operations necessary for a Clojure project. Ex: you have a few libs that you need to include whenever you compile/load a REPL/run a project. Leiningen automatically handles the -classpath option for java and javac, and it similarly handles options for the JVM, runs your project against various configurations, etc.
[7] I’m still using Leiningen 1.x, even though Leiningen v 2.0 is close to being released.
[8] You need swank-clojure in order to get Emacs’ SLIME mode to understand Clojure, and you also get all the benefits that Leiningen gives to your project along with it.

There are a few more resources that might be worth looking at for getting your Clojure environment set up. One is A Brief Beginner’s Guide to Clojure. I can’t tell how much the setup instructions from Relevance‘s labrepl project would be of help.

Why emacs for Clojure?

Emacs, like any other traditional UNIX text editor, has a reputation for a learning curve. But the advantages of using Emacs far outweigh the upfront investment.

What makes emacs particularly suited to programming Clojure? When there is an eternal debate about emacs vs. vi, why is vi not propped up as equivalent for Clojure? vi has Lisp/Clojure editing modes. But emacs is more suited to Lisp programming, and the fact that emacs was written in Lisp is our first hint. Emacs may have been the first widely-used Lisp program, and the power of Lisp means that there is a plugin in emacs to do nearly everything. What that means for us is that over time, a few modes have been developed that make Lisp development in emacs quite nice.

The first is paredit mode, which has a reputation of doing parenthesis judo by turning them from a perceived weakness into an actual strength. First, paredit prevents you from having unbalanced parentheses. When you type an open paren, it immediately fills in a close paren, and you try to backspace over a close paren, it forces your cursor inside and you must delete all of the contents inside until you are left with “()” before you can delete the pair. Because all parens are balanced at all times, and there is no ambiguity in how the code should be formatted, formatting is handled consistently and automatically in real time. Clojure vectors’ square brackets [], maps’ curly braces {}, and strings’ double quotes “” are treated the same way.

When it comes to navigation, there are commands to jump to the beginning / end of a S-expression, jump into / out of a S-exp, grow (slurp) a S-exp to subsume adjacent S-expressions, shrink (barf) a S-exp to give up an S-exp at an endpoint, etc. Sure, Eclipse might be able to do some of this for Java. But when you realize that you need to surround, say, a map form with a filter form, it’s as easy as

jumping to the front of (map …),

 | (map ...)

opening an empty “()” with just a ( keystroke

(|) (map ...)

typing “filter”

(filter |) (map ...)

and typing the command to slurp the map form into the filter form

(filter | (map ...))

SLIME mode for emacs allows the evaluation of Lisp forms in a REPL directly from within emacs. As soon as you finish typing, you can re-evaluate the form, the file, a selected region, etc. The way that SLIME mode works is that it spawns a REPL instance and connects from emacs to that REPL instance on a socket.

Why emacs in general?

I was scared of Emacs for a long time because when I first started using it, I started to hurt my hand in repetitively typing all of its key commands. The simple way to overcome that is to use two hands — one hand for the modifier key and one for the other key in every simultaneous pair of keys. (The most common solution to the problem is actually to configure emacs to switch caps lock and control. But I’m like Sean — I don’t find myself at too much of a loss productivity-wise using two hands, and I prefer being able to use a near-vanilla Emacs installation with ease without depending on each of my personal customizations.)

Previously, I brought up the point that Lisp is to programming what command-line tools are to getting things done on your computer. (I’m sure I’m not the first one to say that, but it was a small epiphany to come to that realization on my own.) Similarly, an analogy might best help to explain the hidden quality that makes emacs truly powerful.

First, let’s remember what it is about text editors like emacs and vi, which originated for the command line before computer mice and GUIs were ubiquitous, that makes them appealing to very skilled programmers even in today’s world of multi-touch input devices and high-res “retina” displays. Using a text editor where keys are necessary for navigation and editing means that you need to be efficient in doing your work. There is a larger variety of commands to do editing operations, especially text editing, and they let you combine the operations in limited ways to still achieve a multitude of power. For example, in vi, you can use visual block mode to easily remove the 3rd-5th characters from each line by g-g-l-l-^V-G-0-4-l-d). Furthermore, they both offer the ability to record and replay keystrokes, and because keystrokes are also our means for executing commands, we can automate a repetitive complex operation by recording it once and replaying it infinitely to the end of the file. For example, if a set of lines are all commented out by “;” at the beginning of each line, but the indentation of the “;” is non-uniform, we can record something like

  • go to the beginning of the line
  • jump to the first occurrence of “;”
  • delete the first character after the cursor
  • go to the next line
  • go to the beginning of the line (for extra measure) so as to be ready in case of a another iteration

This would look like

(human-speak) emacs vi
go to the beginning of the line C-a 0
jump to the first occurrence of “;” C-s ; [RET] F; -OR- /; [RET]
delete the first character after the cursor C-d x
go to the next line C-j -OR- [down] j -OR- [down]
go to the beginning of the line (for extra measure) so as to be ready in case of a another iteration C-a 0

The ease in which you con perform these recorded operations in emacs or vi is still non-trivial in most GUI IDEs. I will omit the commands for starting/stopping the keystroke recording, and replaying a recording a specific number of times. Apart from the analogy which I’m about to get to, you might notice a pseudo-analogy. These text editors call the recording of keystrokes “macros”. These keyboard macros are unrelated to Lisp macros in the same broken way that “JavaScript” is mistakenly though to be related to Java. Sure, somewhat similar to the equivalence of code and data in Lisp, there is the fact that text and commands are both the product of keystrokes in emacs and vi. Both Lisp macros and text editor keyboard macros are executing meta-operations, but Lisp macros are programs that write programs, while keyboard macros are just commands that execute commands.

Now, here’s where emacs can really shine. Emacs has a plugin to handle just about anything – email, git, shell, chat, etc.. And if you thought it has everything but the kitchen sink, someone has already written a plugin that displays an ASCII animation of a running sink. Some people find a lot of what they need on a daily basis in a text-based way through Emacs plugins, and that leads to the joke that Emacs is not a program running on an operating system, but rather, Emacs is an operating system, and programs run on Emacs. The true power now becomes the idea that we can switch back and forth between the different processes/documents (aka buffers) in Emacs completely using keyboard commands just like we do with documents. So if you have email open in an emacs buffer and you wanted to extract all URLs from the most recent 100 emails in your inbox, you could write a keyboard macro to copy the text of an email to a scratch buffer and go to the next email. Do this 99 times, then go to the scratch buffer. In the scratch buffer, you can iterate through to the end of the document like this: search for a URL string, when you find it, mark your position, copy the URL string, paste the URL string to a new line at the top of the document, and return back to your position marker, and advance to the next word in order to be ready for the next iteration. By the end, you should end up with a list of the URLs in the scratch buffer duplicated at the top of the buffer, one per line, in reverse order of their original occurrence. You might argue that most of that can be done through carefully-worked piped command-line commands, but in a way, since it’s more immediate and obvious to do small, complex operations in emacs, all other things being equal, isn’t that better? On top of that, plugins for emacs sometimes use sockets on the local machine’s ports to communicate with other programs running on the OS, and that’s not something you can do through a command-line easily. In short, what vi and emacs do for text editing, emacs is best suited to do for everyday tasks on a computer.

Having extolled the elegance of emacs, I should say that I limit my use of emacs to text editing (especially of Clojure) and maintain self-organization files in org-mode. I still like having a mix of hand movements and visual elements that a little interaction with a GUI OS provides, but I do realize that I am sacrificing a measure of optimal efficiency in my computer usage that emacs is probably best-suited to offer.