Setting Up a Project
Clojure runs on the JVM so you need a recent JDK version installed (Java 6 or newer should do).
To create a new Clojure project we use Leiningen. On Mac OS it’s just a
This will install Leiningen 2. Version 2 breaks compatibility with the old plugin system, but most projects that supply Leiningen have a description how to add them to your project.clj for each version. However if you start a new project, always go with Leiningen 2.
To create our getting started project (we will name it greenfield-clojure) run:
This will create a new folder. For the rest of this writing all file paths will be relative to this folder.
You should see a
project.clj file looking something like this
1 2 3 4 5 6
As you can see Clojure itself is defined as a dependency. As of this writing the latest version is 1.5.1 .
which will download and install all specified dependencies.
During this project we will add additional dependencies to this project. CloJars is a repository for Clojure libaries. There you can find a lot of interesting stuff. You can also include Java dependencies from Maven Central. Please consult the Leiningen sample.project.clj for further information.
The REPL is a interactive environment where you can run Clojure code, in the context of your project.
To start a REPL run:
This will also download and install all dependencies that are given in the project.clj.
Now we can start and enter a simple hello world into the repl:
Setting Up Your Editor
Sublime Text 2
I started out, using Sublime Text 2. It’s a good start. I can recommend installing SublimeREPL. Clojure development uses the REPL extensively, so your editor should come with some kind of REPL integration.
I found SublimeREPL to be less stable as I would have liked. So I switched to vim.
One of the best editors for Clojure is Emacs, but I just can’t get used to it :). All Emacs folks out there: please leave plugin recommendations in the comments, I will integrate them.
As mentioned above I switched from Sublime to vim, because of its better REPL integration via the fireplace.vim plugin, proved to be more stable.
Once your setup is complete you will be able to send the complete file or single calls - under the cursor - to the REPL. Make sure this works. We will use it in the future of this tutorial. You can of course just continuously copy and paste the snippets to the REPL by hand. However that is very tedious and time consuming.
You want to use the REPL, because restating the JVM, just to execute one file, takes seconds, which makes for a very frustrating feedback cycle.
While you are at it you might also want to install rainbow_parentheses.vim. It will highlight matching parenthesis in the same color, while giving each pair an individual color.
Files and Namespaces
If you followed the tutorial and have created the greenfeld_project you will
find a file called
This is the default starting point.
The first line of the file should look like this:
ns creates the new namespace
Namespaces in Clojure have to respond to the file structure.
Given a namespace
greenfield-clojure.domain.user it will look for a file in
Notice that it uses
_ for file names and
- for the namespaces.
Lets create a new clj file:
Following the naming schema we start a fitting namespace for that file by adding:
All the following definitions will go into that namespace.
Now lets add a simple greeting function:
1 2 3 4
In the same namespace you can make a test call:
If you have your REPL going just put the code below the function definition itself and send it to the REPL for evaluation. You can remove the code afterwards.
This way you can quickly sketch together some code and move and refactor later.
If you use the REPL via command line you can switch to this namespae (or any other valid namespace) by calling:
Using Code from other Namespaces
We don’t just want to create namespaces, we want to use stuff that is
located in other namespaces. We can do so by useing
use will include all the vars (function definitions are just vars that point
to functions) into the current namespace.
This will NOT pull vars the used namespace itself includes via
None the less: this pollutes you namespace and it gets harder to avoid clashes
and find where functions are defined.
However if you want to use clojure core namespaces - for example - it sometimes
makes for nicer code.
Here we include
clojure.set operations with the
Notice that we need to quote the namespace, using a
This is useful when working in the REPL itself, but when you write files it’s
better to include this in the
ns call directly useing
We have seen that
use, while nice in some cases, pollutes our namespace.
Instead we use
require. Let us require our util namespace from the core
Now this is very cumbersome. Instead we can include everything we want to
require directly in the
With our utils library required, we can call its functions like this:
In clojure the
/ is used to reference vars from a different namespace.
Thanks to Pierre Mariani for pointing out that if you want to include
every var from another namespace into the current namespace like
you can and should use the following variant of require:
1 2 3 4 5
Or if you want to refer everything from the namespace replace
I admit the hole requiring other namespaces is confusing. But I can also promise you that all the other stuff is much more thought thou and has more of a theme to it. Now if you are interested or still confused Colin Jones explains requiring code in more detail.
Executing from the Command Line
Util now we only executed our code using a REPL, but at some point in time we will want to start our program from the command line.
There are two ways to do this:
- use leiningen
- package everything up into one big jar file
In any case our main namespace must contain a
-main function that takes
a variable number of arguments:
This will just always print the same greeting.
Running with Leiningen
Using leiningen we can call:
-m tells Leiningen which namespace to use for execution.
The namespace must include a
- before the main.
We can also specify the main namespace in our
1 2 3 4 5 6 7
Now we can omit the
-m ... part:
Creating an Uberjar
We can use Leiningen to package everything up into one big jar that can be executed very simply.
For that we have to set the main namespace (same thing we did above):
1 2 3 4 5 6 7
But because this will be called directly, we have to tell clojure that it should
compile the clojure code into a java class when creating the jar.
To do this add a
(:gen-class) argument to the
1 2 3
This is call AOT (Ahead of Time Compilation). It’s sufficient to do this for the main namespace only. You should be careful with this. In case implementations of core clojure functionality change your ATO compiled code might not be compatible without a renewed compilation.
A call to
will create a standalone jar in the
Run it via
We have done it!
In this tutorial we:
- setup and installed clojure from scratch
- fired up a REPL for interactive development
- configured our favorite editor (if it is Sublime or vim ;) )
- learned how the file structure matches up to namespaces
- how to create our own namespace
- how to include code from other namespaces
- we used leiningen to run our code from the command line
- bundled everything up in one nice care-free jar that can be pushed around the computing world
I hope this tutorial was helpful or interesting.
Any feedback is much appreciated.