Skip to content

HTTPS clone URL

Subversion checkout URL

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