ben vandgrift · on living the dream

Clojure: Getting Started

(Mac OS X and Windows)

Getting started with Clojure is mostly a matter of installing the tools you'll need. This quick guide covers Windows and Mac. We'll also try to provide some rationale for why things are the way they are we move along.

The Mac instructions assume you'll be using Mac OS X 10.8+, and that you've installed Homebrew. While the instructions are expected to work for any homebrew installation, they've only been tested on 10.8 and 10.9.

We're also providing instructions for Windows without Cygwin or MSysGit.

Install Java

Clojure runs on the Java Virtual Machine (JVM for short) as do all of its component parts, so the first thing you'll need to get Clojure off the ground is a JVM, which means installing Java. You can download Java from Oracle. You'll want to get the Java Development Kit (JDK) not the Java Runtime Environment (JRE) and you'll want something recent, at least version 6.

You'll also need to ensure that the Java program is in your path.

If you want a bare-bones installation, read the next section. If you'd rather have a dependency management and build tool right off the bat, skip ahead to 'Leiningen'.

Minimal Installation

A minimal install of Clojure will provide you with enough material for some basic experimentation. Download Clojure 1.6.0 from Maven Central. You can also view a list of all available versions here. Sources and JavaDoc downloads are also available.

With this minimal install, you'll be able to run Clojure via java:

# start a REPL
java -server -cp path/to/clojure/jarfile clojure.main -r

# run a .clj file
java -server -cp $CLASSPATH clojure.main some_file.clj

# execute some stuff
java -server -cp $CLASSPATH clojure.main -e '(print "Hello!")'

You might want to create a shell alias or batch file to help with these. For example, in Mac OS X, you'd add the following to your .bash_profile:

export CLASSPATH=$CLASSPATH:path/to/clojure/jarfile
alias clj="java -server -cp $CLASSPATH clojure.main $*"
alias cljc="java -server -cp $CLASSPATH -Dclojure.compile.path=classes/ clojure.lang.Compile $*"

From the prompt, you could then (for example) start a REPL with:

clj -r

You could also compile your clojure files into .class files (placed in the classes/ directory with:

cljc my.namespaced.thing

This assumes that the existence of my/namespaced/thing.clj relative to the current directory.

As mentioned earlier, this is fine for noodling around and getting to know the basic syntax. At some point, however, you are going to want to build things with dependencies and not worry about managing classpaths and such.

You can build your own system up to a point, with a bin/ directory containing scripts for building and whatnot. If you're familiar with Maven you may want to use Mark Derricutt's clojure-maven-plugin.

Probably, though, you'll want Leiningen.

Leiningen

Leiningen 2 (lein) is a project packager and dependency management tool used by the Clojure community. You'll be depending on lein to create, package, or deploy Clojure projects. You'll be in good company, as lein is the most prevalent build and dependency management tool currently in use.

It has a reasonably informative README.md and tutorial, which you should briefly review.

Clojure proper is installed alongside Leiningen. It puts everything (including Clojure) where it needs to be when you use it to create a project.

Mac OS X

You can download the install script, make it executable, place it on your path and run it, or you can use Homebrew. If you're already using Homebrew to manage software, that's the route you should take:

brew install leiningen

Windows

If you have curl or wget installed, setting up Leiningen on Windows simply requires downloading the batch file, placing it on your path, and running lein self-install. This is the simplest way to install, and it's likely you'll want these programs at some point. Of the two, we found that wget is a bit easier to install. Get the prebuilt version, install it and make sure that wget.exe is on your path.

If for whatever reason you don't have these programs and don't want them, you will still need the batch file, but you'll also need to visit the Leiningen downloads page and get the standalone .jar file for the version you want. Save that file somewhere on your file system (we recommend %USERPROFILE%/.lein/self-installs for compatibility with future upgrades), and create a %LEIN_JAR% environment variable with that location.

A Word about Editors

An editor should give you the most leverage for your effort. Providing you with a pleasant and efficient development experience is it's only job.

There are many within the Clojure community that demand you use emacs to be taken seriously, but emacs has a daunting learning curve, and undertaking that challenge while learning a new language is a recipe for frustration. Ignore them, and use whatever works for you.

Once you've hit your stride with Clojure, you may want to re-evaluate your editor and choose something that fits your style more closely. Until then, stick with what you know.

Updates

written: Mar 14 2014