# Clojure Programming/Getting Started

This page walks you through the steps required to setup a usable Clojure environment. You will:
* Install Clojure
* Install several standard enhancements to Clojure
* 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:
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
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
or run a script with
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:
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:
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:
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:
Then to compile using Ant:
or with Maven:

### 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
or
To get out of it, press
* Ctrl+C on Windows
* Ctrl+D on UNIX, Linux and Mac OS X
or type:
For more usage options:
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
or
and you get the usage options with

## 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:
If you are on Ubuntu, you can install the JLine library like so:
Run 'dpkg -L libjline-java' to check the name of the library. On Ubuntu 8.0.4 you'll see something like this:
Then run:
If you want to run a script from the command line:

### 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 rlwrap.
It adds the following features to the Clojure interactive shell.
* Tab Completion
* Parenthesis matching
* History across Clojure sessions
* 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).
Save the following bash script as clj and add it to your path after making it executable:
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:
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 ~/.inputrc:
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
This REPL also remembers the symbols created by you:
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.

### 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:
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:
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 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.
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/.