2009-10-31 21:35:25 +00:00
|
|
|
|
# Leiningen
|
|
|
|
|
|
2009-11-12 05:25:16 +00:00
|
|
|
|
> "Leiningen!" he shouted. "You're insane! They're not creatures you can
|
|
|
|
|
> 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..."
|
2009-11-12 05:25:16 +00:00
|
|
|
|
> -- from Leiningen Versus the Ants by Carl Stephenson
|
2009-10-31 21:35:25 +00:00
|
|
|
|
|
|
|
|
|
Leiningen is a build tool for Clojure designed to not set your hair on fire.
|
|
|
|
|
|
2010-12-03 02:16:16 +00:00
|
|
|
|
<img src="https://github.com/downloads/technomancy/leiningen/leiningen-banner.png" alt="Leiningen logo" title="The man himself" align="right" />
|
2010-07-18 20:28:49 +00:00
|
|
|
|
|
2009-11-15 04:56:52 +00:00
|
|
|
|
Building Clojure projects with tools designed for Java can be an
|
2010-11-07 23:50:25 +00:00
|
|
|
|
exercise in frustration. With Leiningen, you describe your build with
|
|
|
|
|
Clojure.
|
2009-11-15 04:56:52 +00:00
|
|
|
|
|
2009-11-12 05:25:16 +00:00
|
|
|
|
## Installation
|
2009-11-02 07:02:16 +00:00
|
|
|
|
|
2010-06-15 05:23:13 +00:00
|
|
|
|
Leiningen bootstraps itself using the <tt>lein</tt> shell script;
|
2010-09-10 17:02:26 +00:00
|
|
|
|
there is no separate 'install script'. It installs its dependencies
|
|
|
|
|
upon the first run on unix, so the first run will take longer.
|
2010-03-13 05:04:11 +00:00
|
|
|
|
|
2010-12-03 02:16:16 +00:00
|
|
|
|
1. [Download the script](https://github.com/technomancy/leiningen/raw/stable/bin/lein).
|
2009-11-20 01:22:52 +00:00
|
|
|
|
2. Place it on your path and chmod it to be executable.
|
2010-09-03 03:16:54 +00:00
|
|
|
|
|
2010-11-11 04:49:45 +00:00
|
|
|
|
I like to place it in ~/bin, but it can go anywhere on the $PATH.
|
2010-09-10 17:02:26 +00:00
|
|
|
|
To track development of Leiningen you may use [the master version of the
|
2010-12-03 02:16:16 +00:00
|
|
|
|
script](https://github.com/technomancy/leiningen/raw/master/bin/lein)
|
2010-09-03 03:16:54 +00:00
|
|
|
|
instead. See the "Building" section below.
|
2009-11-24 05:26:47 +00:00
|
|
|
|
|
2010-09-10 17:02:26 +00:00
|
|
|
|
On Windows most users can
|
2011-03-16 01:44:53 +00:00
|
|
|
|
|
2010-09-10 17:02:26 +00:00
|
|
|
|
1. Download the Windows distribution
|
2011-01-01 21:55:56 +00:00
|
|
|
|
[leiningen-1.4.2-win32.zip](https://github.com/downloads/technomancy/leiningen/leiningen-1.4.2-win32.zip)
|
2010-09-10 17:02:26 +00:00
|
|
|
|
2. Unzip in a folder of choice.
|
|
|
|
|
3. Include the "lein" directory in PATH.
|
|
|
|
|
|
|
|
|
|
If you have wget.exe or curl.exe already installed and in PATH, you
|
|
|
|
|
can download either [the stable version
|
2010-12-03 02:16:16 +00:00
|
|
|
|
lein.bat](https://github.com/technomancy/leiningen/raw/stable/bin/lein.bat),
|
2010-09-10 17:02:26 +00:00
|
|
|
|
or [the development
|
2010-12-03 02:16:16 +00:00
|
|
|
|
version](https://github.com/technomancy/leiningen/raw/master/bin/lein.bat)
|
2010-09-10 17:02:26 +00:00
|
|
|
|
and use self-install.
|
2010-03-13 05:04:11 +00:00
|
|
|
|
|
2009-10-31 21:35:25 +00:00
|
|
|
|
## Usage
|
|
|
|
|
|
2010-06-19 03:56:36 +00:00
|
|
|
|
The
|
2010-12-03 02:16:16 +00:00
|
|
|
|
[tutorial](https://github.com/technomancy/leiningen/blob/stable/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:
|
|
|
|
|
|
2010-06-05 20:26:52 +00:00
|
|
|
|
$ lein new NAME # generate a new project skeleton
|
|
|
|
|
|
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
|
|
|
|
|
2010-11-07 23:50:25 +00:00
|
|
|
|
$ lein repl # launch an interactive REPL session and socket server
|
2009-10-31 21:35:25 +00:00
|
|
|
|
|
2010-06-22 02:21:13 +00:00
|
|
|
|
$ lein jar # package up the whole project as a .jar file
|
2009-11-09 06:09:39 +00:00
|
|
|
|
|
2010-08-18 05:21:53 +00:00
|
|
|
|
$ lein install [NAME VERSION] # install a project
|
|
|
|
|
|
2010-06-22 02:21:13 +00:00
|
|
|
|
Use <tt>lein help</tt> to see a complete list. <tt>lein help
|
|
|
|
|
$TASK</tt> shows the usage for a specific one.
|
2009-11-20 01:50:33 +00:00
|
|
|
|
|
2010-08-18 05:21:53 +00:00
|
|
|
|
You can also chain tasks together in a single command by using commas:
|
|
|
|
|
|
|
|
|
|
$ lein 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
|
2010-10-25 02:49:48 +00:00
|
|
|
|
work, but some (<tt>new</tt>, <tt>help</tt>, <tt>version</tt>,
|
|
|
|
|
<tt>plugin</tt>, and the two-argument version of <tt>install</tt>) may
|
|
|
|
|
run from anywhere.
|
2010-08-18 05:21:53 +00:00
|
|
|
|
|
|
|
|
|
The install task places shell scripts in the <tt>~/.lein/bin</tt>
|
|
|
|
|
directory for projects that include them, so if you want to take
|
2010-10-02 05:57:29 +00:00
|
|
|
|
advantage of this, you should put it on your <tt>$PATH</tt>.
|
2010-08-17 05:05:24 +00:00
|
|
|
|
|
2009-10-31 21:35:25 +00:00
|
|
|
|
## Configuration
|
|
|
|
|
|
2010-10-02 05:57:29 +00:00
|
|
|
|
Place a <tt>project.clj</tt> file in the project root like this:
|
2009-10-31 21:35:25 +00:00
|
|
|
|
|
2009-11-15 04:47:48 +00:00
|
|
|
|
(defproject leiningen "0.5.0-SNAPSHOT"
|
2010-10-16 16:35:35 +00:00
|
|
|
|
:description "A build tool designed to not set your hair on fire."
|
2009-12-02 06:28:58 +00:00
|
|
|
|
:url "http://github.com/technomancy/leiningen"
|
2010-08-24 04:40:07 +00:00
|
|
|
|
:dependencies [[org.clojure/clojure "1.1.0"]
|
2010-11-07 23:50:25 +00:00
|
|
|
|
[org.clojure/clojure-contrib "1.1.0"]]
|
2010-06-22 02:21:13 +00:00
|
|
|
|
:dev-dependencies [[swank-clojure "1.2.1"]])
|
2009-11-14 22:24:36 +00:00
|
|
|
|
|
2010-06-15 05:23:13 +00:00
|
|
|
|
The <tt>lein new</tt> task generates a project skeleton with an
|
|
|
|
|
appropriate starting point from which you can work. See the
|
2010-12-03 02:16:16 +00:00
|
|
|
|
[sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj)
|
2010-06-19 03:56:36 +00:00
|
|
|
|
file for a detailed listing of configuration options.
|
2009-11-17 04:24:36 +00:00
|
|
|
|
|
2010-08-18 05:21:53 +00:00
|
|
|
|
You can also have user-level configuration that applies for all
|
2010-10-02 05:57:29 +00:00
|
|
|
|
projects. The <tt>~/.lein/init.clj</tt> file will be loaded every time
|
2010-11-19 05:39:44 +00:00
|
|
|
|
Leiningen launches; any arbitrary code may go there. This code is
|
|
|
|
|
executed inside Leiningen itself, not in your project. Set the
|
2011-03-16 01:44:53 +00:00
|
|
|
|
<tt>:repl-init</tt> key in project.clj to point to a namespace if
|
2010-11-19 05:39:44 +00:00
|
|
|
|
you want code executed inside your project.
|
2010-11-07 23:50:25 +00:00
|
|
|
|
|
|
|
|
|
You can also manage your plugins with the <tt>plugin</tt> task. Use
|
|
|
|
|
the same arguments you would put in the Leiningen :dev-dependencies if
|
|
|
|
|
you were only using the plugin on a single project.
|
2010-10-25 02:49:48 +00:00
|
|
|
|
|
2010-11-04 02:46:13 +00:00
|
|
|
|
$ lein plugin install lein-clojars/lein-clojars "0.6.0"
|
2010-10-25 02:49:48 +00:00
|
|
|
|
|
|
|
|
|
See the plugin task's help for more information.
|
|
|
|
|
|
2010-11-04 02:46:13 +00:00
|
|
|
|
$ lein plugin help
|
2010-10-25 02:49:48 +00:00
|
|
|
|
|
2009-11-05 04:25:13 +00:00
|
|
|
|
## FAQ
|
|
|
|
|
|
2009-11-06 04:34:14 +00:00
|
|
|
|
**Q:** How do you pronounce Leiningen?
|
2011-03-22 04:07:10 +00:00
|
|
|
|
**A:** It's LINE-ing-en. ['laɪnɪŋən]
|
2009-11-05 04:25:13 +00:00
|
|
|
|
|
2010-12-03 02:16:16 +00:00
|
|
|
|
**Q:** What does this offer over [Lancet](https://github.com/stuarthalloway/lancet)?
|
2009-11-06 04:34:14 +00:00
|
|
|
|
**A:** Lancet is more of a library than a build tool. It doesn't predefine
|
2009-11-05 04:25:13 +00:00
|
|
|
|
any tasks apart from what Ant itself offers, so there is nothing
|
2009-11-14 22:24:36 +00:00
|
|
|
|
Clojure-specific in it. Leiningen builds on Lancet, but takes
|
|
|
|
|
things further. In addition, it includes some Maven functionality
|
|
|
|
|
for dependencies.
|
2009-11-05 04:25:13 +00:00
|
|
|
|
|
2009-11-06 04:34:14 +00:00
|
|
|
|
**Q:** But Maven is terrifying!
|
|
|
|
|
**A:** That's not a question. Anyway, Leiningen only uses the dependency
|
2009-11-05 04:25:13 +00:00
|
|
|
|
resolution parts of Maven, which are quite tame. For the actual
|
|
|
|
|
task execution cycles it uses Ant under the covers via Lancet.
|
|
|
|
|
|
2009-11-06 04:34:14 +00:00
|
|
|
|
**Q:** But Ant is terrifying!
|
|
|
|
|
**A:** That's [true](http://www.defmacro.org/ramblings/lisp.html). Ant is
|
2009-11-05 04:25:13 +00:00
|
|
|
|
an interpreter for a [procedural language with a regrettable
|
|
|
|
|
syntax](http://blogs.tedneward.com/2005/08/22/When+Do+You+Use+XML+Again.aspx).
|
2009-11-24 05:26:47 +00:00
|
|
|
|
But if you treat it as a standard library of build-related
|
|
|
|
|
functions and are able to write it with a more pleasing syntax, it's
|
|
|
|
|
not bad.
|
2009-11-05 04:25:13 +00:00
|
|
|
|
|
2010-03-13 05:04:11 +00:00
|
|
|
|
**Q:** What's a group ID? How do snapshots work?
|
|
|
|
|
**A:** See the
|
2010-12-03 02:16:16 +00:00
|
|
|
|
[tutorial](https://github.com/technomancy/leiningen/blob/stable/TUTORIAL.md)
|
2010-06-22 02:21:13 +00:00
|
|
|
|
for background.
|
|
|
|
|
|
|
|
|
|
**Q:** How should I pick my version numbers?
|
|
|
|
|
**A:** Use [semantic versioning](http://semver.org).
|
2010-03-13 05:04:11 +00:00
|
|
|
|
|
2011-03-16 01:44:53 +00:00
|
|
|
|
**Q:** It says a required artifact is missing for "super-pom". What's that?
|
|
|
|
|
**A:** The Maven API that Leiningen uses refers to your project as
|
|
|
|
|
"super-pom". It's just a quirk of the API. It probably means there
|
|
|
|
|
is a typo in your :dependency declaration in project.clj.
|
|
|
|
|
|
2009-12-21 04:37:19 +00:00
|
|
|
|
**Q:** What if my project depends on jars that aren't in any repository?
|
2011-03-16 01:44:53 +00:00
|
|
|
|
**A:** The [deploy guide](https://github.com/technomancy/leiningen/blob/stable/DEPLOY.md)
|
|
|
|
|
explains how to set up a private repository.
|
2009-12-02 06:28:58 +00:00
|
|
|
|
|
2010-06-22 02:21:13 +00:00
|
|
|
|
**Q:** How do I write my own tasks?
|
|
|
|
|
**A:** If it's a task that may be useful to more than just your
|
|
|
|
|
project, you should make it into a
|
2010-12-03 02:16:16 +00:00
|
|
|
|
[plugin](https://github.com/technomancy/leiningen/blob/stable/PLUGINS.md).
|
2010-06-22 02:21:13 +00:00
|
|
|
|
You can also include one-off tasks in your src/leiningen/ directory
|
|
|
|
|
if they're not worth spinning off; the plugin guide shows how.
|
|
|
|
|
|
|
|
|
|
**Q:** I want to hack two projects in parallel, but it's annoying to switch between them.
|
2010-12-03 02:10:17 +00:00
|
|
|
|
**A:** Use a feature called _checkout dependencies_. If you create a
|
|
|
|
|
directory called <tt>checkouts</tt> in your project root and symlink
|
|
|
|
|
some other project roots into it, Leiningen will allow you to hack
|
|
|
|
|
on them in parallel. That means changes in the dependency will be
|
|
|
|
|
visible in the main project without having to go through the whole
|
|
|
|
|
install/switch-projects/deps/restart-swank cycle. Note that this is
|
|
|
|
|
not a replacement for listing the project in :dependencies; it
|
|
|
|
|
simply supplements that.
|
2010-03-13 05:04:11 +00:00
|
|
|
|
|
2009-12-21 21:37:38 +00:00
|
|
|
|
**Q:** Is it possible to exclude indirect dependencies?
|
2010-06-05 20:26:52 +00:00
|
|
|
|
**A:** Yes. Some libraries, such as log4j, depend on projects that are
|
2009-12-21 21:28:19 +00:00
|
|
|
|
not included in public repositories and unnecessary for basic
|
|
|
|
|
functionality. Projects listed as :dependencies may exclude
|
2010-06-05 20:26:52 +00:00
|
|
|
|
any of their dependencies by using the :exclusions key. See
|
|
|
|
|
sample.project.clj for details.
|
|
|
|
|
|
2010-06-22 02:21:13 +00:00
|
|
|
|
**Q:** What does java.lang.NoSuchMethodError: clojure.lang.RestFn.<init>(I)V mean?
|
|
|
|
|
**A:** It means you have some code that was AOT (ahead-of-time)
|
|
|
|
|
compiled with a different version of Clojure than the one you're
|
|
|
|
|
currently using. If it persists after running <tt>lein clean</tt> then it
|
2011-03-22 04:07:10 +00:00
|
|
|
|
is a problem with your dependencies. Note that for
|
2010-06-22 02:21:13 +00:00
|
|
|
|
your own project that AOT compilation in Clojure is much less
|
|
|
|
|
important than it is in other languages. There are a few
|
|
|
|
|
language-level features that must be AOT-compiled to work, generally
|
|
|
|
|
for Java interop. If you are not using any of these features, you
|
|
|
|
|
should not AOT-compile your project if other projects may depend
|
|
|
|
|
upon it.
|
2010-11-04 02:46:13 +00:00
|
|
|
|
|
|
|
|
|
**Q:** What can be done to speed up launch?
|
2010-11-21 04:37:36 +00:00
|
|
|
|
**A:** The main delay involved in Leiningen comes from starting the JVM.
|
|
|
|
|
Launching "lein interactive" will give you an interactive session so
|
|
|
|
|
you can run many tasks against the same process instead of launching
|
|
|
|
|
a new one every time. Depending on your editor you may also be able
|
|
|
|
|
to take advantage of its Clojure integration.
|
|
|
|
|
|
|
|
|
|
**Q:** Still too slow; what else can make startup faster?
|
|
|
|
|
**A:** There are two flavours of the JVM, client and server. The
|
|
|
|
|
server is optimized for long-running processes and has quite a poor
|
|
|
|
|
startup time. Leiningen will try to launch a client JVM, but this
|
|
|
|
|
only works on 32-bit JVM installations. If you are on a 64-bit
|
|
|
|
|
machine you can still use a client JVM if you install 32-bit
|
|
|
|
|
packages; on Ubuntu try ia32-sun-java6-bin. Once you've installed
|
|
|
|
|
it, set the <tt>JAVA_CMD</tt> environment variable to
|
|
|
|
|
<tt>/usr/lib/jvm/ia32-java-6-sun/bin/java</tt>.
|
2011-02-19 04:43:29 +00:00
|
|
|
|
|
|
|
|
|
**Q:** I don't have access to stdin inside my project.
|
|
|
|
|
**A:** There's a bug in the Ant library that Leiningen uses to spawn
|
|
|
|
|
new processes that blocks access to console input. This means that
|
|
|
|
|
functions like <tt>read-line</tt> will not work as expected in most
|
|
|
|
|
contexts, though the <tt>repl</tt> task necessarily includes a
|
|
|
|
|
workaround. You can also use <tt>java -cp `lein classpath`
|
|
|
|
|
my.main.namespace</tt> to launch a process with the correct
|
|
|
|
|
classpath that still has access to stdin.
|
2010-11-04 02:46:13 +00:00
|
|
|
|
|
|
|
|
|
## Contributing
|
|
|
|
|
|
|
|
|
|
Please report issues on the [Github issue
|
|
|
|
|
tracker](https://github.com/technomancy/leiningen/issues) or the
|
|
|
|
|
[mailing list](http://groups.google.com/group/leiningen). Personal
|
|
|
|
|
email addresses are not appropriate for bug reports. See the file
|
|
|
|
|
HACKING.md for more details on how Leiningen's codebase is structured.
|
2009-12-21 04:37:19 +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
|
|
|
|
|
checkout you will need to get its dependencies in place. If you have a
|
2010-11-10 22:05:59 +00:00
|
|
|
|
copy of an older Leiningen version around (at least 1.1.0, installed
|
|
|
|
|
as lein-stable, for example), then you can run "lein-stable deps" in
|
2010-11-21 04:37:36 +00:00
|
|
|
|
your checkout. If Leiningen's dependencies change it will be necessary
|
|
|
|
|
to remove the lib/ directory entirely before running "lein deps"
|
|
|
|
|
again. (This is not necessary for most projects, but Leiningen has
|
|
|
|
|
unique bootstrapping issues when working on itself.)
|
2010-07-28 03:13:56 +00:00
|
|
|
|
|
2010-10-06 03:23:01 +00:00
|
|
|
|
Alternatively a <tt>lein self-install</tt> will usually get you what
|
|
|
|
|
you need. However, this will occasionally fail for very new SNAPSHOT
|
|
|
|
|
versions since the standalone jar will not have been uploaded yet.
|
2010-07-28 03:13:56 +00:00
|
|
|
|
|
2010-10-06 03:23:01 +00:00
|
|
|
|
You can also use Maven, just for variety's sake:
|
2010-07-28 03:13:56 +00:00
|
|
|
|
|
2010-08-20 03:53:40 +00:00
|
|
|
|
$ mvn dependency:copy-dependencies
|
2010-07-28 03:13:56 +00:00
|
|
|
|
$ mv target/dependency lib
|
|
|
|
|
|
2010-11-11 04:49:45 +00:00
|
|
|
|
Symlink bin/lein from your checkout into a location on the $PATH. The
|
|
|
|
|
script can figure out when it's being called from inside a checkout
|
|
|
|
|
and use the checkout rather than the self-install uberjar.
|
|
|
|
|
|
2009-10-31 21:35:25 +00:00
|
|
|
|
## License
|
|
|
|
|
|
2011-02-11 03:26:15 +00:00
|
|
|
|
Copyright © 2009-2011 Phil Hagelberg, Alex Osborne, Dan Larkin, and
|
2011-03-16 01:44:53 +00:00
|
|
|
|
[other contributors](https://www.ohloh.net/p/leiningen/contributors).
|
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.
|
|
|
|
|
|
2009-10-31 21:35:25 +00:00
|
|
|
|
Distributed under the Eclipse Public License, the same as Clojure
|
|
|
|
|
uses. See the file COPYING.
|