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/stable/bin/lein
chmod +x lein
./lein self-install

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.4.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”: http://mvnrepository.com/ 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 editor of choice and start working on the library. I use Emacs with swank-clojure installed. Use C-x C-f and open too-hot/src/too_hot/core.clj. Then use M-x clojure-jack-in to start a slime repl with the correct classpath.

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))

Compile and load the file with C-c C-k in Emacs and check that it works in the REPL:

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. Open too-hot/project.clj:

  (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.4.0"] ]
  :deploy-repositories {"clojars-https" {:url "https://clojars.org/repo"
                                         :username "username"
                                         :password "password"}})

Then run

lein deploy clojars-https

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.clojure.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.4.0"] ]
  :deploy-repositories {"clojars-https" {:url "https://clojars.org/repo"
                                         :username "ato"
                                         :password "password"}})

Now try pushing again:

lein deploy clojars-https