2009-10-31 21:35:25 +00:00
# Leiningen
2013-07-02 18:21:33 +00:00
< img src = "http://leiningen.org/img/leiningen.jpg"
2012-01-13 02:04:57 +00:00
alt="Leiningen logo" title="The man himself" align="right" />
2012-01-13 00:10:32 +00:00
2009-11-12 05:25:16 +00:00
> "Leiningen!" he shouted. "You're insane! They're not creatures you can
2012-05-10 02:22:04 +00:00
> fight—they're an elemental—an 'act of God!' Ten miles long, two
> miles wide—ants, nothing but ants! And every single one of them a
2009-12-21 04:37:19 +00:00
> fiend from hell..."
2015-02-18 16:16:27 +00:00
> - from [Leiningen Versus the Ants](http://www.classicshorts.com/stories/lvta.html) by Carl Stephenson
2009-10-31 21:35:25 +00:00
2011-07-06 03:43:25 +00:00
Leiningen is for automating Clojure projects without setting your hair on fire.
2009-10-31 21:35:25 +00:00
2009-11-12 05:25:16 +00:00
## Installation
2009-11-02 07:02:16 +00:00
2012-01-24 03:06:29 +00:00
If your preferred
[package manager ](https://github.com/technomancy/leiningen/wiki/Packaging )
2014-07-19 22:52:50 +00:00
offers a recent version of Leiningen, try that first. Many package managers still
include version 1.x, which is rather outdated, so you may be better off installing manually.
2012-01-24 03:06:29 +00:00
2014-07-19 22:52:50 +00:00
Leiningen installs itself on the first run of the `lein` shell script; there is no
separate install script. Follow these instructions to install Leiningen manually:
2010-03-13 05:04:11 +00:00
2013-06-13 00:11:18 +00:00
1. Make sure you have a Java JDK version 6 or later.
2014-07-19 22:52:50 +00:00
2. [Download the `lein` script from the `stable` branch ](https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein )
of this project.
2013-03-22 16:26:59 +00:00
3. Place it on your `$PATH` . (`~/bin` is a good choice if it is on your path.)
2013-03-22 16:24:22 +00:00
4. Set it to be executable. (`chmod 755 ~/bin/lein`)
2014-07-19 22:52:50 +00:00
5. Run it.
2010-09-10 17:02:26 +00:00
2013-06-13 00:08:51 +00:00
### Windows
2013-06-06 12:02:05 +00:00
2013-07-26 20:01:56 +00:00
There is
[an installer ](http://leiningen-win-installer.djpowell.net/ ) which
2013-06-13 00:08:51 +00:00
will handle downloading and placing Leiningen and its dependencies.
2013-06-06 12:02:05 +00:00
2013-07-26 20:01:56 +00:00
The manual method of putting
2014-05-05 20:54:54 +00:00
[the batch file ](https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein.bat ).
2013-07-26 20:01:56 +00:00
on your `PATH` and running `lein self-install` should still work for
most users. If you have [Cygwin ](http://www.cygwin.com/ ) you should be
able to use the shell script above rather than the batch file.
2010-03-13 05:04:11 +00:00
2016-02-22 07:55:58 +00:00
N.B.: Avoid using a LEIN_JAR environment variable. If you have one instance of Leiningen on your PATH as well as a LEIN_JAR pointing to a different instance, there is a known problem where `lein -v` and `lein update` will refer to the first instance, while usage of Leiningen, such as `lein new foobar` , will refer to the latter.
2012-05-24 04:27:17 +00:00
## Basic Usage
2009-10-31 21:35:25 +00:00
2010-06-19 03:56:36 +00:00
The
2013-01-20 04:39:43 +00:00
[tutorial ](https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md )
2010-06-19 03:56:36 +00:00
has a detailed walk-through of the steps involved in creating a new
project, but here are the commonly-used tasks:
2012-04-12 17:12:05 +00:00
$ lein new [TEMPLATE] NAME # generate a new project skeleton
2010-06-05 20:26:52 +00:00
2009-11-29 22:20:09 +00:00
$ lein test [TESTS] # run the tests in the TESTS namespaces, or all tests
2009-11-02 06:47:21 +00:00
2012-02-08 05:00:02 +00:00
$ lein repl # launch an interactive REPL session
2009-10-31 21:35:25 +00:00
2012-05-25 01:26:46 +00:00
$ lein run -m my.namespace # run the -main function of a namespace
2009-11-09 06:09:39 +00:00
2012-05-25 01:26:46 +00:00
$ lein uberjar # package the project and dependencies as standalone jar
2011-10-21 19:45:53 +00:00
2014-09-09 23:25:46 +00:00
$ lein deploy clojars # publish the project to Clojars as a library
2011-10-19 23:24:30 +00:00
Use `lein help` to see a complete list. `lein help $TASK` shows the
2012-01-13 00:10:32 +00:00
usage for a specific task.
2009-11-20 01:50:33 +00:00
2012-06-10 04:48:32 +00:00
You can also chain tasks together in a single command by using the
`do` task with comma-separated tasks:
2010-08-18 05:21:53 +00:00
2012-06-10 04:48:32 +00:00
$ lein do clean, test foo.test-core, jar
2010-08-17 05:05:24 +00:00
2010-08-18 05:21:53 +00:00
Most tasks need to be run from somewhere inside a project directory to
2012-04-12 17:12:05 +00:00
work, but some (`new`, `help` , `search` , `version` , and `repl` ) may
run from anywhere.
2010-08-17 05:05:24 +00:00
2009-10-31 21:35:25 +00:00
## Configuration
2011-10-19 23:24:30 +00:00
The `project.clj` file in the project root should look like this:
2011-08-17 20:13:17 +00:00
2012-01-13 01:10:35 +00:00
```clj
2011-08-17 20:13:17 +00:00
(defproject myproject "0.5.0-SNAPSHOT"
:description "A project for doing things."
2013-01-03 06:32:07 +00:00
:license "Eclipse Public License 1.0"
2011-08-17 20:13:17 +00:00
:url "http://github.com/technomancy/myproject"
2016-01-21 10:08:58 +00:00
:dependencies [[org.clojure/clojure "1.8.0"]]
2014-09-09 23:25:46 +00:00
:plugins [[lein-tar "3.2.0"]])
2011-08-18 01:00:12 +00:00
```
2009-10-31 21:35:25 +00:00
2012-05-10 02:22:04 +00:00
The `lein new` task generates a project skeleton with an appropriate
starting point from which you can work. See the
2013-01-20 04:39:43 +00:00
[sample.project.clj ](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj )
2012-05-10 02:22:04 +00:00
file (also available via `lein help sample` ) for a detailed listing of
configuration options.
2010-11-07 23:50:25 +00:00
2012-05-25 01:26:46 +00:00
The `project.clj` file can be customized further with the use of
2013-01-20 04:39:43 +00:00
[profiles ](https://github.com/technomancy/leiningen/blob/stable/doc/PROFILES.md ).
2012-01-29 21:59:07 +00:00
2012-10-10 18:42:32 +00:00
## Documentation
Leiningen documentation is organized as a number of guides:
2015-09-09 23:53:01 +00:00
### Usage
2014-09-09 23:25:46 +00:00
* [Tutorial ](https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md ) (start here if you are new)
* [FAQ ](https://github.com/technomancy/leiningen/blob/stable/doc/FAQ.md )
2013-09-19 17:39:06 +00:00
* [Profiles ](https://github.com/technomancy/leiningen/blob/stable/doc/PROFILES.md )
2013-01-20 04:39:43 +00:00
* [Deployment & Distribution of Libraries ](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md )
* [Sample project.clj ](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj )
2014-09-09 23:25:46 +00:00
* [Polyglot (e.g. Clojure/Java) projects ](https://github.com/technomancy/leiningen/blob/stable/doc/MIXED_PROJECTS.md )
2015-09-09 23:53:01 +00:00
### Development
* [Writing Plugins ](https://github.com/technomancy/leiningen/blob/stable/doc/PLUGINS.md )
* [Writing Templates ](https://github.com/technomancy/leiningen/blob/stable/doc/TEMPLATES.md )
* [Contributing ](https://github.com/technomancy/leiningen/blob/stable/CONTRIBUTING.md )
* [Building Leiningen ](https://github.com/technomancy/leiningen/blob/stable/CONTRIBUTING.md#bootstrapping )
2012-10-10 18:42:32 +00:00
2012-05-25 01:26:46 +00:00
## Plugins
2012-01-13 01:10:35 +00:00
2012-01-13 02:04:57 +00:00
Leiningen supports plugins which may contain both new tasks and hooks
2012-12-21 16:27:03 +00:00
that modify behaviour of existing tasks. See
2012-01-13 01:10:35 +00:00
[the plugins wiki page ](https://github.com/technomancy/leiningen/wiki/Plugins )
for a full list. If a plugin is needed for successful test or build
runs, (such as `lein-tar` ) then it should be added to `:plugins` in
2011-10-21 21:36:40 +00:00
project.clj, but if it's for your own convenience (such as
2014-09-09 23:25:46 +00:00
`lein-pprint` ) then it should be added to the `:plugins` list in the
2012-12-21 16:27:03 +00:00
`:user` profile in `~/.lein/profiles.clj` . See the
2013-01-20 04:39:43 +00:00
[profiles guide ](https://github.com/technomancy/leiningen/blob/stable/doc/PROFILES.md )
2012-12-21 16:27:03 +00:00
for details on how to add to your `:user` profile. The
2013-01-20 04:39:43 +00:00
[plugin guide ](https://github.com/technomancy/leiningen/blob/stable/doc/PLUGINS.md )
2012-01-13 02:04:57 +00:00
explains how to write plugins.
2010-10-25 02:49:48 +00:00
2009-10-31 21:35:25 +00:00
## License
2016-01-02 23:43:46 +00:00
Source Copyright © 2009-2016 Phil Hagelberg, Alex Osborne, Dan Larkin, and
[contributors ](https://github.com/technomancy/leiningen/contributors ).
2011-07-20 02:04:15 +00:00
Distributed under the Eclipse Public License, the same as Clojure
uses. See the file COPYING.
2009-10-31 21:35:25 +00:00
2009-11-06 04:36:27 +00:00
Thanks to Stuart Halloway for Lancet and Tim Dysinger for convincing
me that good builds are important.
2011-07-20 02:04:15 +00:00
Images Copyright © 2010 Phil Hagelberg. Distributed under the Creative
Commons Attribution + ShareAlike
2013-01-10 19:57:24 +00:00
License. [Full-size version ](http://leiningen.org/img/leiningen-full.jpg )
2011-07-20 02:04:15 +00:00
available.