Clojure Programming/Getting Started

This page walks you through the steps required to setup a usable Clojure environment. You will:
 * 1) Install Clojure
 * 2) Install several standard enhancements to Clojure
 * 3) Configure Clojure for use with an IDE or text editor

Once these steps are complete, you'll be ready to start coding.

Installation
To give Clojure a test drive, without having to perform an installation, point your (reasonably up-to-date) web browser to http://www.try-clojure.org/. There, you can interact with a REPL (read-eval-print loop) to get a feel for Clojure's interactive environment.

To move beyond baby steps, you will need your own installation. The following sections provide installation instructions for various systems. In addition, check out the official Getting Started page on the Clojure wiki: http://dev.clojure.org/display/doc/Getting+Started

The easiest way to start with Clojure is to just download ClojureW from here: http://bitbucket.org/kasim/clojurew/get/tip.zip Just unzip it to your directory of choice and in that directory, run: clojurew/bin/clj

For platform specific installation, please follow below instruction:

Windows
The easiest installation option for Windows users is Clojure Box. A video installation guide for Clojure Box is available at http://vimeo.com/9219062. Note: Clojure Box is not maintained anymore and last version support Clojure 1.2, it doesn't support 1.3 very well 2012-02-17

An up-to-date alternative is Lisp Cabinet, which supports Clojure up to at least 1.5.1. 2013-06-04

Using MacPorts
Users running Mac OS X can install Clojure automatically using MacPorts. If MacPorts is not already installed, first go to macports.org and follow the directions there to install it.

Once MacPorts is installed, Clojure can be installed by issuing the command sudo port install clojure +rlwrap

The "+rlwrap" part of the command can be left off (or changed to "+readline), but it is recommended, since it will include JLine and rlwrap for better history support in the REPL. Once Clojure has been installed with MacPorts, you can enter the REPL with the command

clj

or run a script with

clj myscript.clj

If Clojure is installed this way, the steps below related to creating a "clj" script and enhancing the REPL with JLine or rlwrap do not need to be performed.

Using Homebrew
You can also use homebrew for easy installation of Clojure. To install Clojure through homebrew, first download homebrew through the homebrew webpage at and install it following the guide there.

Once installed you can install Clojure through using the command:

brew install clojure

No sudo required. To enter the REPL just write "clj" into the terminal.

Debian GNU/Linux and Derivatives
On Debian-based systems, the easiest way to install Clojure is to run:

sudo apt-get install clojure1.2

This installs the Clojure jar with a bash script to make command-line invocation easier. The access for this is a little different from other methods. To run a Clojure script just call:

clojure script-name.clj arguments to script

Invoking without script name and arguments opens the REPL.

Note: This installs version 1.0. To install a newer version of Clojure, you must use one of the following methods:

Installing a JAR
On systems that don't support apt-get or if you need a version newer than 1.0, the easiest way to start with Clojure is to download the zip file available here. However, Clojure is under active development, and you may want to download and build from source.

Installation from Source
You need Git to download the latest source code. To compile you need the Java Development Kit (javac) and either Maven (mvn) or Ant (ant). The examples below use ant to run the build, but mvn may be used in its place.

You can download the latest code using:

git clone git://github.com/clojure/clojure.git

Then to compile using Ant:

cd clojure ant

or with Maven:

cd clojure mvn package -DskipTests

Additional Installation Options
There are currently many pre-packaged options available for installing Clojure, including:
 * Cljr : Provides a Clojure REPL and package manager.
 * Dejour : Package consisting of: Clojure, clojure-contrib, JLine, and a startup script.
 * labrepl : Web application package containg multiple libraries as well as exercises.
 * ClojureX : Includes Clojure, clojure-contrib, JLine, and a very full-featured startup script (this was unmainted for a while but is under active development again since 04/2011).

With version 1.6.0
you start a clojure REPL with java -cp clojure-1.6.0.jar clojure.main or java -jar clojure-1.6.0.jar

To get out of it, press or type: (System/exit 0)
 * Ctrl+C on Windows
 * Ctrl+D on UNIX, Linux and Mac OS X

For more usage options: java -cp clojure-1.6.0.jar clojure.main --help

If you get errors use "-cp ./clojure-1.3.0.jar" or put the current directory "." into your CLASSPATH.

With old versions up to 1.2.1
you start the eval loop with java -cp clojure.jar clojure.main or java -jar clojure.jar and you get the usage options with java -cp clojure.jar clojure.main --help

Enhancing the Environment
In this section we explain how to install some standard enhancements to Clojure. You can either use rlwrap or JLine with the Clojure REPL to get functionality, like being able to press the up arrow to retrieve the previous command.

Enhancing Clojure REPL with JLine
Download JLine.

There is some problem with jline 1.0 on ubuntu and some version of OSX where the retrieving the previous line will not take into account the offset created by the prompt So jline 0.9.94 is preferred. Copy the jar into the clojure directory. Then you can run:

java -cp jline-VERSION.jar:clojure.jar jline.ConsoleRunner clojure.main

If you are on Ubuntu, you can install the JLine library like so: sudo apt-get install libjline-java libjline-java-doc

Run 'dpkg -L libjline-java' to check the name of the library. On Ubuntu 8.0.4 you'll see something like this:

$ dpkg -L libjline-java /.   /usr/share/java /usr/share/java/jline-VERSION.jar

Then run:

java -cp /usr/share/java/jline-VERSION.jar:clojure.jar jline.ConsoleRunner clojure.main

If you want to run a script from the command line:

echo '(println "Hello, World")' > hello-world.clj java -cp clojure.jar clojure.main hello-world.clj

Create clj Script
A clj script is a convenient script to launch your clojure applications. Each of the recipes below depends on the jline library being installed.

Unix
There is a bash script included in Contrib.

Windows
For Windows users, here's the suggested clj.bat BATCH file:

Note: If clojure is installed to a path with spaces, you will need to put the places where the variables are in quotes. Thus,

would become

Enhancing Clojure REPL with rlwrap
To enhance the Clojure REPL under Unix variants, one very useful utility is.

It adds the following features to the Clojure interactive shell.
 * 1) Tab Completion
 * 2) Parenthesis matching
 * 3) History across Clojure sessions
 * 4) Vi or Emacs binding based on your readline .inputrc settings

As a first step build and install. It might also be available as a part of you package repository for your GNU/Linux distribution. Ensure that  version 0.30 or above is in your path (previous versions have issues with multiline prompts).

[cljuser:~]% rlwrap -v rlwrap 0.30 [cljuser:~]%

Save the following bash script as  and add it to your path after making it executable: Note that this script uses  and not JLine. The file  is the file   will use for providing tab completions.

Also, note that the file  in the script should refer to whatever is the name of the jar built by either ant or maven. Ant builds.

The following Clojure program can be used to generate the completions file:

To generate completions for all the standard Clojure namespaces (not just 'closure), substitute the first line of that code with the following definition.

At this point you are good to go. Here are the settings from :

set editing-mode vi   tab: complete set completion-ignore-case on   set blink-matching-paren on

For the Vi key bindings, the user can use  for jumping to matching parenthesis in the interactive shell. For Emacs bindings the keys are 'M-C-f' ('forward-sexp') and 'M-C-b' ('backward-sexp').

Invoke the REPL as

[cljuser:~]% clj Clojure user=> (de --> tab   Desktop/      defmethod     defstruct     deref    dec           defmulti      delay         derive    definline     defn          delay?        descendants    defmacro      defn-         destructure    user=> (def --> tab definline defmacro   defmethod  defmulti   defn       defn-      defstruct user=> (take- --> tab   take-nth    take-while    user=> (take-

This REPL also remembers the symbols created by you:

[cljuser:~]% clj Clojure user=> (def foo 10) #'user/foo user=> (def foobar 20) #'user/foobar user=> (def foo-next 30) #'user/foo-next user=> (fo --> tab   foo       foo-next  foobar    for       force    user=> (fo

Happy REPLing!

User settings
clojure.lang.Repl will run all the files listed before it goes to the prompt. So I have my clj script updated to accept a .cljrc.clj file that has my settings. (set! *print-length* 50) (set! *print-level* 10)

Installing clojure.contrib
Clojure contrib is a common library for Clojure. Several projects depend on it, so it should be one of the first things you install. It is currently only available in source form, so check it out as follows:

git clone git://github.com/richhickey/clojure-contrib.git

Use Apache Maven to build by typing "mvn package" in the clojure-contrib subdirectory. Add the newly built clojure-contrib.jar from the "target" subdirectory to the classpath in your startup script:

java -cp $CLOJURE_JAR:$CONTRIB_JAR clojure.main

Or skip building the clojure-contrib.jar and add clojure-contrib/src/main/clojure to your classpath instead.

Official Instructions for various IDEs
See the section on the official Clojure wiki.

Emacs
See the instructions in the Clojure documentation.

Vim
The state of the art in using Vim to edit Clojure code is the VimClojure plugin (recently merged with the Gorilla plugin, and depends on having a Ruby-enabled Vim (a Windows build of vim including Ruby support can be found here)).

With VimClojure set up, you have:
 * syntax highlighting (including rainbow parens) and indenting
 * a REPL buffer inside Vim (with command history, highlighting and indenting)
 * the ability to evaluate code from your program
 * documentation lookup, omni-completion, and more

Gorilla is in active development (particularly to remove the Ruby dependency), but is very stable and useful.

Both VimClojure and Gorilla were created by, and are maintained by, Meikel Brandmeyer.

Some notes on these plugins:
 * Two (out of date) screencasts can be viewed: VimClojure and Gorilla.
 * A more UpToDate-Screencast can be found at: Installing VimClojure
 * Installation instructions are included at the plugin pages. Note that Gorilla comes with a file gorilla.jar that needs to be in your classpath when you run Gorilla.
 * The way to use Gorilla is this: run it (so that a REPL server is in operation), then open a Clojure file in Vim. \sr will start a REPL buffer; \et will evaluate the expression under the cursor; see :help gorilla.txt for more.

Completions
If you are using the  plugin from the previous section,   completions should work for you out of the box and you don't really need to bother with this section.

However, if you are using the bleeding edge Clojure from the sources, there may be some additions / changes to the API. If this is the case, you would need to generate an updated list of completions for Clojure. This can be created using the Clojure script from section Enhancing Clojure REPL with rlwrap. Once generated this completions file may be linked into your VimClojure plugin or you could update your. Note that the completions generator script is already available as a part of the  plugin.

Once you have the file  add the following line to your.

au Bufenter,Bufnewfile *.clj setl complete+=k~/.clj_completions

With this setting you should be able to use  in insert mode to see possible completions. For example, Ctrl+N will show ,   and   in a drop-down list.

Other ways to communicate with a REPL from Vim
If you are unwilling or unable to run Gorilla, there are two other ways you can access a Clojure REPL from Vim.

Chimp is the precursor to Gorilla. It uses screen to send text to a running REPL. It is far less convenient that Gorilla, but better than nothing.

This article describes exactly the same basic idea as Chimp, but is a more lightweight plugin.

As these two approaches rely on Screen, they are essentially available on Unix-like (including Cygwin) systems only.

Eclipse
There are a couple Eclipse plug-ins for Clojure development, the most prominent one being Counterclockwise.

NetBeans
A NetBeans plugin is available from the Enclojure project, http://www.enclojure.org/.