Appendix. Installing Clojure

You have a few options for installing a Clojure compiler and read-evaluate-print loop (REPL) to run Clojure code. (A REPL is a programming language’s interactive command line, like a command prompt or terminal shell.) We’ll survey some options in this appendix, and you can find more options at Clojure’s Getting Started page (http://clojure.org/). But most people will want to install Clojure via the project management tool Leiningen (see section A.3).

In almost every case you’ll first need to install Java 1.6 or greater. To check if you have Java installed, open a command prompt and type the following:

$ java -version
java version "1.8.0_20"
Java(TM) SE Runtime Environment (build 1.8.0_20-b26)
Java HotSpot(TM) 64-Bit Server VM (build 25.20-b23, mixed mode)

If you get an error, or if the first line shows a Java version lower than 1.6, you’ll need to follow the instructions to install Java for your platform (https://www.java.com/en/download/help/download_options.xml). Once you have Java installed, you can follow the instructions shown here to install Clojure.

A.1. Try Clojure

The easiest way to install something is not to install it. Try Clojure (http://www.tryclj.com) is a Clojure REPL you run in your browser. This REPL has two major limitations:

• It runs an older version of Clojure (1.4 as of this writing).
• If you define too many things or wait 15 minutes, your environment is reset. (It’s kept if you close your browser window, so you can reopen it without losing your defined vars and functions.)

But if you just want to try some Clojure code, this isn’t a bad option. You can follow along with most of the examples in chapters 2 and 3 using nothing more than the Try Clojure REPL.

A.2. Clojure.jar

Clojure is really just some Java code, and Java code is distributed in JAR files. You can download prebuilt Clojure JAR files from http://clojure.org/downloads. Unzip the downloaded file and run the clojure.main entry point to get a REPL:

$ java -cp clojure-1.6.0.jar clojure.main
Clojure 1.6.0
user=>

The clojure.main entry point has some other command-line options, too:

$ java -cp clojure-1.6.0.jar clojure.main --help
Usage: java -cp clojure.jar clojure.main [init-opt*] [main-opt] [arg*]

  With no options or args, runs an interactive Read-Eval-Print Loop

  init options:
    -i, --init path     Load a file or resource
    -e, --eval string   Evaluate expressions in string; print non-nil values

  main options:
    -m, --main ns-name  Call the -main function from a namespace with args
    -r, --repl          Run a repl
    path                Run a script from from a file or resource
    -                   Run a script from standard input
    -h, -?, --help      Print this help message and exit

  operation:

    - Establishes thread-local bindings for commonly set!-able vars
    - Enters the user namespace
    - Binds *command-line-args* to a seq of strings containing command line
      args that appear after any main option
    - Runs all init options in order
    - Calls a -main function or runs a repl or script if requested

  The init options may be repeated and mixed freely, but must appear before
  any main option. The appearance of any eval option before running a repl
  suppresses the usual repl greeting message: "Clojure ~(clojure-version)".

  Paths may be absolute or relative in the filesystem or relative to
  classpath. Classpath-relative paths have prefix of @ or @/

A.3. Leiningen

Leiningen is the standard Clojure project and dependency management tool—almost all Clojure projects are managed using Leiningen. For most people, almost all of their contact with Clojure is actually through Leiningen. If you’re not sure what Clojure installation option you need, then it’s this one!

If you’re familiar with the Java world, you’re sure to have come across Maven. This is an open source tool that can simplify dependency management and builds of any Java-based project. Although Maven has become ubiquitous in the Java world, it’s known for being somewhat difficult to use, especially when it comes to larger, complex projects.

Luckily, despite Clojure being a Java project itself, you don’t have to use Maven directly. Phil Hagelberg (http://technomancy.us) has created the Leiningen project, which uses the best parts of Maven while providing a very clean Clojure interface to end users. In this section, you’ll install Leiningen and use it to set up your Clojure project.

Getting Leiningen to work on your computer is trivial. Just follow the instructions on the project’s GitHub page: https://github.com/technomancy/leiningen. Once you’ve finished, you should be able to run the lein (short for Leiningen) command from your shell. To get into a Clojure REPL from anywhere, run lein repl.

But Leiningen’s true power is managing projects: Clojure programs and libraries with multiple dependencies, entry points, tests, deployment processes, and the like. Read on to learn the basics of Leiningen project creation and management.

A.3.1. lein tasks

Running lein will show you a list of available tasks. The simplest one that lets you get started is lein new. Running this task creates a skeleton project.clj file, which is the basic configuration file that drives Leiningen, along with a directory structure for a new Clojure project. Here’s the set of directories and files created by running lein new trial, where trial is the name of the project we’re creating:

• project.clj
• README.md
• doc/
• src/
• test/

You may have slightly different content in this directory, depending on your exact version of Leiningen. The following shows the contents of the project.clj file we just generated:

(defproject trial "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.6.0"]])

The file contains a single call to defproject, which is part of the lein DSL. As you can see, the name of the project is trial, and the version number has been set to 0.1.0-SNAPSHOT. If you’re familiar with Maven, you’ll know what setting the version of a project to SNAPSHOT means (it just means that this version hasn’t yet been released and is perhaps not official). Apart from the name of the project and the version, defproject accepts a number of keyword parameters. The ones shown previously are mostly self-explanatory, but one of interest is :dependencies. This specifies the various libraries (JAR files) that the project depends on and that will be pulled in from a Maven repository (by default, lein looks at the Maven repository hosted at http://clojars.org). Incidentally, you may have a different version of Clojure as your dependency, depending on the latest stable release of Clojure.

A.3.2. lein repl

The next step is to run another lein task called repl. This causes lein to first run a task called deps, which connects to the default Maven repository (and any others that you may specify via the :repositories parameter in your project.clj), and get the dependency JAR files. These will be stored in your home folder, under the .m2 directory.

Once the dependencies have been downloaded, you’ll be dropped to a Clojure prompt that’s the REPL, with the classpath set up to include all the specified dependencies. This makes it really easy to manage your project’s dependencies and their specific versions. The following shows how it looks once the task runs (again, your output may be slightly different). Remember to change directory so you’re in the project folder:

$ lein repl
nREPL server started on port 58315 on host 127.0.0.1 - nrepl://127.0.0.1:58315
REPL-y 0.3.5, nREPL 0.2.6
Clojure 1.6.0
Java HotSpot(TM) 64-Bit Server VM 1.8.0_20-b26
    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=>

At this point, you’re up and running at an active Clojure prompt. Next, let’s take a look at how to add other dependencies to your Clojure project.

A.3.3. Adding dependencies to a Leiningen project

Larger Clojure programs often need other libraries on which to build functionality. Traditionally, managing such libraries has been a chore, but over the past couple of years, Leiningen has become the default dependency management tool for Clojure projects. As mentioned earlier, it uses Maven repositories as sources for the various libraries (JAR files in the Clojure world). There’s a community repository hosted at https://clojars.org, which is the default repository for Leiningen. You can search this repository, and you’ll often find what you’re looking for if someone has uploaded that library. Of course, you can also upload your own JAR files if you don’t find what you’re looking for. Further, you can also tell Leiningen to look at other repositories and indeed host your own Maven repository if you’d like.

Here’s an example of how you might conveniently add the JSON handling library called Cheshire to your program. You go to https://clojars.org and search for Cheshire, and you’ll notice several options. One of them has version 5.4, which is a recent version and one that you’ll probably be comfortable with. When you go to the web page for that library, you’ll see the Leiningen dependency vector you need to add this to your project. In this case it is

[cheshire "5.4.0"]

You copy and paste that into the :dependencies section of your project.clj, save the file, and then run lein deps. Leiningen will download the correct JAR file, and you’ll have it available to use when you start your REPL the next time.