Where to start with your Clojure adventure? You’re lucky because there are published books that are available now. Unfortunately for the beginning learner, they gloss over the very first real steps; once you get a REPL running, they’re done. This is step 1.1.

My assumption is that you are new to Clojure, but you know Java and perhaps Maven. Since Clojure runs on the JVM, you need to a Java development kit 1.5 or later already installed.

In this article you will configure Clojure’s build tool Leiningen and use it to start a REPL. Inside the REPL – the Read Evaluate Print Loop – you execute your Clojure code. That is all we’re doing here: installing Leiningen and getting it to execute a REPL. In another article, I show you how to use
the Emacs with Leiningen.

Getting Clojure

Yes, you can download it and you can run a REPL with the jar.

$ java -cp clojure-1.3.0.jar clojure.main
REPL started; server listening on localhost port 57274
user=> (+ 2 2)
4
$

Or, if you just want a taste, you can just try Clojure online.

But honestly, in real life you are going to be using some sort of build tool. So, why not just start there? Coming from Java you may have used ANT or Maven. You can use Maven with Clojure, but if you’ve spent as much time as me whacking away at pom.xml files, you may be open to something different. Even if you just want to hack away in a REPL, I suggest you install Leiningen.

Leiningen

Leniningen is “Maven for Clojure.” It even uses Maven repositories. It is also an easy way to just get started hacking at Clojure. The instructions to install Leiningen are straightforward – download a shell script, put it in your path, and execute it. Then run the self-install target.

$ cd /to/a/directory/that/is/in/your/PATH
$ curl -O https://raw.github.com/technomancy/leiningen/stable/bin/lein
$ chmod 755 lein
$ lein self-install

This will create a directory named ~/.lein that will contain configuration and lein plugins. Take a look if you want, but you don’t have to.

The first thing I suggest that you do with Leiningen is to create a new project.

$ lein new lein01
Created new project in: /Users/gene/clojureprojects/lein01
$ cd lein01
$ lein classpath
/Users/gene/clojureprojects/lein01/test:/Users/gene/clojureprojects/lein01/test-resources:/Users/gene/clojureprojects/lein01/src:/Users/gene/clojureprojects/lein01/classes:/Users/gene/clojureprojects/lein01/resources
$

Go ahead and examine the directory/file structure. It is similar to a Maven project. project.clj is your pom.xml, but it is in Clojure instead of XML.

1
2
3

(defproject lein01 "1.0.0-SNAPSHOT"
  :description "FIXME: write description"
  :dependencies [[org.clojure/clojure "1.2.1"]])

Running lein deps will create a lib directory in your project and copy the dependencies specified in your project.clj into it. The contents of the lib directory will be appended to your classpath.

$ ls lib
ls: lib: No such file or directory
$ ls
README		classes		project.clj	src		test
$ lein deps
Copying 1 file to /Users/gene/clojureprojects/lein01/lib
$ ls lib
clojure-1.2.1.jar
$ lein classpath
/Users/gene/clojureprojects/lein01/test:/Users/gene/clojureprojects/lein01/test-resources:/Users/gene/clojureprojects/lein01/src:/Users/gene/clojureprojects/lein01/classes:/Users/gene/clojureprojects/lein01/resources:/Users/gene/clojureprojects/lein01/lib/clojure-1.2.1.jar

Now, assuming you are in the project directory, simply type the following:

$ lein repl
REPL started; server listening on localhost port 33198
user=> (+ 2 2)
4
user=> (doc +)
-------------------------
clojure.core/+
([] [x] [x y] [x y & more])
  Returns the sum of nums. (+) returns 0.
nil
user=>

You now have a REPL with your project’s classpath all set up. Since you haven’t touched project.clj yet, that doesn’t really matter right now, but it will when you start to add dependencies.

You really don’t have do any further setup to start playing with Clojure. Grab a Clojure book/tutorial and whack at the REPL. Control-D to quit. Eventually though, you will probably want an editor.

Displaying the classpath inside the REPL

We’ve seen the classpath from the command line using lein classpath. But once we are inside a REPL, how do you discover the classpath? There are several libraries under the rubric “contrib” that are outside Clojure proper. Until recently, contrib was one huge monolithic jar. It is now separate projects. One of these contrib projects is named java.classpath. Some details are on the project’s home page. and you can read the documentation.

The first thing we need to do is to update the project.clj file and add a new dependency like this:

(defproject lein01 "1.0.0-SNAPSHOT"
  :description "FIXME: write description"
  :dependencies [[org.clojure/clojure "1.2.1"]
 		[org.clojure/java.classpath "0.2.0"]
		])

Then update your dependencies with lein. Several repositories are tried until the jar is found.

$ lein deps
Downloading: org/clojure/java.classpath/0.2.0/java.classpath-0.2.0.pom from central
Downloading: org/clojure/pom.contrib/0.0.21/pom.contrib-0.0.21.pom from central
Downloading: org/clojure/clojure/1.3.0-alpha6/clojure-1.3.0-alpha6.pom from clojars
Downloading: org/clojure/clojure/1.3.0-alpha6/clojure-1.3.0-alpha6.pom from jboss
Downloading: org/clojure/clojure/1.3.0-alpha6/clojure-1.3.0-alpha6.pom from jboss-public-repository-group
Transferring 5K from jboss-public-repository-group
Downloading: org/clojure/java.classpath/0.2.0/java.classpath-0.2.0.jar from central
Copying 2 files to /Users/gene/clojureprojects/lein01/lib
$

Now you can start your REPL and use a function, cunningly named “classpath” from this contrib library.

$ lein repl
REPL started; server listening on localhost port 12414
user=> (use 'clojure.java.classpath)
nil
user=> (clojure.java.classpath/classpath)
(#<File /Users/gene/clojureprojects/lein01/test> 
#<File /Users/gene/clojureprojects/lein01/src> 
#<File /Users/gene/clojureprojects/lein01/classes> 
#<File /Users/gene/clojureprojects/lein01/lib/clojure-1.2.1.jar> 
#<File /Users/gene/clojureprojects/lein01/lib/java.classpath-0.2.0.jar> 
[...details deleted])
$

Wrap up

Next step? You probably want a good editor. Lispers have used the Emacs for decades. You should give it a try. Here is how.

Resources

Books

Clojure Programming
Programming Clojure
Clojure in Action
The Joy of Clojure: Thinking the Clojure Way
Practical Clojure (Expert’s Voice in Open Source)
On Lisp: Advanced Techniques for Common Lisp