Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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