leiningen/doc/TUTORIAL.md

Tutorial

For those of you new to the JVM who have never touched Ant or Maven in anger: don't panic. Leiningen is designed with you in mind. This tutorial will help you get started and explain Leiningen's take on project automation and JVM-land dependency management.

Creating a Project

We'll assume you've got Leiningen installed as per the README. Generating a new project is easy:

$ lein new my-stuff

Generating a project called my-stuff based on the 'default' template.

$ cd my-stuff
$ tree
.
|-- project.clj
|-- README.md
|-- src
|   `-- my_stuff
|       `-- core.clj
`-- test
    `-- my_stuff
        `-- core_test.clj

Here we've got your project's README, a src/ directory containing the code, a test/ directory, and a project.clj file which describes your project to Leiningen. The src/my/stuff.clj file corresponds to the my.stuff namespace.

Note that we use my-stuff.core instead of just my-stuff since single-segment namespaces are discouraged in Clojure. Also note that namespaces with dashes in the name will have the corresponding file named with underscores instead since the JVM has trouble loading files with dashes in the name.

Packaging

You can package your project up now, even though at this stage it's fairly useless:

$ lein jar

Created ~/src/my-stuff/target/my-stuff-0.1.0-SNAPSHOT.jar

Libraries for the JVM are packaged up as .jar files, which are basically just .zip files with a little extra JVM-specific metadata. They usually contain .class files (JVM bytecode) and .clj source files, but they can also contain other things like config files. Leiningen downloads jar files of dependencies from remote Maven repositories for you.

project.clj

$ cat project.clj

(defproject my-stuff "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.3.0"]])

Fill in the :description with a short sentence so that your project will show up in search results once you publish it, and be sure to fix the :url as well. At some point you'll need to flesh out the README too, but for now let's skip ahead to setting :dependencies. Note that Clojure is just another dependency here. Unlike most languages, it's easy to swap out any version of Clojure.

Dependencies

By default, Leiningen projects download dependencies from Clojars and Maven Central. Clojars is the Clojure community's centralized jar repository, while Maven Central is for the wider JVM community.

The lein search command will search each remote repository:

$ lein search lancet
 == Results from clojars - Showing page 1 / 1 total
[lancet "1.0.0"] Dependency-based builds, Clojure Style.
[lancet "1.0.1"] Dependency-based builds, Clojure Style.

This shows two versions available with the dependency vector notation for each. You can copy one of these directly into the :dependencies vector in project.clj.

The "artifact id" here is "lancet", and "1.0.1" is the version you require. Every library also has a "group id", though for Clojure libraries it is often the same as the artifact-id, in which case you may omit it. For Java libraries often a reversed domain name is used as the group id.

Sometimes versions will end in "-SNAPSHOT". This means that it is not an official release but a development build. Relying on snapshot dependencies is discouraged but is sometimes necessary if you need bug fixes, etc. that have not made their way into a release yet. However, snapshot versions are not guaranteed to stick around, so it's important that released code never depends upon snapshot versions that you don't control. Adding a snapshot dependency to your project will cause Leiningen to actively go seek out the latest version of the dependency (whereas normal release versions are cached in the local repository) so if you have a lot of snapshots it will slow things down.

Speaking of the local repository, all the dependencies you pull in using Leiningen or Maven get cached in $HOME/.m2/repository since Leiningen uses the same library as Maven under the covers. You can install the current project in the local repository with this command:

$ lein install

Wrote ~/src/my-stuff/target/pom.xml
[INFO] Installing my-stuff-0.1.0-SNAPSHOT.jar to ~/.m2/repository/myproject/myproject/0.1.0-SNAPSHOT/myproject-0.1.0-SNAPSHOT.jar

Note that some libraries make their group-id and artifact-id correspond with the namespace they provide inside the jar, but this is just a convention. There is no guarantee they will match up at all, so consult the library's documentation before writing your :require clauses.

You can add third-party repositories by setting the :repositories key in project.clj. See the sample.project.clj.

Profiles

Sometimes you want to pull in dependencies that are really only necessary while developing; they aren't required for the project to function in production. You can do this by adding a :dependencies entry to the :dev profile. These will be available unless you specify different profiles using the with-profiles task, but they are not brought along when another project depends on your project.

Using midje for your tests would be a typical example; you would not want it included in production, but it's needed to run the tests:

(defproject my-stuff "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.3.0"]]
  :profiles {:dev {:dependencies [[midje "1.3.1"]]}})

Note that profile-specific dependencies are different from plugins in context; plugins run in Leiningen's process while dependencies run in your project itself. (Older versions of Leiningen lacked this distinction.)

If you have dependencies that are not necessary for developing but just for convenience (things like Swank Clojure for Emacs support or clj-stacktrace you should add them to the :user profile in ~/.lein/profiles instead of the :dev profile. Both those profiles are active by default; the difference is the convention for where they are specified.

Writing the Code

This is the part Leiningen can't really help you with; you're on your own here. Well—not quite. Leiningen can help you with running your tests.

$ lein test

Testing my.test.stuff

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

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

Of course, we haven't written any tests yet, so we've just got the skeleton failing tests that Leiningen gave us with lein new. But once we fill it in the test suite will become more useful. Sometimes if you've got a large test suite you'll want to run just one or two namespaces at a time:

$ lein test my.test.stuff.parser

Testing my.test.stuff.parser
Ran 2 tests containing 10 assertions.
0 failures, 0 errors.

Rather than running your whole suite or just a few namespaces at a time, you can run a subset of your tests using test selectors. To do this, you attach metadata to various deftests.

(deftest ^:integration network-heavy-test
  (is (= [1 2 3] (:numbers (network-operation)))))

Then add a :test-selectors map to project.clj:

:test-selectors {:default (complement :integration)
                 :integration :integration
                 :all (fn [_] true)}

Now if you run lein test it will only run deftests that don't have :integration metadata, while lein test :integration will only run the integration tests and lein test :all will run everything. You can include test selectors and listing test namespaces in the same run.

Running lein test from the command-line is suitable for regression testing, but the slow startup time of the JVM makes it a poor fit for testing styles that require tighter feedback loops. In these cases, either keep a repl open for running the appropriate call to clojure.test/run-tests or look into editor integration such as clojure-test-mode.

Keep in mind that while keeping a single process around is convenient, it's easy for that process to get into a state that doesn't reflect the files on disk—functions that are loaded and then deleted from the file will remain in memory, making it easy to miss problems arising from missing functions (often referred to as "getting slimed"). Because of this it's advised to do a lein test run with a fresh instance periodically in any case, perhaps before you commit.

AOT Compiling

If you're lucky you'll be able to get away without doing any AOT (ahead-of-time) compilation. But there are some Java interop features that require it, so if you need to use them you should add an :aot option into your project.clj file. It should be a seq of namespaces you want AOT-compiled. Again, the sample.project.clj has example usage.

Like dependencies, this should happen for you automatically when needed, but if you need to force it you can:

$ lein compile

Compiling my.stuff

For your code to compile, it must be run. This means that you shouldn't have any code with side-effects in the top-level. Anything outside a function definition that doesn't start with "def" is suspect. If you have code that should run on startup, place it in a -main function as explained below under "Uberjar".

For projects that include some Java code, you can set the :java-source-paths key in project.clj to a vector of directories containing Java files. (You can set it to ["src"] to keep Java alongside Clojure source or keep them in a separate directory.) Then the javac compiler will run before your Clojure code is AOT-compiled, or you can run it manually with the javac task.

What to do with it

Generally speaking, there are three different goals that are typical of Leiningen projects:

• An application you can distribute to end-users
• A server-side application
• A library for other Clojure projects to consume

For the first, you typically either build an uberjar. For libraries, you will want to have them published to a repository like Clojars or a private repository. For server-side applications it varies as described below.

Uberjar

The simplest thing to do is to distribute an uberjar. This is a single standalone executable jar file most suitable for giving to nontechnical users. For this to work you'll need to specify a namespace as your :main in project.clj. By this point our project.clj file should look like this:

(defproject my-stuff "0.1.0-SNAPSHOT"
  :description "FIXME: write description"
  :url "http://example.com/FIXME"
  :license {:name "Eclipse Public License"
            :url "http://www.eclipse.org/legal/epl-v10.html"}
  :dependencies [[org.clojure/clojure "1.3.0"]
                 [org.apache.lucene/lucene-core "3.0.2"]
                 [lancet "1.0.0"]]
  :profiles {:dev {:dependencies [[midje "1.3.1"]]}}
  :test-selectors {:default (complement :integration)
                  :integration :integration
                  :all (fn [_] true)}
  :main my.stuff)

The namespace you specify will need to contain a -main function that will get called when your standalone jar is run. This namespace should have a (:gen-class) declaration in the ns form at the top. The -main function will get passed the command-line arguments. Let's try something simple in src/my/stuff.clj:

(ns my.stuff
  (:gen-class))

(defn -main [& args]
  (println "Welcome to my project! These are your args:" args))

Now we're ready to generate your uberjar:

$ lein uberjar
Compiling my.stuff
Compilation succeeded.
Created /home/phil/src/leiningen/my-stuff/target/my-stuff-0.1.0-SNAPSHOT.jar
Including my-stuff-0.1.0-SNAPSHOT.jar
Including lancet-1.0.0.jar
Including clojure-1.2.0.jar
Including lucene-core-3.0.2.jar
Created /home/phil/src/leiningen/my-stuff/target/my-stuff-0.1.0-SNAPSHOT-standalone.jar

This creates a single jar file that contains the contents of all your dependencies. Users can run it with a simple java invocation, or on some systems just by double-clicking the jar file.

$ java -jar my-stuff-0.1.0-standalone.jar Hello world.
Welcome to my project! These are your args: (Hello world.)

You can run a regular (non-uber) jar with the java command-line tool, but that requires constructing the classpath yourself, so it's not a good solution for end-users.

Invoking lein run will launch your project's -main function as if from an uberjar, but without going through the packaging process. You can also specify an alternate namespace in which to look for -main with lein run -m my.alternate.namespace ARG1 ARG2.

For long-running lein run processes, you may wish to use the trampoline task, which allows the Leiningen JVM process to exit before launching your project's JVM. This can save memory:

$ lein trampoline run -m my-stuff.server 5000

Server-side Projects

There are many ways to get your project deployed as a server-side application. Simple programs can be packaged up as tarballs with accompanied shell scripts using the lein-tar plugin and then deployed using pallet, chef, or other mechanisms. Debian packages can be created with lein-deb. Web applications may be deployed using .war (web application archive) files created by the lein-ring plugin. You can even create Hadoop projects. These kinds of deployments are so varied that they are better-handled using plugins rather than tasks that are built-in to Leiningen itself.

It may be tempting to deploy by just checking out your project and using "lein run" on production servers. However, unless you take steps to freeze all the dependencies before deploying, it could be easy to end up with unrepeatable deployments. It's much better to use Leiningen to create a deployable artifact in a continuous integration setting instead. For example, you could have a Jenkins CI server run your project's full test suite, and if it passes, upload a tarball to S3. Then deployment is just a matter of pulling down and extracting the known-good tarball on your production servers.

Publishing Libraries

If your project is a library and you would like others to be able to use it as a dependency in their projects, you will need to get it into a public repository. While it's possible to maintain your own private repository or get it into Maven central, the easiest way is to publish it at Clojars. Once you have created an account there, publishing is easy:

$ lein jar, pom
$ scp target/pom.xml target/my-stuff-0.1.0.jar clojars@clojars.org:

Once that succeeds it will be available as a package on which other projects may depend. You will need to have permission to publish to the project's group-id under Clojars, though if that group-id doesn't exist yet then Clojars will automatically create it and give you permissions.

For further details about publishing including setting up private repositories, see the deploy guide

That's It!

Now go start coding your next project!