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

Mac OS X

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 [1] 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).

Running Clojure

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

• Ctrl+C on Windows
• Ctrl+D on UNIX, Linux and Mac OS X

or type:

   (System/exit 0)

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:

    :: Setup:
    :: 
    :: 1. Change the constants to match your paths
    :: 2. Put this clj.bat file on your PATH
    ::
    :: Usage:
    ::
    :: clj                           # Starts REPL
    :: clj my_script.clj             # Runs the script
    :: clj my_script.clj arg1 arg2   # Runs the script with arguments

    @echo off

    :: Change the following to match your paths
    set CLOJURE_DIR=D:\clojure-1.2.0
    set CLOJURE_JAR=%CLOJURE_DIR%\clojure-1.2.0.jar
    set CONTRIB_JAR=%CLOJURE_DIR%\clojure-contrib-1.2.0.jar
    set JLINE_JAR=%CLOJURE_DIR%\jline-0.9.94.jar

    if (%1) == () (
        :: Start REPL
        java -cp .;%JLINE_JAR%;%CLOJURE_JAR%;%CONTRIB_JAR% jline.ConsoleRunner clojure.main
    ) else (
        :: Start some_script.clj
        java -cp .;%CLOJURE_JAR%;%CONTRIB_JAR% clojure.main %1 -- %*
    )

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

    java -cp %CLOJURE_DIR%\jline-VERSION.jar;%CLOJURE_JAR% jline.ConsoleRunner clojure.main

would become

    java -cp "%CLOJURE_DIR%\jline-VERSION.jar;%CLOJURE_JAR%" jline.ConsoleRunner clojure.main

Enhancing Clojure REPL with rlwrap

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

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 rlwrap. It might also be available as a part of you package repository for your GNU/Linux distribution. Ensure that rlwrap 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 clj and add it to your path after making it executable:

    #!/bin/sh
    breakchars="(){}[],^%$#@\"\";:''|\\"
    CLOJURE_DIR=~/clojure
    CLOJURE_JAR="$CLOJURE_DIR"/clojure.jar
    if [ $# -eq 0 ]; then 
         exec rlwrap --remember -c -b "$breakchars" \
            -f "$HOME"/.clj_completions \
             java -cp "$CLOJURE_JAR" clojure.main
    else
         exec java -cp "$CLOJURE_JAR" clojure.main $1 -- "$@"
    fi

Note that this script uses rlwrap and not JLine. The file ~/.clj_completions is the file rlwrap will use for providing tab completions.

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

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

(def completions (keys (ns-publics (find-ns 'clojure.core))))

(with-open [f (java.io.BufferedWriter. (java.io.FileWriter. (str (System/getenv "HOME") "/.clj_completions")))]
    (.write f (apply str (interpose \newline completions))))

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

(def completions (mapcat (comp keys ns-publics) (all-ns)))

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

   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 clj

   [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.

Editors/IDEs

Official Instructions for various IDEs

See the [2] 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 VimClojure plugin from the previous section, Ctrl-N 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 .vimrc. Note that the completions generator script is already available as a part of the VimClojure plugin.

Once you have the file ~/.clj_completions add the following line to your ~/.vimrc.

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

With this setting you should be able to use Ctrl+N in insert mode to see possible completions. For example, takeCtrl+N will show take-while, take-nth and take 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/.