Learning Clojure/Installation

As of writing, Clojure lacks a standard installer for Windows, and a few packages exist for popular *nix Operating Systems. Although, all examples presented work exactly the same across all systems, regardless of what type of installation you choose.

Base Installation

A Base Installation is a minimal install that provides all of the capabilities of the Clojure language, but without a GUI or additional interfaces for assistance. Installation with this method has several low level tasks that are not difficult to perform, but may seem difficult to those that have never manually installed a program on a system before.

Steps

First you should confirm that the Java VM is installed on your machine. This can be easily checked by going to a terminal and typing java -version. If it returns something about your java version, you should be set. If it does not, then you will need to download the Java VM from the Java website .

After you've confirmed that Java is installed on your machine, obtain the most recent version of Clojure from the main Clojure website [1]. This book was written and tested for Clojure version 1.2 (Stable). The file you have downloaded will be a zip file containing several files which are explained in detail in the section Source Install. The file we want is clojure.jar.

Take this file and extract it to any directory of your choice. As this point, you will have a successful installation of Clojure on your machine! All you need to do is to open a command window and type change your directory to where you extracted clojure.jar and type java -jar clojure.jar and you'll be greeted with the Clojure REPL.

Mind you, this is a lot of work just to start Clojure, so we will create a script for each OS that will run the program with a single command and also add this program to the PATH, making the program easily accessible for execution at any time.

Windows Configuration

First, we need to create a script to run Clojure without the excessive typing. This tutorial assumes that you unzipped clojure.jar to C:\Development\Learning Clojure, and that the below bat file is named clj.bat The below script does just that.

 rem File: clj.bat
 rem Version: 1.0
 rem Date: 2010OCT31
 rem 
 rem Script based off of the Wikibooks Clojure Programming Getting Started.
 rem Source: http://en.wikibooks.org/wiki/Clojure_Programming/Getting_Started#Windows_2
 rem
 rem Usage:
 rem
 rem clj                           # Starts REPL
 rem clj my_script.clj             # Runs an external script
 rem clj my_script.clj arg1 arg2   # Runs the script passing it arguments
 
 @echo off
 
 :: Change the following to match your paths
 set CLOJURE_DIR=C:\Development\Learning Clojure
 set CLOJURE_VERSION=1.2.0
 set CLOJURE_JAR="%CLOJURE_DIR%\clojure-%CLOJURE_VERSION%.jar"
 
 if (%1) == () (
     :: Start REPL
     java -server -cp .;%CLOJURE_JAR% clojure.main
 ) else (
     :: Start some_script.clj
     java -server -cp .;%CLOJURE_JAR% clojure.main %1 -- %*
 )

Let's break this down into blocks.

The first few lines that begin with rem are comments. They're present to serve as a reminder of how this bat file works. The next block says that you do not want to see the output of this bat file. This removes command line "noise" when you start Clojure. The next block defines where you installed Clojure and prepares the arguments for when we launch it. Note that the CLOJURE_JAR variable is written in quotes. This is because Java recognizes a space as an end of argument. Thus, without the quotes, the Java command will try to run C:\Development\Learning, which is invalid.

Finally, we have a conditional. The conditional checks to see if there was an argument passed (in our case a clj file). If one was not passed, we will run Clojure's REPL. If one was passed, we will run the passed clj file and also pass any additional arguments to the script.

So we now have our clj.bat which we can run Clojure from easily. Now let's add it to our PATH so that we can execute Clojure from any directory on your system.

This can be done by the following.

1. Click Start
2. Right Click My Computer
3. Select Properties
4. Click the Advanced tab
5. Click on Environment Variables

If you wish to install this just for the current user, Underneath the "Variables for User" frame, find PATH. If PATH doesn't already exist, click the new button. You'll be greeted with a popup window with the variable name and arguments. For the arguments field, add C:\Development\Learning Clojure. If some value already exists, go to the very beginning and type the same thing, immediately following with a semicolon. Finally click Ok on the Variable Properties screen and Ok again on the Environment Variables Screen.

If you wish to install this for every user on your system, locate the PATH variable underneath the System Variables and perform the same steps as above.

At this point, your system should be set up to run Clojure from any directory. To try it out, click on Start, Run, and then type in clj. You should be greeted with the Clojure REPL.

Leiningen on windows

Leiningen is a automating tool for clojure. Like Maven for Java, it provides easy and configurable environment for compilation, execution and distribution functionality. It also provides standard convention and project structure. You can download leiningen from https://github.com/technomancy/leiningen, it comes with a batch file and wget.exe for downloading rest of the tool. Site's github page has the details on installation and usage.

Linux/OSX Configuration

Linux and OSX users follow a similar scripting process to the Windows setup. Below is the script needed to run Clojure:

#!/bin/bash
# File: clj
# Version: 1.0
# Date: 2010OCT31
#
# Usage:
#
# clj                           # Starts REPL
# clj my_script.clj             # Runs an external script
# clj my_script.clj arg1 arg2   # Runs the script passing it arguments
CWD="/opt/Learning Clojure"
if [ $# -eq 0 ]; then 
  java -server -cp ${CWD}/clojure.jar clojure.main
else
  java -server -cp ${CWD}/clojure.jar clojure.main $1 -- "$@"
fi

You should now mark the file as executable by typing chmod a+x clj.bat, and add this directory to your path. This can be done either by a static link to /usr/bin or changing the value of PATH in your .bashrc.

You should now be able to run the Clojure REPL by typing clj at the command prompt.

Integrated Development Environments (IDE)

Clojure has a few IDEs that makes development easier by providing additional features and utilities. The first and foremost benefit to using an IDE for development is having an all-in-one package. The IDE is your editor, it is your compiler, and it is your build system. The second benefit is that external tools become available, such as source version control systems like Mercurial, Git, and Subversion. Also, IDEs generally make learning a language easier and faster, because most tasks are standardized.

There's also some problems with using IDEs. Using an IDE typically results in a vendor lock-in. If you've written code in one particular IDE, you're not likely to switch to another. Another problem is that IDEs provide a lot of functionality, but sometimes restricts you in areas, such as choosing between Make, Maven, and Leiningen for your build system.

As of writing, there are three major IDEs for Clojure, all which work across Windows, Linux, and OSX.

Enclojure (Netbeans)

Enclojure is a Netbeans sponsored project which covers a wide array of features.

Counter Clockwise (Eclipse)

Counter Clockwise is a Eclipse plugin which brings a different look at how Clojure could be integrated into an IDE.

Swank Clojure (Emacs)

Swank Clojure is a clone of the venerable Slime interface for programming Lisp in Emacs.

These instructions come from: http://riddell.us/ClojureSwankLeiningenWithEmacsOnLinux.html, however that location is not a wiki and there are small fixes that it needs, so I'm copying what was there with those small fixes.

What follows is a description of how to get up and running in Ubuntu.

Install Java

~$ sudo apt-get install sun-java6-jdk

NOTE: If using Lucid Lynx (10.04) or later (and possibly some earlier versions), you will need to first change the apt-get repository so that sun-java6-jdk is available:

~$ sudo add-apt-repository "deb http://archive.canonical.com/ maverick partner"

(where "maverick" is the adjective descriptor of your ubuntu version ("lucid" for lucid lynx, "maverick" for maverick meerkat, etc.))

~$ sudo apt-get update

Install Ant

~$ sudo apt-get install ant

Install Maven

~$ sudo apt-get install maven2

Install Git

~$ sudo apt-get install git-core

Install Clojure

~$ mkdir ~/opt
~$ cd ~/opt
~$ git clone git://github.com/clojure/clojure.git
~$ cd clojure
~$ ./antsetup.sh
~$ ant
~$ mkdir ~/.clojure
~$ cp clojure.jar ~/.clojure

• Test Clojure, Gentlemen, start your REPLs.

~$ cd ~/.clojure 
~$ java -cp clojure.jar clojure.main
user=> (+ 1 41) 
42 
Ctrl-d will exit the REPL.

Install clojure-contrib

~$ cd ~/opt 
~$ git clone git://github.com/clojure/clojure-contrib.git 
~$ cd clojure-contrib 
~$ mvn install 

Configure Bash Start-up Script

clojure-contrib contains a bash script called clj-env-dir for starting clojure with various options. Edit your ~/.bashrc file to configure this script.

export CLOJURE_EXT=~/.clojure
export PATH=$PATH:~/opt/clojure-contrib/launchers/bash
alias clj=clj-env-dir

The last line added to the file above sets an alias to the clj-env-dir script. This example uses clj but it could be set to anything.

See the file at ~/opt/clojure-contrib/launchers/bash/clj-env-dir for options.

Add JLine support

Download JLine from http://jline.sourceforge.net/ and unzip and copy jar to the ~/.clojure directory.

Add jline.ConsoleRunner to the last line in ~/opt/clojure-contrib/launchers/bash/clj-env-dir to add JLine functionality.

exec $JAVA $OPTS jline.ConsoleRunner $MAIN "$@"

• Test the Script

To test the new script and verify access to the clojure-contrib library, open a new terminal window and try this:

~$ clj
user=> (System/getProperty "java.class.path")

If any other jars are needed either copy or link them to the ~/.clojure directory.

Emacs support

Install Emacs

~$ sudo apt-get install emacs-snapshot-gtk

Install Slime

~$ cd ~/opt
~$ git clone git://github.com/nablaone/slime.git

Install clojure-mode

~$ cd ~/opt 
~$ git clone git://github.com/technomancy/clojure-mode.git

Install leiningen

~$ cd ~/opt
~$ git clone https://github.com/technomancy/leiningen.git
~$ cd leiningen/bin
!$ chmod +x lein; ./lein self-install  # or maybe just ./lein is enough

Add the following to .bashrc.

export PATH=$PATH:~/opt/leiningen

Execute the leiningen script.

~$ chmod +x lein
~$ ./lein self-install

Configure Emacs

Add these specifics to the .emacs file.

;; clojure-mode
(add-to-list 'load-path "~/opt/clojure-mode")
(require 'clojure-mode)
;; slime
(eval-after-load "slime" 
  '(progn (slime-setup '(slime-repl))))
(add-to-list 'load-path "~/opt/slime")
(require 'slime)
(slime-setup)

Test Configuration

Create a test project.

~$ mkdir ~/tmp
~$ cd tmp
~$ lein new test-project
~$ cd test-project
~$ emacs project.clj

Add the following:

(defproject test-project "0.1.0"
 :description "Test Project"
 :dependencies [[org.clojure/clojure "1.2.0-master-SNAPSHOT"]
                [org.clojure/clojure-contrib "1.2.0-SNAPSHOT"]]
 :dev-dependencies swank-clojure "1.2.1")

Save and exit the file.

~$ lein deps
~$ lein swank

Open a new terminal and open the generated file in emacs:

~$ emacs ~/tmp/test-project/src/test_project/core.clj

Connect to the running swank server:

M-x slime-connect

Add some code to the file:

(System/getProperty "java.class.path")

And then at the end of the line, evaluate:

C-x C-e

The output will show the configured jar files and their associated paths on the Java classpath.

Lastly, compile the file:

C-c C-k

Source Install

Installation on windows is slightly complicated if you have never modified environment variables or dealt with command-line operations. You will need either the Sun JDK or OpenJDK packages installed on your computer, and you will also need to have Maven installed before attempting this process.

doc

Documentation for the Clojure project.

script

Test scripts used when building from source

src

Java code that your version of Clojure was built on (see Source Install)

test

Test scripts that is run when you build Clojure from source

build.xml

Build file for Ant compilation

changes.txt

Recent changes log.

epl-v10.html

The Eclipse Public License

install

a Bash script that runs the installation for Clojure

pom-tempalate.xml

Build file for Mavin compilation

readme.txt

Contains essential information that you should read before installing