Introduction to Leiningen for Clojure

1. Introduction

Leiningen is a modern build system for our Clojure projects. It’s also written and configured entirely in Clojure.

It works similarly to Maven, giving us a declarative configuration that describes our project, without needing to configure exact steps to be executed.

Let’s jump in and see how to get started with Leiningen for building our Clojure projects.

2. Installing Leiningen

Leiningen is available as a standalone download, as well as from a large number of package managers for different systems.

Standalone downloads are available for Windows as well as for Linux and Mac. In all cases, download the file, make it executable if necessary, and then it’s ready to use.

The first time the script is run it will download the rest of the Leiningen application, and then this will be cached from this point forward:

$ ./lein
Downloading Leiningen to /Users/user/.lein/self-installs/leiningen-2.8.3-standalone.jar now...
.....
Leiningen is a tool for working with Clojure projects.

Several tasks are available:
.....

Run `lein help $TASK` for details.

.....

3. Creating a New Project

Once Leiningen is installed, we can use it to create a new project by invoking lein new.

This creates a project using a particular template from a set of options:

• app – Used to create an application
• default – Used to create a general project structure, typically for libraries
• plugin – Used to create a Leiningen Plugin
• template – Used to create new Leiningen templates for future projects

For example, to create a new application called “my-project” we would execute:

$ ./lein new app my-project
Generating a project called my-project based on the 'app' template.

This gives us a project containing:

• A build definition – project.clj
• A source directory – src – including an initial source file – src/my_project/core.clj
• A test directory – test – including an initial test file – test/my_project/core_test.clj
• Some additional documentation files – README.md, LICENSE, CHANGELOG.md and doc/intro.md

Looking inside our build definition, we’ll see that it tells us what to build, but not how to build it:

(defproject my-project "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "EPL-2.0 OR GPL-2.0-or-later WITH Classpath-exception-2.0"
            :url "https://www.eclipse.org/legal/epl-2.0/"}
  :dependencies [[org.clojure/clojure "1.9.0"]]
  :main ^:skip-aot my-project.core
  :target-path "target/%s"
  :profiles {:uberjar {:aot :all}})

This tells us:

• The details of the project consisting of the project name, version, description, homepage and license details.
• The main namespace to use when executing the application
• The list of dependencies
• The target path to build the output into
• A profile for building an uberjar

Note that the main source namespace is my-project.core, and is found in the file my_project/core.clj. It’s discouraged in Clojure to use single-segment namespaces – the equivalent of top-level classes in a Java project.

Additionally, the filenames are generated with underscores instead of hyphens because the JVM has some problems with hyphens in filenames.

The generated code is pretty simple:

(ns my-project.core
  (:gen-class))

(defn -main
  "I don't do a whole lot ... yet."
  [& args]
  (println "Hello, World!"))

Also, notice that Clojure is just a dependency here. This makes it trivial to write projects using whatever version of the Clojure libraries are desired, and especially to have multiple different versions running on the same system.

If we change this dependency, then we’ll get the alternative version instead.

4. Building and Running

Our project isn’t worth much if we can’t build it, run it and package it up for distribution, so let’s look at that next.

4.1. Launching a REPL

Once we have a project, we can launch a REPL inside of it using lein repl. This will give us a REPL that has everything in the project already available on the classpath – including all project files as well as all dependencies.

It also starts us in the defined main namespace for our project:

$ lein repl
nREPL server started on port 62856 on host 127.0.0.1 - nrepl://127.0.0.1:62856
[]REPL-y 0.4.3, nREPL 0.5.3
Clojure 1.9.0
Java HotSpot(TM) 64-Bit Server VM 1.8.0_77-b03

    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

my-project.core=> (-main)
Hello, World!
nil

This executes the function -main in the current namespace, which we saw above.

4.2. Running the Application

If we are working on an application project – created using lein new app – then we can simply run the application from the command line. This is done using lein run:

$ lein run
Hello, World!

This will execute the function called -main in the namespace defined as :main in our project.clj file.

4.3. Building a Library

If we are working on a library project – created using lein new default – then we can build the library into a JAR file for inclusion in other projects.

We have two ways that we can achieve this – using lein jar or lein install. The difference is simply in where the output JAR file is placed.

If we use lein jar then it will place it in the local target directory:

$ lein jar
Created /Users/user/source/me/my-library/target/my-library-0.1.0-SNAPSHOT.jar

If we use lein install, then it will build the JAR file, generate a pom.xml file and then place the two into the local Maven repository (typically under .m2/repository in the users home directory)

$ lein install
Created /Users/user/source/me/my-library/target/my-library-0.1.0-SNAPSHOT.jar
Wrote /Users/user/source/me/my-library/pom.xml
Installed jar and pom into local repo.

4.4. Building an Uberjar

If we are working on an application project, Leiningen gives us the ability to build what is called an uberjar. This is a JAR file containing the project itself and all dependencies and set up to allow it to be run as-is.

$ lein uberjar
Compiling my-project.core
Created /Users/user/source/me/my-project/target/uberjar/my-project-0.1.0-SNAPSHOT.jar
Created /Users/user/source/me/my-project/target/uberjar/my-project-0.1.0-SNAPSHOT-standalone.jar

The file my-project-0.1.0-SNAPSHOT.jar is a JAR file containing exactly the local project, and the file my-project-0.1.0-SNAPSHOT-standalone.jar contains everything needed to run the application.

$ java -jar target/uberjar/my-project-0.1.0-SNAPSHOT-standalone.jar
Hello, World!

5. Dependencies

Whilst we can write everything needed for our project ourselves, it’s generally significantly better to re-use the work that others have already done on our behalf. We can do this by having our project depend on these other libraries.

5.1. Adding Dependencies to Our Project

To add dependencies to our project, we need to add them correctly to our project.clj file.

Dependencies are represented as a vector consisting of the name and version of the dependency in question. We’ve already seen that Clojure itself is added as a dependency, written in the form [org.clojure/clojure “1.9.0”].

If we want to add other dependencies, we can do so by adding them to the vector next to the :dependencies keyword. For example, if we want to depend on clj-json we would update the file:

  :dependencies [[org.clojure/clojure "1.9.0"] [clj-json "0.5.3"]]

Once done, if we start our REPL – or any other way to build or run our project – then Leiningen will ensure that the dependencies are downloaded and available on the classpath:

$ lein repl
Retrieving clj-json/clj-json/0.5.3/clj-json-0.5.3.pom from clojars
Retrieving clj-json/clj-json/0.5.3/clj-json-0.5.3.jar from clojars
nREPL server started on port 62146 on host 127.0.0.1 - nrepl://127.0.0.1:62146
REPL-y 0.4.3, nREPL 0.5.3
Clojure 1.9.0
Java HotSpot(TM) 64-Bit Server VM 1.8.0_77-b03
    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

my-project.core=> (require '(clj-json [core :as json]))
nil
my-project.core=> (json/generate-string {"foo" "bar"})
"{\"foo\":\"bar\"}"
my-project.core=>

We can also use them from inside our project. For example, we could update the generated src/my_project/core.clj file as follows:

(ns my-project.core
  (:gen-class))

(require '(clj-json [core :as json]))

(defn -main
  "I don't do a whole lot ... yet."
  [& args]
  (println (json/generate-string {"foo" "bar"})))

And then running it will do exactly as expected:

$ lein run
{"foo":"bar"}

5.2. Finding Dependencies

Often, it can be difficult to find the dependencies that we want to use in our project. Leiningen comes with a search functionality built in to make this easier. This is done using lein search.

For example, we can find our JSON libraries:

$ lein search json
Searching central ...
[com.jwebmp/json "0.63.0.60"]
[com.ufoscout.coreutils/json "3.7.4"]
[com.github.iarellano/json "20190129"]
.....
Searching clojars ...
[cheshire "5.8.1"]
  JSON and JSON SMILE encoding, fast.
[json-html "0.4.4"]
  Provide JSON and get a DOM node with a human representation of that JSON
[ring/ring-json "0.5.0-beta1"]
  Ring middleware for handling JSON
[clj-json "0.5.3"]
  Fast JSON encoding and decoding for Clojure via the Jackson library.
.....

This searches all of the repositories that our project is working with – in this case, Maven Central and Clojars. It then returns the exact string to put into our project.clj file and, if available, the description of the library.

6. Testing Our Project

Clojure has built-in support for unit testing our application, and Leiningen can harness this for our projects.

Our generated project contains test code in the test directory, alongside the source code in the src directory. It also includes a single, failing test by default – found in test/my_project/core-test.clj:

(ns my-project.core-test
  (:require [clojure.test :refer :all]
            [my-project.core :refer :all]))

(deftest a-test
  (testing "FIXME, I fail."
    (is (= 0 1))))

This imports the my-project.core namespace from our project, and the clojure.test namespace from the core Clojure language. We then define a test with the deftest and testing calls.

We can immediately see the names of the test, and the fact that it’s deliberately written to fail – it asserts that 0 == 1.

Let’s run this using the lein test command, and immediately see the tests running and failing:

$ lein test
lein test my-project.core-test

lein test :only my-project.core-test/a-test

FAIL in (a-test) (core_test.clj:7)
FIXME, I fail.
expected: (= 0 1)
  actual: (not (= 0 1))

Ran 1 tests containing 1 assertions.
1 failures, 0 errors.
Tests failed.

If we instead fix the test, changing it to assert that 1 == 1 instead, then we’ll get a passing message instead:

$ lein test
lein test my-project.core-test

Ran 1 tests containing 1 assertions.
0 failures, 0 errors.

This is a much more succinct output, only showing what we need to know. This means that when there are failures, they immediately stand out.

If we want to, we can also run a specific subset of the tests. The command line allows for a namespace to be provided, and only tests in that namespace are executed:

$ lein test my-project.core-test

lein test my-project.core-test

Ran 1 tests containing 1 assertions.
0 failures, 0 errors.

$ lein test my-project.unknown

lein test my-project.unknown

Ran 0 tests containing 0 assertions.
0 failures, 0 errors.

7. Summary

This article has shown how to get started with the Leiningen build tool, and how to use it to manage our Clojure based projects – both executable applications and shared libraries.

Why not try it for out on the next project and see how well it can work.