Tutorial

See also: Leiningen’s own tutorial and deploy guide and our Clojure CLI instructions.

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 (this assumes you are on Linux or MacOS – see leiningen.org for installing on other platforms):

cd ~/bin
wget https://raw.githubusercontent.com/technomancy/leiningen/stable/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.3"] ])

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, 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. First, we’ll need to create a deploy token to use in place in of our password. Then run

lein deploy clojars

You’ll be prompted for your username and password – enter your Clojars username and deploy token, respectively.

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. In order to deploy a project, you have to own the group it is in. 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 rokatanski change your project.clj to:

(defproject org.clojars.rokatanski/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.3"] ])

Now try pushing again:

lein deploy clojars

If you want to create your own groups for deploying projects, read our Groups page for more details.