Clojure is the new hotness among people who think the JVM is an interesting platform for post-Java languages, and for people who think there’s still life in that ol’ Lisp beast, and for people who worry about concurrency and state in the context of the multicore future. Over the last few days I’ve been severely bipolar about Clojure, swinging from “way cool!” to “am I really that stupid?” Herewith some getting-started tips for newbies like me.

This is almost certainly not interesting to anyone except those who are already interested in Clojure, and to one other group: those who might want to package up a programming language in such a way that learning it will be straightforward.

Background · I understand the JVM and Java package structures reasonably well. I am by no means a Lisp hacker, my experience being limited to a few thousand lines of elisp, mostly to cook my own idiosyncratic XML editing mode that I’m using as I write this.

What To Read · Before I started, I read most of Mark Volmann’s Clojure — Functional Programming for the JVM, and bought the PDF of Stuart Halloway’s Programming Clojure from the Prags, although I’d only read the Concurrency section in any detail.

Neither is great, but both are OK, and with addition of another resource, will get you what you need. That other resource is the Clojure source code, which provides tons of examples of how-to-do-X; go grepping around in $CLOJURE/src/clj/... and you’ll strike gold.

REPL! · You just really can’t do any exploratory programming in a dynamic language without a REPL, as in Read-Evaluate-Print Loop. Unlike Ruby, Clojure doesn’t come with a precooked readline-equipped REPL, but you can get a primitive one going in a simple shell script.

Don’t do that though, get yourself some IDE help. Emacs and NetBeans are both plausible choices, because Emacs is already Lisp-centric and NetBeans knows about the acres of gleaming Java machinery that is holding this whole thing up.

IDE · I saw there was a NetBeans plug-in called Enclojure, so I went and got that from wherever Google took me. Don’t do that! Get whatever’s the latest from github.

Enclojure’s install documentation is a little baffling. I liked the idea of having a REPL right there in the IDE, so I followed the link and it expected me to understand what the difference between “managed local” and “remote unmanaged” and “standalone” REPLs were, and it wasn’t obvious what I’d need to download. I eventually convinced myself that I wanted a “Project REPL” and it turns out that you get that with the plug-in.

Here are the basic things you need to know before you can do anything with the Project REPL:

Right-click in your code buffer and select “Change REPL to file/ns”. Otherwise Nothing Will Work.

When you hop over to the REPL (command-T on the Mac flips back & forth), you have to do a “Load File” (control-L on the Mac) so that the REPL will know about your functions. Otherwise Nothing Will Work. I wasted literally the best part of a day trying various weird incantations so that I could define a function foo and say (foo) in the REPL. It’s worse, because the “Load File” option isn’t advertised when you right-click in the REPL.

Once you get past this stuff, Enclojure seems like a rather good (if young) IDE front-end for Clojure. And the REPL has all the command-line editing and history you could want. But it should be easier to get started.

Namespace Hell · I noticed when I made a Clojure project, taking all the defaults, some ceremonial arm-waving at the top of the file:

(ns org.tbray.paralines (:gen-class))

So I went to read up on this ns thing, and, well, it’s a maze of twisty little passages, all different. There’s ns and in-ns and use and require and import , except for ns takes :require and :use and :import clauses, which are said to be better.

Some of them are forms and some of them are macros, and eventually you come to the sickening realization that this is essentially your old friend CLASSPATH Hell, which evidently is not improved by the application of S-expressions.

The documentation in all the sources I could find shares the assumption that you understand what’s going on and leaps directly into the finer points. I have no fucking idea what’s going on, but I managed to spelunk through the Clojure sources and steal enough working samples to get my code to run.

On the other hand, I haven’t yet had the courage to try to distribute my code across more than one file.

Asking For Help · There’s a (very quiet) #enclojure IRC channel, and a rather high-quality Google group, where I was able to get some problems answered with archive searches.