Telman Yusupov’s Blog

These series of posts describe how I setup Clojure development environment on my system. Even though these instructions are geared towards Mac users, they should work for other Unix-like systems with small (if any) changes. I hope it saves some time to anyone new to Clojure.

I broke the series into 3 parts:

Basic Clojure Setup – Part 1: Installing Clojure
Basic Clojure Setup – Part 2: Getting Clojure to work with Emacs/SLIME
Basic Clojure Setup – Part 3:  Staying up-to-date

This article is Part 1 – Installing Clojure. We’ll cover

• installing prerequisite software
• optional adjustments to Java on OS X
• configuring required system variables
• getting Clojure itself and clojure-contrib library
• using better command line interaction facilities

Update (25-SEP-2009): since I wrote the original article in February 2009, Clojure development repository moved from Google Code to Github. I’ve updated the article to reflect this change based on Jeff Stern’s comment.

I’ve accumulated this information mostly by googling around and reading Clojure’s Wikibooks entry and Bill Clementson’s excellent blog.

Part 1 – Basic Clojure Setup

1. Get JDK
Clojure runs on JVM, so you will need to download the latest JDK from Sun (for Windows and Linux) or Apple (on OS X).

2. Optional – configure Java 6 (Mac only)
I prefer using Java 6 instead of Java 5 that Apple exposes by default. It’s only available in 64 bit version and runs fine on any recent Core 2 Duo Intel Macs.

I’ve discovered that it has better CPU utilization on my Macbook Pro, especially when running concurrent apps (like Ant colony simulation created by Rich Hickey).

Java 6 is not enabled by default and you have to do it manually by going to Applications/Utilities/Java/Java Preferences and dragging Java 6 into the top spot.

3. Other Required Software
a. Install git. As Clojure is still in active development, using version control tools is the best way to keep up with the latest and greatest.
b. Install Ant – this utility is necessary to compile Java projects. You might already have it on your system -  type ant on your command line to check.
c. Another Java tool that will be needed to compile clojure-contrib and is used by Leiningen (Clojure build tool) is Maven. Get it here, if it’s not already installed on your system (type mvn to check).

4. JAR file directory
JAR files are Java libraries that can be used by other Java programs. In effect, Clojure itself is a JAR file run by JVM. It’s important to make sure that Java knows where to find these JAR files on your system.

I found that keeping all of the JARs (or symbolic links to them) in one directory is a great way to keep things organized. So, I’ve created /opt/jars directory for this purpose.

mkdir /opt/jars

5. Configure CLASSPATH variable
Once you have JDK installed, you need to configure the CLASSPATH variable so that your Java installation knows where to look for JAR files to execute. It’s somewhat similar to the regular PATH variable but for Java.

Add the following to your personal profile file (.login or .profile or .bash_login file in my case).

On old JDKs (before 1.6) you had to either list all of the JARs individually (huge pain!) or use something like this script (borrowed from from Eric’s Lispcast blog entry) to build it interactively:


# Build Classpath interactively for earlier versions of Java.
# Assumed JAR file location is /opt/jars directory - change appropriately for yourself
# Make sure to use backquotes (`) on the first line
for i in `ls /opt/jars/*.jar`
do
CLASSPATH=${CLASSPATH}:${i}
done


However, starting with version 1.6 you can specify the directory only without having to list each file individually:

CLASSPATH=/Users/tyusupov/clojure-code:/opt/jars/*

/Users/tyusupov/clojure-code is where I keep my own Clojure code. Change this to your directory, so that Clojure knows where to find your files. Also, note that I put /opt/jars/* at the end – this way I don’t get any compilation errors from other Clojure libraries.

Test your CLASSPATH setup to make sure that you see all of your JAR files:

echo $CLASSPATH

6. Create Clojure directory
As I already mentioned, I like to keep things organized and keep everything Clojure related in one directory. In my case it is /opt/clojure

mkdir /opt/clojure

7. Get Clojure
Here we’ll
- Check out the latest development version from the Subversion Github repository
- Compile it using ant
- Create a symbolic link to the newly created clojure.jar in /opt/clojure directory, so that Java knows where to find Clojure.


cd /opt/clojure
git clone git://github.com/richhickey/clojure.git clojure
cd clojure
ant
ln -s /opt/clojure/clojure/clojure.jar /opt/jars/clojure.jar


8. Get clojure-contrib
Clojure-contrib is the official library for Clojure contributions and has a lot of very useful stuff. You’ll definitely need it!


cd /opt/clojure
git clone git://github.com/richhickey/clojure-contrib.git clojure-contrib
cd clojure-contrib
mvn package
ln -s /opt/clojure/clojure-contrib/clojure-contrib.jar /opt/jars/clojure-contrib.jar


9. Test it!
Go to your command line and try to run Clojure by typing:

java clojure.main

If you have setup everything correctly then you should see Clojure’s prompt:

Clojure
user=>

Try the obligatory Hello World example:

>(println "Hello, Clojure World!")

Output:

Hello, Clojure World!
nil
user=>

10. Better command line interaction
Now you have access to Clojure’s REPL (command line interface), but it’s not very friendly to work with: it has no command history and other goodies that we are used in other shell environments.

There is a utility called JLine that can help us with it. Download it from http://jline.sourceforge.net, unpack it and copy jline-0.9.94.jar (or whatever the latest version is) to your JAR directory (/opt/jars in my case).

Paste this little script into a new file and call it something like clj and save it in a directory that is in your PATH variable:


#!/bin/bash

if [ -z "$1" ]; then
java jline.ConsoleRunner clojure.main
else
java clojure.main $1
fi


Don’t forget to add execute privilege:
chmod +x clj

If you run this script with no arguments, you will have a nice command line access to Clojure. You can also run a Clojure script by passing an argument to this script, i.e.


> echo '(println "Hello, Clojure from script!")' >> hello.clj
> clj hello.clj


Hello, Clojure from script!

Now you are ready to use Clojure. In the next couple of posts I’ll describe how to use Clojure with Emacs and Slime as well as setup Clojure and its libraries for easy updates.