Tutorial

See also: Leiningen’s own tutorial and deploy guide.

Hi! Today I’ll walk you through creating and building a simple library with Leiningen and pushing it to Clojars.org. First up, install Leiningen:

cd ~/bin
wget http://github.com/technomancy/leiningen/raw/preview/bin/lein
chmod +x lein

Our example library is going to be called too-hot so lets create a project skeleton for it.

lein new too-hot

Next open the Leiningen project file at too-hot/project.clj using your text editor. This is where we specify the name and version of our project and list its dependencies.

(defproject too-hot "1.0.0"
  :description "A very simple Fahrenheit to Celsius converter."
  :url "http://github.com/kelvin/too-hot"
  :dependencies [ [org.clojure/clojure "1.10.0"] ])

This says that we want to use the latest version of Clojure. If you need more dependencies for your project, try searching Maven central for Java libs and Clojars for Clojure libraries, then just add them to your :dependencies list. The format is:

[groupId/artifactId "version"]

Note that the groupId is optional if it’s the same as the artifactId.

Now you can fire up your REPL of choice and start working on the library. Unless you have your editor already set up, it’s simplest to just start with lein repl.

As an Australian if I complain to an American friend about how it’s 40 degrees outside and way they usually just give me a puzzled look. So our example library is going to be a Celsius to Fahrenheit converter. Change too-hot/src/too_hot/core.clj:

(ns too-hot.core)
  
(defn celsius
  "Converts a temperature in Fahrenheit to Celsius."
  [f]
  (* (- f 32) 5/9))
 
(defn fahrenheit
  "Converts a temperature in Celsius to Fahrenheit."
  [c]
  (+ (* c 9/5) 32))

Load the file with (require ’too-hot.core) in the REPL and check that it works:

user> (too-hot.core/fahrenheit 40)
104N
user> (too-hot.core/celsius 104)
40N

Beaut, we’re finished. So lets now push the library to the Clojars repository so that other people can use it. Run

lein deploy clojars

Whoops, what happened?

Error deploying artifact 'too-hot:too-hot:jar': Error deploying artifact: Failed to transfer file: https://clojars.org/repo/too-hot/too-hot/1.0.0/too-hot-1.0.0.jar. Return code is: 401

Here you see Clojars’ groups in action. When you push a jar a group is automatically created with you as its sole member. You can add members by going to the group under “Your groups” on your dashboard and filling in a username to add. In this case I own the official too-hot group so you are unable to push to it.

If you want to push your own version of somebody else’s jar you’ll have to put it under your group, to show it’s your version and not the official one. To do this, just qualify the project name by putting org.clojars.username/ in front of it in your project.clj. So for example, if your Clojars username is ato change your project.clj to:

(defproject org.clojars.ato/too-hot "1.0.0"
  :description "A very simple Fahrenheit to Celsius converter."
  :url "http://github.com/kelvin/too-hot"
  :dependencies [ [org.clojure/clojure "1.8.0"] ])

Now try pushing again:

lein deploy clojars

Older versions of Leiningen (1.x) don’t use https for Clojars and won’t be able to push directly; see pushing for instructions on how to force https.