2009-10-31 21:35:25 +00:00
|
|
|
# Leiningen
|
|
|
|
|
2012-01-13 02:04:57 +00:00
|
|
|
<img src="https://github.com/downloads/technomancy/leiningen/leiningen-banner.png"
|
|
|
|
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..."
|
2012-05-10 02:22:04 +00:00
|
|
|
> - from Leiningen Versus the Ants 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)
|
|
|
|
has a relatively recent version of Leiningen, try that first.
|
|
|
|
Otherwise you can install by hand:
|
|
|
|
|
2011-10-19 23:24:30 +00:00
|
|
|
Leiningen bootstraps itself using the `lein` shell script;
|
|
|
|
there is no separate install script. It installs its dependencies
|
2010-09-10 17:02:26 +00:00
|
|
|
upon the first run on unix, so the first run will take longer.
|
2010-03-13 05:04:11 +00:00
|
|
|
|
2012-06-14 23:26:39 +00:00
|
|
|
1. [Download the script](https://raw.github.com/technomancy/leiningen/preview/bin/lein).
|
2012-02-08 05:00:02 +00:00
|
|
|
2. Place it on your `$PATH`. (I like to use `~/bin`)
|
2011-10-19 23:24:30 +00:00
|
|
|
3. Set it to be executable. (`chmod 755 ~/bin/lein`)
|
2010-09-10 17:02:26 +00:00
|
|
|
|
2012-06-14 23:26:39 +00:00
|
|
|
The link above will get you the 2.x preview release. There is still a
|
|
|
|
lot of extant material on the Web concerning the older
|
|
|
|
[Leiningen 1.x](https://raw.github.com/technomancy/leiningen/stable/bin/lein)
|
|
|
|
version, which is still available if you need to work on older
|
|
|
|
projects that aren't compatible with 2.x yet. The
|
2012-03-13 17:08:09 +00:00
|
|
|
[upgrade guide](https://github.com/technomancy/leiningen/wiki/Upgrading)
|
2012-06-14 23:26:39 +00:00
|
|
|
has instructions on migrating to version 2.
|
2012-03-13 17:08:09 +00:00
|
|
|
|
2011-10-19 23:24:30 +00:00
|
|
|
On Windows most users can get
|
2012-06-14 23:26:39 +00:00
|
|
|
[the batch file](https://raw.github.com/technomancy/leiningen/preview/bin/lein.bat).
|
2010-09-10 17:02:26 +00:00
|
|
|
If you have wget.exe or curl.exe already installed and in PATH, you
|
2011-10-19 23:24:30 +00:00
|
|
|
can just run `lein self-install`, otherwise get the standalone jar from the
|
|
|
|
[downloads page](https://github.com/technomancy/leiningen/downloads).
|
|
|
|
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
|
|
|
|
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
|
2012-03-07 22:27:26 +00:00
|
|
|
[tutorial](https://github.com/technomancy/leiningen/blob/preview/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
|
|
|
|
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
|
|
|
|
2012-05-25 01:26:46 +00:00
|
|
|
See the [FAQ](https://github.com/technomancy/leiningen/blob/master/doc/FAQ.md)
|
2012-05-24 04:27:17 +00:00
|
|
|
for more details.
|
|
|
|
|
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."
|
|
|
|
:url "http://github.com/technomancy/myproject"
|
2012-05-25 01:26:46 +00:00
|
|
|
:dependencies [[org.clojure/clojure "1.4.0"]]
|
2012-01-13 00:10:32 +00:00
|
|
|
:plugins [[lein-ring "0.4.5"]])
|
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
|
2012-03-07 22:27:26 +00:00
|
|
|
[sample.project.clj](https://github.com/technomancy/leiningen/blob/preview/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
|
|
|
|
[profiles](https://github.com/technomancy/leiningen/blob/master/doc/PROFILES.md).
|
2012-01-29 21:59:07 +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
|
|
|
|
that modify behaivour 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
|
2012-04-12 17:12:05 +00:00
|
|
|
`swank-clojure`) then it should be added to the `:plugins` list in the
|
2012-07-14 00:35:33 +00:00
|
|
|
`:user` profile from `~/.lein/profiles.clj`. See the
|
|
|
|
[profiles guide](https://github.com/technomancy/leiningen/blob/preview/doc/PROFILES.md)
|
|
|
|
for details on how to add to your user profile. The
|
2012-03-07 22:27:26 +00:00
|
|
|
[plugin guide](https://github.com/technomancy/leiningen/blob/preview/doc/PLUGINS.md)
|
2012-01-13 02:04:57 +00:00
|
|
|
explains how to write plugins.
|
2010-10-25 02:49:48 +00:00
|
|
|
|
2010-11-04 02:46:13 +00:00
|
|
|
## Contributing
|
|
|
|
|
2012-01-16 04:43:12 +00:00
|
|
|
Please report issues on the
|
2012-05-10 02:22:04 +00:00
|
|
|
[GitHub issue tracker](https://github.com/technomancy/leiningen/issues)
|
2012-06-27 23:44:55 +00:00
|
|
|
or the [mailing list](http://librelist.com/browser/leiningen/).
|
2012-01-16 04:43:12 +00:00
|
|
|
Personal email addresses are **not** appropriate for bug reports. See
|
2012-05-10 02:22:04 +00:00
|
|
|
the
|
|
|
|
[readme for the leiningen-core library](https://github.com/technomancy/leiningen/blob/master/leiningen-core/README.md)
|
|
|
|
and `doc/PLUGINS.md` for more details on how Leiningen's codebase is
|
|
|
|
structured. Design discussions also occur in the
|
2012-03-07 02:06:21 +00:00
|
|
|
[#leiningen channel on Freenode](irc://chat.freenode.net#leiningen).
|
2009-12-21 04:37:19 +00:00
|
|
|
|
2012-05-10 02:22:04 +00:00
|
|
|
Patches are preferred as GitHub pull requests, though patches from
|
2011-12-05 03:43:14 +00:00
|
|
|
`git format-patch` are also welcome on the mailing list. Please use
|
|
|
|
topic branches when sending pull requests rather than committing
|
2011-07-20 02:04:15 +00:00
|
|
|
directly to master in order to minimize unnecessary merge commit
|
|
|
|
clutter.
|
|
|
|
|
|
|
|
Contributors who have had a single patch accepted may request commit
|
2012-01-13 00:10:32 +00:00
|
|
|
rights on the mailing list or in IRC. Please use your judgment
|
|
|
|
regarding potentially-destabilizing work and branches. Other
|
|
|
|
contributors will usually be glad to review topic branches before
|
|
|
|
merging if you ask on IRC or the mailing list.
|
2011-07-20 02:04:15 +00:00
|
|
|
|
|
|
|
Contributors are also welcome to request a free
|
|
|
|
[Leiningen sticker](http://twitpic.com/2e33r1) by asking on the
|
2012-05-10 02:22:04 +00:00
|
|
|
mailing list and mailing a self-addressed, stamped envelope.
|
2011-07-20 02:04:15 +00:00
|
|
|
|
2010-07-28 03:13:56 +00:00
|
|
|
## Building
|
|
|
|
|
2010-10-06 03:23:01 +00:00
|
|
|
You don't need to "build" Leiningen per se, but when you're using a
|
2012-01-13 02:04:57 +00:00
|
|
|
checkout you will need to get its dependencies in place.
|
2010-07-28 03:13:56 +00:00
|
|
|
|
2012-08-24 23:55:06 +00:00
|
|
|
For the master branch, use an existing Leiningen version to run `lein
|
|
|
|
install` in the `leiningen-core` subproject directory. When the
|
|
|
|
dependencies change you will also have to do `rm .lein-classpath` in
|
|
|
|
the project root. It's not yet possible to bootstrap a development
|
|
|
|
version of Leiningen without having an older version installed.
|
2010-11-11 04:49:45 +00:00
|
|
|
|
2012-02-08 02:15:24 +00:00
|
|
|
Once you've done that, symlink `bin/lein` to somewhere on your
|
2012-08-24 23:55:06 +00:00
|
|
|
`$PATH`. Usually you'll want to rename your existing installation to
|
|
|
|
keep them from interfering.
|
2012-03-20 20:53:09 +00:00
|
|
|
|
2009-10-31 21:35:25 +00:00
|
|
|
## License
|
|
|
|
|
2012-01-13 00:10:32 +00:00
|
|
|
Source Copyright © 2009-2012 Phil Hagelberg, Alex Osborne, Dan Larkin, and
|
2012-03-03 00:20:12 +00:00
|
|
|
[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
|
|
|
|
License. [Full-size version](https://github.com/downloads/technomancy/leiningen/leiningen-full.jpg)
|
|
|
|
available.
|