Leiningen is a command-line tool that can be used to do many things to and with Clojure projects, including creating them and running them.

Here I will explain how to install Leiningen and use it to add libraries to your projects. The explanation here is very detailed, assuming you’ve never done anything like this before.

First, install Leiningen on your system

Leiningen can be obtained from [https://github.com/technomancy/leiningen]

The details for installing leiningen will vary a bit depending on your operating system. I’ll give full details here for how to do it in MacOS, and the process will be similar for linux. Windows will be a bit more different; there are windows instructions on the leiningen site.

The short version of how to install leiningen is something like: It’s just a shell script; put it somewhere on your path and make it executable. Done. But for those of you who haven’t done this sort of thing before, here is one way of doing this in full detail (specified for MacOS).

Go to [https://github.com/technomancy/leiningen]. Click on the relevant link and save the resulting page as lein.txt. Put it on your desktop for now.

You’re going to want to invoke the script that’s in this file from a command line. We’ll also use a commands at the command line to move it into the right place and set it up properly.

In MacOS you get a command line by launching the Terminal application which can usually be found in Applications/Utilities. When you launch Terminal you’ll get a command prompt and you’ll be “in” the top level of your user directory. The command “ls” will show you what’s there, which may help to orient you.

The script file needs to be put somewhere on your “path”, which is where the command line interface will look for commands that you type. You could put it anywhere, and add the place you put it to your path, but what I do (and I think is pretty common) is to create a directory (folder) called “bin” in my user directory. You can do this from the finder or like this at the command line:

mkdir bin

Now you need to move the script file (lein.txt) into the bin folder and rename it just “lein”. One way to do this is to use the finder: drag it into the bin folder and then rename it, although the renaming here will be a little annoying because of the way file suffixes are hidden in the finder… you have to do File > Get Info on it and change the name there, and tell it that you really don’t want a suffix, hidden or not. I found it simpler just to do this at the command line:

mv Desktop/lein.txt bin/lein

Now you have to make the script file “executable”. You can do this with the “chmod” command. I do it with:

chmod +x bin/lein

The leiningen instructions say “chmod 755 ~/bin/lein” which will work too. I prefer +x instead of 755 because it’s easier for me to remember, since it means “add execute”. The “~/” in this version means “starting from the user’s home directory”, so no matter what directory you’re currently in it will work on the file that’s in your bin directory. If you’re following my directions above then you’re already in your home directory, so you don’t need that.

Now you have to make sure that the bin folder is actually on your path. If it is, it will probably be because you previously created it and put it there, and you will know that! You can check by typing:

echo $PATH

and looking for “~/bin” in the result.

Let’s assume that it’s not there (which it won’t be unless you’d done stuff like this before). It can be added to your path with the “export” command, but that will add it only for the current terminal session. We want it to be added automatically every time you open a terminal session, so that you don’t have to think about this again. This can be done by adding a call to the export command in a file in your home directory that gets run every time you launch a terminal session. In MacOS this is a hidden file called “.profile” — it will have a different name in other operating systems.

The command that you want to add to .profile is:

export PATH=~/bin:$PATH

You can do this in a text editor, or from the command line with this command:

echo "export PATH=~/bin:$PATH" >> .profile

This won’t make a difference for the terminal session that you’re in, but open a new terminal window and .profile will be run for it. Then you can type:

lein

And it will do a bunch of downloading and configuration stuff and then, if all goes well, you’ll get a welcome message and a list of lein commands. If you get the welcome message then lein has been installed correctly on your computer.

Add a dependency to your project and use it

1. Include an additional item in the :dependencies specification in your project’s project.clj file.
2. Run “lein deps” at the command line (which will pull in the necessary files from the web).
3. Make sure the new stuff is visible to the environment in which you’re running your code; for clooj I quit/restart clooj after running lein deps.

How do you find the item to include in project.clj? That depends on what dependency you want to pull in. Things that are part of Clojure itself can be found at https://github.com/clojure, and if you look at the readme text for any of the specific libraries you’ll see what you need to add. For example, clicking on math.combinatorics I see that this is the thing to add to the :dependencies specification for leiningen: [org.clojure/math.combinatorics “0.0.3”]

For example, if I make a brand new project (in clooj) called foo then the project.clj that’s made automatically for me will look like this:

(defproject foo "1.0.0-SNAPSHOT"
  :description "FIXME: write"
  :dependencies [[org.clojure/clojure "1.3.0"]])

If I want to add a dependency to math.combinatorics then I should change it to be:

(defproject foo "1.0.0-SNAPSHOT"
  :description "FIXME: write"
  :dependencies [[org.clojure/clojure "1.3.0"]
                 [org.clojure/math.combinatorics "0.0.3"]])

Once I’ve done this I should save the file, switch to Terminal, cd into the foo directory, and do:

lein deps

This will pull in the math.combinatorics library, and restarting clooj will ensure that clooj “sees” that the new file is there.

Next, make sure that your code requires or uses the new library’s namespace. This can be done with the use or require functions, or (preferably) in your code’s ns declaration. For example, in my foo project I put this in my core.clj:

(ns foo.core
  (:use [clojure.math.combinatorics]))

Then, after evaluating this, I can do things like:

(combinations [1 2 3] 2)

to get:

((1 2) (1 3) (2 3))

Find and use other libraries

There are a lot of other things out there that you might want to use, and often the best way to find them is with a general web search. For example, suppose that you want to use the “quil” library to do Processing graphics (this is a version of the library used in Processing — [http://processing.org]). A quick search for “clojure quil” finds [https://github.com/quil/quil] and this includes nice instructions with the thing that you have to add to your project.clj ([quil “1.6.0”]) and also information on how to set up your namespace and some example code.

One other specific library that may be of interest is a small library that makes it easy to refer to local files; see [https://github.com/arthuredelstein/local-file/]. (I believe that this functionality will be built in to Clojure 1.4, but as of 1.3 this library is still quite useful.)

One other site to know about is [http://clojars.org] — aka “clojars”. Clojars is a community repository for open source Clojure libraries, and that’s where a lot of commonly used libraries actually reside. You can use the site to look up the dependency information that you need to put in your project.clj for all of the projects that it houses, although clojars doesn’t itself serve documentation (so you usually have to do a general web search to find that).