How to set up Clojure

The first time I set a Clojure development environment up on Linux, I followed the instructions. Next time, on MacOS, I had to start all over again because I hadn’t made notes. This page is a reminder of what is needed and why. I recommend you to read to the end of the page before you start then get your computer on the Internet and fetch what you need. You should check for yourself if anything I say is true because I’m relatively new to Clojure.

Clojure works well, interactively, inside a Read-Execute-Print-Loop (REPL.)
When I first started, I got a REPL by installing a tool called Leiningen then typing:

lein repl

at the command line interpreter (bash.) There is now a simpler way to get started, known as the ‘CLI Tools’ which handle software dependencies differently, using a deps.edn file, described here: https://clojure.org/guides/deps_and_cli.
My computer that runs default Debian/Gnome didn’t have curl or rlwrap installed, nor sudo, so I used su to install them.

You now start a REPL by typing:

clj

On a slow machine, it starts noticeably faster than leiningen.

https://clojure.org/guides/getting_started talks about the ‘CLI Tools’ first then mentions the more complex Build Tools, Leiningen & Boot at the bottom of the page. It’s not yet entirely clear how these alternatives will be made to work together but I would guess Leiningen will adapt in some way, to work with deps.edn.

If you want to do things the Leiningen way,

Install Leiningen

On Ubuntu and Debian Linux, I put leiningen under $HOME/bin which, if it exists, gets added to $PATH automatically by the default .profile. On macOS there was no .profile so I followed the suggestion of putting it in /usr/local/bin which was already on the $PATH.

I started learning Clojure from the book Clojure for the Brave and True, which “longs for you to own it” but is available in HTML on the Internet, to get you started.

Clojure

It tells you where to install Clojure from and how to get a new version of Java if you need it. I tried using the Clojure from a Linux repository but it was very old. The recommended way then was to install Leiningen, which downloads the clojure.jar file containing the Clojure compiler which runs on the Java Virtual Machine. Clojure doesn’t mind which operating system you choose.

ClojureScript

If you see any mention of ClojureScript, that is a related language that compiles to JavaScript in the brower, instead of to the JVM. I won’t mention that any further, for now.

Running a REPL

The book tells you how to start a REPL with Leiningen and run some simple code:

http://www.braveclojure.com/getting-started/

It suggests a choice of editors but recommends emacs. The emacs editor is written in the eLisp dialect of Lisp and can be connected by CIDER to provide another way to get a REPL, running inside emacs. Learning emacs is going to be a big investment of your time. You can get started with the ‘CLI Tools’, any editor you already like and cut and paste between them.

The next chapter, http://www.braveclojure.com/basic-emacs/ explains how to install emacs for your operating system and offers you a download file from the book’s web site, to customise the editor to match the book. After teaching you how to use emacs, it explains how to set up cider, to allow the REPL to open inside emacs.

If you want a better understanding of the relationship between emacs, the REPL and Cider, then see the Cider manual http://cider.readthedocs.io/en/latest/. Cider replaced an earlier tool called Slime which you no longer require.

Pi issue, as of 20/11/2016:

I have the above configuration running on Ubuntu on a slow Atom processor but an update to Raspbian Linux on my Raspberry Pi 2 caused leiningen to fail to start. It took a VERY long time to start up before, so I suspect it got even longer for some reason so the ‘lein repl’ activation is timing out.

The error message is ‘REPL server launch timed out.’

I could create the app directory structure with
lein repl new app appname

I tried increasing the time-out to 2 minutes in the project.cli by adding

:repl-options {
;; If nREPL takes too long to load it may timeout,
;; increase this to wait longer before timing out.
;; Defaults to 30000 (30 seconds)
:timeout 120000
}

That didn’t work but I discovered a workaround by starting the REPL first:
lein repl :headless

which reports:
OpenJDK Zero VM warning: TieredCompilation is disabled in this release.
nREPL server started on port 43903 on host 127.0.0.1 – nrepl://127.0.0.1:43903

then connecting to the remote REPL from another terminal:
lein repl :connect 127.0.0.1:43903 (port number is different each time, so take note of it)

OpenJDK Zero VM warning: TieredCompilation is disabled in this release.
Connecting to nREPL at 127.0.0.1:43903 (as noted above)
REPL-y 0.3.7, nREPL 0.2.12
Clojure 1.8.0
OpenJDK Zero VM 1.7.0_111-b01
Docs: (doc function-name-here)
(find-doc “part-of-name-here”)
Source: (source function-name-here)
Javadoc: (javadoc java-object-or-class-here)
Exit: Control+D or (exit) or (quit)
Results: Stored in vars *1, *2, *3, an exception in *e

user=> (+ 1 3)
4

Both take ages to start so it’s possible the 120s time-out still isn’t long enough.

How I DIDN’T install Clojure

Via the Linux distribution repositories, which are out of date.

On Raspbian, Clojure was at 1.6, whereas 1.7 was current. Leiningen is at 1.7.1-2 but needs to be 2.x. Therefore I was forced to download from the Internet.

Clojure and Leiningen are hosted on the Java Virtual Machine rather than running directly on the operating system. They need at least Java 1.6.

If you don’t have enough ways to get a REPL, a minimal Clojure can be downloaded and unzipped to a .jar file and executed at the command line with

java -cp clojure-1.8.0.jar clojure.main

to provide Clojure’s in-built REPL, instead of using the nREPL provided by Leiningen.

See http://clojure.org/guides/getting_started

Leiningen requires Java to be pre-installed but uses the Apache Maven Java tool to provide Clojure. ‘deps.edn’ makes Maven more visible than Leiningen did.