Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 273 lines (207 sloc) 11.715 kB
88b5360 @technomancy Initial commit.
authored
1 # Leiningen
2
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
3 <img src="https://github.com/downloads/technomancy/leiningen/leiningen-banner.png"
4 alt="Leiningen logo" title="The man himself" align="right" />
042ec19 @technomancy Update readme for lein2.
authored
5
410b4e7 @technomancy This is not 1.0-level material... yet.
authored
6 > "Leiningen!" he shouted. "You're insane! They're not creatures you can
7 > fight--they're an elemental--an 'act of God!' Ten miles long, two
8 > miles wide--ants, nothing but ants! And every single one of them a
045e24d @technomancy Minor readme tweaks.
authored
9 > fiend from hell..."
410b4e7 @technomancy This is not 1.0-level material... yet.
authored
10 > -- from Leiningen Versus the Ants by Carl Stephenson
88b5360 @technomancy Initial commit.
authored
11
44994c9 @technomancy Re-word docs in favour of the term "project automation".
authored
12 Leiningen is for automating Clojure projects without setting your hair on fire.
88b5360 @technomancy Initial commit.
authored
13
410b4e7 @technomancy This is not 1.0-level material... yet.
authored
14 ## Installation
b62c7c0 @technomancy Added temporary install note.
authored
15
03da3ae @technomancy Update todo.org.
authored
16 If your preferred
17 [package manager](https://github.com/technomancy/leiningen/wiki/Packaging)
18 has a relatively recent version of Leiningen, try that first.
19 Otherwise you can install by hand:
20
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
21 Leiningen bootstraps itself using the `lein` shell script;
22 there is no separate install script. It installs its dependencies
575fd09 @technomancy README updates for Windows
authored
23 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
24
49929c1 @technomancy Link directly to raw.github.com.
authored
25 1. [Download the script](https://raw.github.com/technomancy/leiningen/stable/bin/lein).
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
26 2. Place it on your path. (I like to use `~/bin`)
27 3. Set it to be executable. (`chmod 755 ~/bin/lein`)
575fd09 @technomancy README updates for Windows
authored
28
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
29 On Windows most users can get
30 [the batch file](https://raw.github.com/technomancy/leiningen/stable/bin/lein.bat).
575fd09 @technomancy README updates for Windows
authored
31 If you have wget.exe or curl.exe already installed and in PATH, you
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
32 can just run `lein self-install`, otherwise get the standalone jar from the
33 [downloads page](https://github.com/technomancy/leiningen/downloads).
34 If you have [Cygwin](http://www.cygwin.com/) you should be able to use
35 the shell script above rather than the batch file.
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
36
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
37 The `master` branch is currently undergoing massive changes for
24a89ee @technomancy Add note about master branch to readme.
authored
38 Leiningen 2.0; you should not expect it to work. If you want to build
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
39 from source for everyday use, use the `1.x` branch.
24a89ee @technomancy Add note about master branch to readme.
authored
40
88b5360 @technomancy Initial commit.
authored
41 ## Usage
42
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
43 The
2cb7ec9 @technomancy Update paths of documentation files.
authored
44 [tutorial](https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md)
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
45 has a detailed walk-through of the steps involved in creating a new
46 project, but here are the commonly-used tasks:
47
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
48 $ lein new NAME # generate a new project skeleton
49
4d4aa03 @technomancy Allow test task to take namespaces as an argument.
authored
50 $ lein test [TESTS] # run the tests in the TESTS namespaces, or all tests
73115a5 Added test namespace/task.
Phil Hagelberg authored
51
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
52 $ lein repl # launch an interactive REPL session and socket server
88b5360 @technomancy Initial commit.
authored
53
eea1ebb @technomancy Misc documentation tweaks.
authored
54 $ lein jar # package up the whole project as a .jar file
c558fe9 @technomancy Add clean command.
authored
55
77d8a5c @technomancy Document 1.3.0 features.
authored
56 $ lein install [NAME VERSION] # install a project
57
042ec19 @technomancy Update readme for lein2.
authored
58 $ lein search ... # find jars for your project.clj dependencies
a00e78d @tavisrudd added notes about search command to README
tavisrudd authored
59
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
60 Use `lein help` to see a complete list. `lein help $TASK` shows the
042ec19 @technomancy Update readme for lein2.
authored
61 usage for a specific task.
bda58ab @technomancy Add new task for generating project skeletons.
authored
62
77d8a5c @technomancy Document 1.3.0 features.
authored
63 You can also chain tasks together in a single command by using commas:
64
65 $ lein clean, test foo.test-core, jar
a920ab9 @technomancy Added documentation TODOs.
authored
66
77d8a5c @technomancy Document 1.3.0 features.
authored
67 Most tasks need to be run from somewhere inside a project directory to
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
68 work, but some (`new`, `help`, `version`, and the
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
69 two-argument version of `install`) may run from anywhere.
77d8a5c @technomancy Document 1.3.0 features.
authored
70
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
71 The install task places shell scripts in the `~/.lein/bin`
77d8a5c @technomancy Document 1.3.0 features.
authored
72 directory for projects that include them, so if you want to take
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
73 advantage of this, you should put it on your `$PATH`.
a920ab9 @technomancy Added documentation TODOs.
authored
74
88b5360 @technomancy Initial commit.
authored
75 ## Configuration
76
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
77 The `project.clj` file in the project root should look like this:
21e1dee @technomancy Looks like github in-browser merge messed up that markdown.
authored
78
3ae4b06 @technomancy Document profiles.
authored
79 ```clj
21e1dee @technomancy Looks like github in-browser merge messed up that markdown.
authored
80 (defproject myproject "0.5.0-SNAPSHOT"
81 :description "A project for doing things."
82 :url "http://github.com/technomancy/myproject"
83 :dependencies [[org.clojure/clojure "1.2.1"]
84 [org.clojure/clojure-contrib "1.2.0"]]
042ec19 @technomancy Update readme for lein2.
authored
85 :plugins [[lein-ring "0.4.5"]])
4dcd0cb @mwilliams Add syntax highlighting to Clojure code in the README
mwilliams authored
86 ```
88b5360 @technomancy Initial commit.
authored
87
042ec19 @technomancy Update readme for lein2.
authored
88 To find specific versions of a dependency, use `lein search`.
42cdf1f @technomancy Version is no longer optional in defproject.
authored
89
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
90 The `lein new` task generates a project skeleton with an
3abb1b0 @technomancy Spruce up the readme a bit.
authored
91 appropriate starting point from which you can work. See the
b3fe397 @technomancy Switching all Github URLs to https.
authored
92 [sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/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
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
96 projects. The `~/.lein/init.clj` 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
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
99 `:repl-init` key in project.clj to point to a namespace if
e85e390 @technomancy Doco updates.
authored
100 you want code executed inside your project.
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
101
3ae4b06 @technomancy Document profiles.
authored
102 ### Profiles
042ec19 @technomancy Update readme for lein2.
authored
103
3ae4b06 @technomancy Document profiles.
authored
104 You can change the configuration of your project by applying various
105 profiles. Each profile is defined as a map which gets merged into your
106 project map.
ccfcc54 @tavisrudd added a fuller explanation of plugins to the README
tavisrudd authored
107
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
108 Profiles are read from 3 different locations: (in order of precedence)
3ae4b06 @technomancy Document profiles.
authored
109
110 * the `:profiles` entry in the project map
111 * the `~/.lein/profiles.clj` file
112 * the `leiningen.core.project/default-profiles` atom
113
114 Each of these should be a map of profile names to profile maps.
115
116 Note that profiles have special logic when they are merged into your
117 project map: maps get merged recursively, but sets are `union`ed and
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
118 other collections are `concat`enated. Other values are simply
119 replaced. Profiles take precedence in the order they are specified.
3ae4b06 @technomancy Document profiles.
authored
120
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
121 To activate a profile for a given run, use the `with-profile`
122 higher-order task:
3ae4b06 @technomancy Document profiles.
authored
123
124 $ lein with-profile qa test :database
125
b2cbf4d @technomancy Update plugin guide; remove deprecations from sample.
authored
126 Multiple profiles may be specified with commas:
127
128 $ lein with-profile qa,user test :database
129
3ae4b06 @technomancy Document profiles.
authored
130 A single `with-profile` call does not apply across task comma-chains.
131 Outside `with-profile` calls, the `:dev` and `:user` profiles are
132 active by default.
133
134 ### Leiningen Plugins
135
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
136 Leiningen supports plugins which may contain both new tasks and hooks
137 that modify behaivour of existing tasks. See
3ae4b06 @technomancy Document profiles.
authored
138 [the plugins wiki page](https://github.com/technomancy/leiningen/wiki/Plugins)
139 for a full list. If a plugin is needed for successful test or build
140 runs, (such as `lein-tar`) then it should be added to `:plugins` in
3b6b8b4 @technomancy Clarify :dev-deps vs lein plugin install.
authored
141 project.clj, but if it's for your own convenience (such as
042ec19 @technomancy Update readme for lein2.
authored
142 swank-clojure) then it should be added to the `:plugins` list in the
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
143 `:user` profile from `~/.lein/profiles.clj`. The
144 [plugin guide](https://github.com/technomancy/leiningen/blob/stable/doc/PLUGINS.md)
145 explains how to write plugins.
4be3d03 @ivey Merge Colin Jones' lein-plugin plugin for managing plugins
ivey authored
146
b3e0233 @technomancy Added FAQ, License.
authored
147 ## FAQ
148
0802503 @technomancy Fix markdown in readme.
authored
149 **Q:** How do you pronounce Leiningen?
55f2b80 @technomancy Readme and NEWS updates.
authored
150 **A:** It's LINE-ing-en. ['laɪnɪŋən]
b3e0233 @technomancy Added FAQ, License.
authored
151
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
152 **Q:** What's a group ID? How do snapshots work?
153 **A:** See the
2cb7ec9 @technomancy Update paths of documentation files.
authored
154 [tutorial](https://github.com/technomancy/leiningen/blob/stable/doc/TUTORIAL.md)
eea1ebb @technomancy Misc documentation tweaks.
authored
155 for background.
156
157 **Q:** How should I pick my version numbers?
158 **A:** Use [semantic versioning](http://semver.org).
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
159
045e24d @technomancy Minor readme tweaks.
authored
160 **Q:** What if my project depends on jars that aren't in any repository?
2cb7ec9 @technomancy Update paths of documentation files.
authored
161 **A:** The [deploy guide](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md)
44994c9 @technomancy Re-word docs in favour of the term "project automation".
authored
162 explains how to set up a private repository. If you are not sharing
042ec19 @technomancy Update readme for lein2.
authored
163 them with a team you could also just [install locally](https://github.com/kumarshantanu/lein-localrepo).
f390c60 @technomancy Explain optional project.clj keys in readme. Note publishing deps on …
authored
164
eea1ebb @technomancy Misc documentation tweaks.
authored
165 **Q:** I want to hack two projects in parallel, but it's annoying to switch between them.
042ec19 @technomancy Update readme for lein2.
authored
166 **A:** If you create a directory called `checkouts` in your project
167 root and symlink some other project roots into it, Leiningen will
168 allow you to hack on them in parallel. That means changes in the
169 dependency will be visible in the main project without having to go
170 through the whole install/switch-projects/deps/restart-repl cycle,
171 and the copy in `checkouts` will take precedence over the dependency
172 declared in project.clj. Note that this is not a replacement for
173 listing the project in `:dependencies`; it simply supplements that for
174 convenience.
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
175
c0df45a Extra space at end of question.
Matt Revelle authored
176 **Q:** Is it possible to exclude indirect dependencies?
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
177 **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
178 not included in public repositories and unnecessary for basic
042ec19 @technomancy Update readme for lein2.
authored
179 functionality. Projects listed as `:dependencies` may exclude
180 any of their dependencies by using the `:exclusions` key. See
181 `lein help sample` for details.
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
182
042ec19 @technomancy Update readme for lein2.
authored
183 **Q:** What does `java.lang.NoSuchMethodError: clojure.lang.RestFn.<init>(I)V` mean?
eea1ebb @technomancy Misc documentation tweaks.
authored
184 **A:** It means you have some code that was AOT (ahead-of-time)
185 compiled with a different version of Clojure than the one you're
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
186 currently using. If it persists after running `lein clean` then it
55f2b80 @technomancy Readme and NEWS updates.
authored
187 is a problem with your dependencies. Note that for
eea1ebb @technomancy Misc documentation tweaks.
authored
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
9a4cefc @technomancy Mention HTTP proxying issues in the FAQ.
authored
195 **Q:** I'm behind an HTTP proxy; how can I fetch my dependencies?
042ec19 @technomancy Update readme for lein2.
authored
196 **A:** TODO: document aether proxy setup.
9a4cefc @technomancy Mention HTTP proxying issues in the FAQ.
authored
197
d900c66 @technomancy Documentation updates. Mention JAVA_CMD, contribution guidelines.
authored
198 **Q:** What can be done to speed up launch?
d055f28 @technomancy Release 1.5.1.
authored
199 **A:** The main delay involved in Leiningen comes from starting the
042ec19 @technomancy Update readme for lein2.
authored
200 JVM. Most people use a development cycle that involves keeping a
201 single process running for as long as you're working on that
202 project. Depending on your editor you may be able to do this via its
203 Clojure integration. (See
d055f28 @technomancy Release 1.5.1.
authored
204 [swank-clojure](http://github.com/technomancy/swank-clojure) or
042ec19 @technomancy Update readme for lein2.
authored
205 [VimClojure](https://bitbucket.org/kotarak/vimclojure), for
206 example.) Otherwise you can use the basic `lein repl`.
419a333 @technomancy Mention interactive task speedup in faq.
authored
207
208 **Q:** Still too slow; what else can make startup faster?
a47f467 @technomancy Update README's mention of client JVM vs tiered compilation.
authored
209 **A:** If you are running an older version of Leiningen (before 1.7)
210 you can `export LEIN_JVM_OPTS=-XX:+TieredCompilation` to improve
211 boot time. This requires Hotspot version 20 or newer. On newer versions
212 of Leiningen it is enabled automatically.
cc740d0 @technomancy Mention ant stdin bug.
authored
213
214 **Q:** I don't have access to stdin inside my project.
042ec19 @technomancy Update readme for lein2.
authored
215 **A:** There's a problem in the library that Leiningen uses to spawn
cc740d0 @technomancy Mention ant stdin bug.
authored
216 new processes that blocks access to console input. This means that
a6c35b8 @technomancy Redo windows installation instructions, be consistent with markdown tt.
authored
217 functions like `read-line` will not work as expected in most
218 contexts, though the `repl` task necessarily includes a
219 workaround. You can also use the `trampoline` task to
dfb4b75 @technomancy Doco updates.
authored
220 launch your project's JVM after Leiningen's has exited rather than
042ec19 @technomancy Update readme for lein2.
authored
221 launching it as a subprocess. TODO: document in-process classloader
d900c66 @technomancy Documentation updates. Mention JAVA_CMD, contribution guidelines.
authored
222
223 ## Contributing
224
205c586 @technomancy Move HACKING.md into leiningen-core README.md.
authored
225 Please report issues on the
226 [Github issue tracker](https://github.com/technomancy/leiningen/issues)
227 or the [mailing list](http://groups.google.com/group/leiningen).
228 Personal email addresses are **not** appropriate for bug reports. See
229 the readme for the `leiningen-core` library and `doc/PLUGINS.md` for
230 more details on how Leiningen's codebase is structured.
045e24d @technomancy Minor readme tweaks.
authored
231
6de9784 @technomancy Clarify license of images.
authored
232 Patches are preferred as Github pull requests, though patches from
0a0f8ad @technomancy Expand HACKING.md a bit.
authored
233 `git format-patch` are also welcome on the mailing list. Please use
234 topic branches when sending pull requests rather than committing
6de9784 @technomancy Clarify license of images.
authored
235 directly to master in order to minimize unnecessary merge commit
236 clutter.
237
238 Contributors who have had a single patch accepted may request commit
042ec19 @technomancy Update readme for lein2.
authored
239 rights on the mailing list or in IRC. Please use your judgment
240 regarding potentially-destabilizing work and branches. Other
241 contributors will usually be glad to review topic branches before
242 merging if you ask on IRC or the mailing list.
6de9784 @technomancy Clarify license of images.
authored
243
244 Contributors are also welcome to request a free
245 [Leiningen sticker](http://twitpic.com/2e33r1) by asking on the
246 mailing list and mailing a SASE.
247
ae98527 @technomancy Add Building section to README.
authored
248 ## Building
249
a29b20c @technomancy Clarify bootstrap process.
authored
250 You don't need to "build" Leiningen per se, but when you're using a
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
251 checkout you will need to get its dependencies in place.
ae98527 @technomancy Add Building section to README.
authored
252
1fee69f @technomancy Update bootstrapping instructions, remove old lein.util.* references.
authored
253 Using Leiningen 1.x, run `lein deps` in the `leiningen-core`
254 subproject directory. Once you do that in most cases a `bin/lein
255 self-install` will usually get you what you need. However, this will
256 occasionally fail for very new SNAPSHOT versions since the standalone
257 jar will not have been uploaded yet.
a50cef3 @technomancy bin/lein placement notes.
authored
258
88b5360 @technomancy Initial commit.
authored
259 ## License
260
042ec19 @technomancy Update readme for lein2.
authored
261 Source Copyright © 2009-2012 Phil Hagelberg, Alex Osborne, Dan Larkin, and
6de9784 @technomancy Clarify license of images.
authored
262 [other contributors](https://www.ohloh.net/p/leiningen/contributors).
263 Distributed under the Eclipse Public License, the same as Clojure
264 uses. See the file COPYING.
88b5360 @technomancy Initial commit.
authored
265
79b969b @technomancy Move away from build.clj to project.clj.
authored
266 Thanks to Stuart Halloway for Lancet and Tim Dysinger for convincing
267 me that good builds are important.
268
6de9784 @technomancy Clarify license of images.
authored
269 Images Copyright © 2010 Phil Hagelberg. Distributed under the Creative
270 Commons Attribution + ShareAlike
271 License. [Full-size version](https://github.com/downloads/technomancy/leiningen/leiningen-full.jpg)
272 available.
Something went wrong with that request. Please try again.