Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 252 lines (192 sloc) 11.158 kb
88b5360 @technomancy Initial commit.
authored
1 # Leiningen
2
410b4e7 @technomancy This is not 1.0-level material... yet.
authored
3 > "Leiningen!" he shouted. "You're insane! They're not creatures you can
4 > fight--they're an elemental--an 'act of God!' Ten miles long, two
5 > miles wide--ants, nothing but ants! And every single one of them a
045e24d @technomancy Minor readme tweaks.
authored
6 > fiend from hell..."
410b4e7 @technomancy This is not 1.0-level material... yet.
authored
7 > -- from Leiningen Versus the Ants by Carl Stephenson
88b5360 @technomancy Initial commit.
authored
8
9 Leiningen is a build tool for Clojure designed to not set your hair on fire.
10
5f5c0ba @technomancy Use a banner image in the readme instead of the full logo.
authored
11 <img src="http://github.com/downloads/technomancy/leiningen/leiningen-banner.png" alt="Leiningen logo" title="The man himself" align="right" />
dff976c @technomancy Documentation update.
authored
12
c5ba551 @technomancy Add motivation to README
authored
13 Building Clojure projects with tools designed for Java can be an
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
14 exercise in frustration. With Leiningen, you describe your build with
15 Clojure.
c5ba551 @technomancy Add motivation to README
authored
16
410b4e7 @technomancy This is not 1.0-level material... yet.
authored
17 ## Installation
b62c7c0 @technomancy Added temporary install note.
authored
18
3abb1b0 @technomancy Spruce up the readme a bit.
authored
19 Leiningen bootstraps itself using the <tt>lein</tt> shell script;
575fd09 @technomancy README updates for Windows
authored
20 there is no separate 'install script'. It installs its dependencies
21 upon the first run on unix, so the first run will take longer.
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
22
f0220e6 @technomancy Fix some readme links.
authored
23 1. [Download the script](http://github.com/technomancy/leiningen/raw/stable/bin/lein).
70a6d19 @technomancy Bump version to 1.0.0-SNAPSHOT
authored
24 2. Place it on your path and chmod it to be executable.
5ff106e @technomancy Auto-self-install on demand.
authored
25
a50cef3 @technomancy bin/lein placement notes.
authored
26 I like to place it in ~/bin, but it can go anywhere on the $PATH.
575fd09 @technomancy README updates for Windows
authored
27 To track development of Leiningen you may use [the master version of the
5ff106e @technomancy Auto-self-install on demand.
authored
28 script](http://github.com/technomancy/leiningen/raw/master/bin/lein)
29 instead. See the "Building" section below.
a2f17c0 @technomancy Update readme for easier dev installation; add some TODOs.
authored
30
575fd09 @technomancy README updates for Windows
authored
31 On Windows most users can
32 1. Download the Windows distribution
33 [lein-win32.zip](http://github.com/downloads/technomancy/leiningen/lein-win32.zip)
34 2. Unzip in a folder of choice.
35 3. Include the "lein" directory in PATH.
36
37 If you have wget.exe or curl.exe already installed and in PATH, you
38 can download either [the stable version
39 lein.bat](http://github.com/technomancy/leiningen/raw/stable/bin/lein.bat),
40 or [the development
41 version](http://github.com/technomancy/leiningen/raw/master/bin/lein.bat)
42 and use self-install.
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
43
88b5360 @technomancy Initial commit.
authored
44 ## Usage
45
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
46 The
47 [tutorial](http://github.com/technomancy/leiningen/blob/master/TUTORIAL.md)
48 has a detailed walk-through of the steps involved in creating a new
49 project, but here are the commonly-used tasks:
50
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
51 $ lein new NAME # generate a new project skeleton
52
88b5360 @technomancy Initial commit.
authored
53 $ lein deps # install dependencies in lib/
54
4d4aa03 @technomancy Allow test task to take namespaces as an argument.
authored
55 $ lein test [TESTS] # run the tests in the TESTS namespaces, or all tests
73115a5 Added test namespace/task.
Phil Hagelberg authored
56
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
57 $ lein repl # launch an interactive REPL session and socket server
88b5360 @technomancy Initial commit.
authored
58
eea1ebb @technomancy Misc documentation tweaks.
authored
59 $ lein jar # package up the whole project as a .jar file
c558fe9 @technomancy Add clean command.
authored
60
77d8a5c @technomancy Document 1.3.0 features.
authored
61 $ lein install [NAME VERSION] # install a project
62
eea1ebb @technomancy Misc documentation tweaks.
authored
63 Use <tt>lein help</tt> to see a complete list. <tt>lein help
64 $TASK</tt> shows the usage for a specific one.
bda58ab @technomancy Add new task for generating project skeletons.
authored
65
77d8a5c @technomancy Document 1.3.0 features.
authored
66 You can also chain tasks together in a single command by using commas:
67
68 $ lein clean, test foo.test-core, jar
a920ab9 @technomancy Added documentation TODOs.
authored
69
77d8a5c @technomancy Document 1.3.0 features.
authored
70 Most tasks need to be run from somewhere inside a project directory to
4be3d03 @ivey Merge Colin Jones' lein-plugin plugin for managing plugins
ivey authored
71 work, but some (<tt>new</tt>, <tt>help</tt>, <tt>version</tt>,
72 <tt>plugin</tt>, and the two-argument version of <tt>install</tt>) may
73 run from anywhere.
77d8a5c @technomancy Document 1.3.0 features.
authored
74
75 The install task places shell scripts in the <tt>~/.lein/bin</tt>
76 directory for projects that include them, so if you want to take
6d27faf @technomancy Readme formatting.
authored
77 advantage of this, you should put it on your <tt>$PATH</tt>.
a920ab9 @technomancy Added documentation TODOs.
authored
78
88b5360 @technomancy Initial commit.
authored
79 ## Configuration
80
6d27faf @technomancy Readme formatting.
authored
81 Place a <tt>project.clj</tt> file in the project root like this:
88b5360 @technomancy Initial commit.
authored
82
ddf403d @technomancy Spin off swank into a subproject.
authored
83 (defproject leiningen "0.5.0-SNAPSHOT"
7227039 @technomancy Mostly todos.
authored
84 :description "A build tool designed to not set your hair on fire."
f390c60 @technomancy Explain optional project.clj keys in readme. Note publishing deps on …
authored
85 :url "http://github.com/technomancy/leiningen"
da5571e @technomancy NEWS for 1.3.1.
authored
86 :dependencies [[org.clojure/clojure "1.1.0"]
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
87 [org.clojure/clojure-contrib "1.1.0"]]
eea1ebb @technomancy Misc documentation tweaks.
authored
88 :dev-dependencies [[swank-clojure "1.2.1"]])
42cdf1f @technomancy Version is no longer optional in defproject.
authored
89
3abb1b0 @technomancy Spruce up the readme a bit.
authored
90 The <tt>lein new</tt> task generates a project skeleton with an
91 appropriate starting point from which you can work. See the
92 [sample.project.clj](http://github.com/technomancy/leiningen/blob/master/sample.project.clj)
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
93 file for a detailed listing of configuration options.
4b65172 @technomancy Prompt to overwrite if pom.xml exists already.
authored
94
77d8a5c @technomancy Document 1.3.0 features.
authored
95 You can also have user-level configuration that applies for all
6d27faf @technomancy Readme formatting.
authored
96 projects. The <tt>~/.lein/init.clj</tt> file will be loaded every time
e85e390 @technomancy Doco updates.
authored
97 Leiningen launches; any arbitrary code may go there. This code is
98 executed inside Leiningen itself, not in your project. Set the
99 <tt>:repl-init-script</tt> key in project.clj to point to a file if
100 you want code executed inside your project.
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
101
102 You can also manage your plugins with the <tt>plugin</tt> task. Use
103 the same arguments you would put in the Leiningen :dev-dependencies if
104 you were only using the plugin on a single project.
4be3d03 @ivey Merge Colin Jones' lein-plugin plugin for managing plugins
ivey authored
105
d900c66 @technomancy Documentation updates. Mention JAVA_CMD, contribution guidelines.
authored
106 $ lein plugin install lein-clojars/lein-clojars "0.6.0"
4be3d03 @ivey Merge Colin Jones' lein-plugin plugin for managing plugins
ivey authored
107
108 See the plugin task's help for more information.
109
d900c66 @technomancy Documentation updates. Mention JAVA_CMD, contribution guidelines.
authored
110 $ lein plugin help
4be3d03 @ivey Merge Colin Jones' lein-plugin plugin for managing plugins
ivey authored
111
b3e0233 @technomancy Added FAQ, License.
authored
112 ## FAQ
113
0802503 @technomancy Fix markdown in readme.
authored
114 **Q:** How do you pronounce Leiningen?
115 **A:** It's LINE-ing-en. I think.
b3e0233 @technomancy Added FAQ, License.
authored
116
0802503 @technomancy Fix markdown in readme.
authored
117 **Q:** What does this offer over [Lancet](http://github.com/stuarthalloway/lancet)?
118 **A:** Lancet is more of a library than a build tool. It doesn't predefine
b3e0233 @technomancy Added FAQ, License.
authored
119 any tasks apart from what Ant itself offers, so there is nothing
42cdf1f @technomancy Version is no longer optional in defproject.
authored
120 Clojure-specific in it. Leiningen builds on Lancet, but takes
121 things further. In addition, it includes some Maven functionality
122 for dependencies.
b3e0233 @technomancy Added FAQ, License.
authored
123
0802503 @technomancy Fix markdown in readme.
authored
124 **Q:** But Maven is terrifying!
125 **A:** That's not a question. Anyway, Leiningen only uses the dependency
b3e0233 @technomancy Added FAQ, License.
authored
126 resolution parts of Maven, which are quite tame. For the actual
127 task execution cycles it uses Ant under the covers via Lancet.
128
0802503 @technomancy Fix markdown in readme.
authored
129 **Q:** But Ant is terrifying!
130 **A:** That's [true](http://www.defmacro.org/ramblings/lisp.html). Ant is
b3e0233 @technomancy Added FAQ, License.
authored
131 an interpreter for a [procedural language with a regrettable
132 syntax](http://blogs.tedneward.com/2005/08/22/When+Do+You+Use+XML+Again.aspx).
a2f17c0 @technomancy Update readme for easier dev installation; add some TODOs.
authored
133 But if you treat it as a standard library of build-related
134 functions and are able to write it with a more pleasing syntax, it's
135 not bad.
b3e0233 @technomancy Added FAQ, License.
authored
136
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
137 **Q:** What's a group ID? How do snapshots work?
138 **A:** See the
d36318c @technomancy Replace intro with tutorial.
authored
139 [tutorial](http://github.com/technomancy/leiningen/blob/master/TUTORIAL.md)
eea1ebb @technomancy Misc documentation tweaks.
authored
140 for background.
141
142 **Q:** How should I pick my version numbers?
143 **A:** Use [semantic versioning](http://semver.org).
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
144
045e24d @technomancy Minor readme tweaks.
authored
145 **Q:** What if my project depends on jars that aren't in any repository?
72ff86d @technomancy Minor readme/todo tweaks.
authored
146 **A:** Open-source jars can be uploaded to Clojars (see "Publishing"
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
147 in the tutorial), though be sure to use the group-id of
148 "org.clojars.$USERNAME" in order to avoid conflicts and to allow the
149 original authors to claim it in the future once they get around to
150 uploading. Alternatively you can do a one-off install into your
4a69976 @technomancy Mention mvn invocation output in lein deps for non-hosted dependencies.
authored
151 local repository in ~/.m2 with Maven. Add a dependency to
152 project.clj that doesn't exist in any remote repository and run
dff976c @technomancy Documentation update.
authored
153 <tt>lein deps</tt>. It won't succeed, but the output will include
154 the <tt>mvn</tt> invocation to do this. It's _much_ better to get
155 the dependency in a remote repository for repeatability reasons
156 though. For teams working on private projects
157 [Hudson](http://hudson-ci.org/) works well.
f390c60 @technomancy Explain optional project.clj keys in readme. Note publishing deps on …
authored
158
eea1ebb @technomancy Misc documentation tweaks.
authored
159 **Q:** How do I write my own tasks?
160 **A:** If it's a task that may be useful to more than just your
161 project, you should make it into a
162 [plugin](http://github.com/technomancy/leiningen/blob/master/PLUGINS.md).
163 You can also include one-off tasks in your src/leiningen/ directory
164 if they're not worth spinning off; the plugin guide shows how.
165
166 **Q:** I want to hack two projects in parallel, but it's annoying to switch between them.
dff976c @technomancy Documentation update.
authored
167 **A:** Use a feature called _checkout dependencies_. If you create
eea1ebb @technomancy Misc documentation tweaks.
authored
168 a directory called <tt>checkouts</tt> in your project root and
169 symlink some other projects into it, Leiningen will allow you to
170 hack on them in parallel. That means changes in the dependency will
171 be visible in the main project without having to go through the
172 whole install/switch-projects/deps/restart-swank cycle.
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
173
c0df45a Extra space at end of question.
Matt Revelle authored
174 **Q:** Is it possible to exclude indirect dependencies?
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
175 **A:** Yes. Some libraries, such as log4j, depend on projects that are
bea0cfa Added documentation about :exclusions in :dependencies to the README …
Matt Revelle authored
176 not included in public repositories and unnecessary for basic
177 functionality. Projects listed as :dependencies may exclude
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
178 any of their dependencies by using the :exclusions key. See
179 sample.project.clj for details.
180
181 **Q:** It says a required artifact is missing for "super-pom". What's that?
182 **A:** The Maven API that Leiningen uses refers to your project as
183 "super-pom". It's just a quirk of the API. It probably means there
184 is a typo in your :dependency declaration in project.clj.
bea0cfa Added documentation about :exclusions in :dependencies to the README …
Matt Revelle authored
185
eea1ebb @technomancy Misc documentation tweaks.
authored
186 **Q:** What does java.lang.NoSuchMethodError: clojure.lang.RestFn.<init>(I)V mean?
187 **A:** It means you have some code that was AOT (ahead-of-time)
188 compiled with a different version of Clojure than the one you're
189 currently using. If it persists after running <tt>lein clean</tt> then it
190 is a problem with your dependencies. If you depend on contrib, make
191 sure the contrib version matches the Clojure version. Also note for
192 your own project that AOT compilation in Clojure is much less
193 important than it is in other languages. There are a few
194 language-level features that must be AOT-compiled to work, generally
195 for Java interop. If you are not using any of these features, you
196 should not AOT-compile your project if other projects may depend
197 upon it.
d900c66 @technomancy Documentation updates. Mention JAVA_CMD, contribution guidelines.
authored
198
199 **Q:** What can be done to speed up launch?
200 **A:** The "server" Hotspot compiler in the JVM is optimized for
201 long-running processes and has quite a poor startup time. Leiningen
202 will try to launch a client JVM, but this only works on 32-bit JVM
203 installations. If you are on a 64-bit machine you can still use a
204 client JVM; on Ubuntu use the ia32-sun-java6-bin package. Once
205 you've installed it, set the <tt>JAVA_CMD</tt> environment variable
206 to <tt>/usr/lib/jvm/ia32-java-6-sun/bin/java</tt>. Using the
207 <tt>interactive</tt> command, the <tt>swank-clojure</tt> plugin, and
208 the socket started by the <tt>repl</tt> command are also good ways
209 to avoid paying the startup time penalty.
210
211 ## Contributing
212
213 Please report issues on the [Github issue
214 tracker](https://github.com/technomancy/leiningen/issues) or the
215 [mailing list](http://groups.google.com/group/leiningen). Personal
216 email addresses are not appropriate for bug reports. See the file
217 HACKING.md for more details on how Leiningen's codebase is structured.
045e24d @technomancy Minor readme tweaks.
authored
218
ae98527 @technomancy Add Building section to README.
authored
219 ## Building
220
a29b20c @technomancy Clarify bootstrap process.
authored
221 You don't need to "build" Leiningen per se, but when you're using a
222 checkout you will need to get its dependencies in place. If you have a
a53e419 @technomancy Expand on bootstrap instructions.
authored
223 copy of an older Leiningen version around (at least 1.1.0, installed
224 as lein-stable, for example), then you can run "lein-stable deps" in
225 your checkout. If Leiningen's dependencies change,
ae98527 @technomancy Add Building section to README.
authored
226
a29b20c @technomancy Clarify bootstrap process.
authored
227 Alternatively a <tt>lein self-install</tt> will usually get you what
228 you need. However, this will occasionally fail for very new SNAPSHOT
229 versions since the standalone jar will not have been uploaded yet.
ae98527 @technomancy Add Building section to README.
authored
230
a29b20c @technomancy Clarify bootstrap process.
authored
231 You can also use Maven, just for variety's sake:
ae98527 @technomancy Add Building section to README.
authored
232
e9a7f03 @technomancy Documentation updates for 1.3.0.
authored
233 $ mvn dependency:copy-dependencies
ae98527 @technomancy Add Building section to README.
authored
234 $ mv target/dependency lib
235
a50cef3 @technomancy bin/lein placement notes.
authored
236 Symlink bin/lein from your checkout into a location on the $PATH. The
237 script can figure out when it's being called from inside a checkout
238 and use the checkout rather than the self-install uberjar.
239
e9a7f03 @technomancy Documentation updates for 1.3.0.
authored
240 See the file HACKING.md for instructions on contributing.
cd4b569 @technomancy Keep dev-dependencies in lib/dev, out of the way of uberjar.
authored
241
88b5360 @technomancy Initial commit.
authored
242 ## License
243
6c36bbb @technomancy Refactor clean task. Fixes #64.
authored
244 Copyright (C) 2009-2010 Phil Hagelberg, Alex Osborne, Dan Larkin, and
7f5b862 @technomancy Ready for 1.4.0-SNAPSHOT.
authored
245 [contributors](https://www.ohloh.net/p/leiningen/contributors).
88b5360 @technomancy Initial commit.
authored
246
79b969b @technomancy Move away from build.clj to project.clj.
authored
247 Thanks to Stuart Halloway for Lancet and Tim Dysinger for convincing
248 me that good builds are important.
249
88b5360 @technomancy Initial commit.
authored
250 Distributed under the Eclipse Public License, the same as Clojure
251 uses. See the file COPYING.
Something went wrong with that request. Please try again.