Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 212 lines (160 sloc) 9.204 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
14 exercise in frustration. If you use Ant, you end up copying around a
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
15 lot of the same tasks between XML files on all your projects;
c5ba551 @technomancy Add motivation to README
authored
16 there's a lot of repetition. Maven avoids repetition, but provides
17 very little transparency into what's really going on behind the scenes
18 and forces you to become a Maven expert to script a nontrivial
3abb1b0 @technomancy Spruce up the readme a bit.
authored
19 build. Either way you must write far more XML than is decent.
c5ba551 @technomancy Add motivation to README
authored
20
56c6cb4 @technomancy Add initial hacking guide; still needs lots of work.
authored
21 With Leiningen, you describe your build with Clojure.
c5ba551 @technomancy Add motivation to README
authored
22
410b4e7 @technomancy This is not 1.0-level material... yet.
authored
23 ## Installation
b62c7c0 @technomancy Added temporary install note.
authored
24
3abb1b0 @technomancy Spruce up the readme a bit.
authored
25 Leiningen bootstraps itself using the <tt>lein</tt> shell script;
26 there is no separate 'install script'. It installs its dependencies in
27 $HOME/.m2/repository.
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
28
f0220e6 @technomancy Fix some readme links.
authored
29 1. [Download the script](http://github.com/technomancy/leiningen/raw/stable/bin/lein).
70a6d19 @technomancy Bump version to 1.0.0-SNAPSHOT
authored
30 2. Place it on your path and chmod it to be executable.
31 3. Run: <tt>lein self-install</tt>
b62c7c0 @technomancy Added temporary install note.
authored
32
eea1ebb @technomancy Misc documentation tweaks.
authored
33 For development versions you may use [the master version of the lein
1e89f02 @technomancy Snapshot versions now work with self-install.
authored
34 script](http://github.com/technomancy/leiningen/raw/master/bin/lein) instead.
a2f17c0 @technomancy Update readme for easier dev installation; add some TODOs.
authored
35
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
36 On Windows you can download
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
37 [lein.bat](http://github.com/technomancy/leiningen/raw/master/bin/lein.bat),
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
38 instead, though support on that platform is still experimental.
39
88b5360 @technomancy Initial commit.
authored
40 ## Usage
41
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
42 The
43 [tutorial](http://github.com/technomancy/leiningen/blob/master/TUTORIAL.md)
44 has a detailed walk-through of the steps involved in creating a new
45 project, but here are the commonly-used tasks:
46
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
47 $ lein new NAME # generate a new project skeleton
48
88b5360 @technomancy Initial commit.
authored
49 $ lein deps # install dependencies in lib/
50
4d4aa03 @technomancy Allow test task to take namespaces as an argument.
authored
51 $ lein test [TESTS] # run the tests in the TESTS namespaces, or all tests
73115a5 Added test namespace/task.
Phil Hagelberg authored
52
dff976c @technomancy Documentation update.
authored
53 $ lein repl # launch an interactive REPL session
88b5360 @technomancy Initial commit.
authored
54
eea1ebb @technomancy Misc documentation tweaks.
authored
55 $ lein jar # package up the whole project as a .jar file
c558fe9 @technomancy Add clean command.
authored
56
77d8a5c @technomancy Document 1.3.0 features.
authored
57 $ lein install [NAME VERSION] # install a project
58
eea1ebb @technomancy Misc documentation tweaks.
authored
59 Use <tt>lein help</tt> to see a complete list. <tt>lein help
60 $TASK</tt> shows the usage for a specific one.
bda58ab @technomancy Add new task for generating project skeletons.
authored
61
77d8a5c @technomancy Document 1.3.0 features.
authored
62 You can also chain tasks together in a single command by using commas:
63
64 $ lein clean, test foo.test-core, jar
a920ab9 @technomancy Added documentation TODOs.
authored
65
77d8a5c @technomancy Document 1.3.0 features.
authored
66 Most tasks need to be run from somewhere inside a project directory to
67 work, but some (<tt>new</tt>, <tt>help</tt>, <tt>version</tt> and the
68 two-argument version of <tt>install</tt>) may run from anywhere.
69
70 The install task places shell scripts in the <tt>~/.lein/bin</tt>
71 directory for projects that include them, so if you want to take
72 advantage of this, you should put it on your $PATH.
a920ab9 @technomancy Added documentation TODOs.
authored
73
88b5360 @technomancy Initial commit.
authored
74 ## Configuration
75
3abb1b0 @technomancy Spruce up the readme a bit.
authored
76 Place a project.clj file in the project root like this:
88b5360 @technomancy Initial commit.
authored
77
ddf403d @technomancy Spin off swank into a subproject.
authored
78 (defproject leiningen "0.5.0-SNAPSHOT"
4d4aa03 @technomancy Allow test task to take namespaces as an argument.
authored
79 :description "A build tool designed not to set your hair on fire."
f390c60 @technomancy Explain optional project.clj keys in readme. Note publishing deps on clo...
authored
80 :url "http://github.com/technomancy/leiningen"
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
81 :dependencies [[org.clojure/clojure "1.1.0]
82 [org.clojure/clojure-contrib "1.1.0"]
ddf403d @technomancy Spin off swank into a subproject.
authored
83 [ant/ant-launcher "1.6.2"]
84 [org.apache.maven/maven-ant-tasks "2.0.10"]]
eea1ebb @technomancy Misc documentation tweaks.
authored
85 :dev-dependencies [[swank-clojure "1.2.1"]])
42cdf1f @technomancy Version is no longer optional in defproject.
authored
86
3abb1b0 @technomancy Spruce up the readme a bit.
authored
87 The <tt>lein new</tt> task generates a project skeleton with an
88 appropriate starting point from which you can work. See the
89 [sample.project.clj](http://github.com/technomancy/leiningen/blob/master/sample.project.clj)
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
90 file for a detailed listing of configuration options.
4b65172 @technomancy Prompt to overwrite if pom.xml exists already.
authored
91
77d8a5c @technomancy Document 1.3.0 features.
authored
92 You can also have user-level configuration that applies for all
93 projects. The ~/.lein/init.clj file will be loaded every time
94 Leiningen launches; any arbitrary code may go there. Place jars
95 containing plugins in ~/.lein/plugins to have them available globally
96 for the current user.
97
b3e0233 @technomancy Added FAQ, License.
authored
98 ## FAQ
99
0802503 @technomancy Fix markdown in readme.
authored
100 **Q:** How do you pronounce Leiningen?
101 **A:** It's LINE-ing-en. I think.
b3e0233 @technomancy Added FAQ, License.
authored
102
0802503 @technomancy Fix markdown in readme.
authored
103 **Q:** What does this offer over [Lancet](http://github.com/stuarthalloway/lancet)?
104 **A:** Lancet is more of a library than a build tool. It doesn't predefine
b3e0233 @technomancy Added FAQ, License.
authored
105 any tasks apart from what Ant itself offers, so there is nothing
42cdf1f @technomancy Version is no longer optional in defproject.
authored
106 Clojure-specific in it. Leiningen builds on Lancet, but takes
107 things further. In addition, it includes some Maven functionality
108 for dependencies.
b3e0233 @technomancy Added FAQ, License.
authored
109
0802503 @technomancy Fix markdown in readme.
authored
110 **Q:** But Maven is terrifying!
111 **A:** That's not a question. Anyway, Leiningen only uses the dependency
b3e0233 @technomancy Added FAQ, License.
authored
112 resolution parts of Maven, which are quite tame. For the actual
113 task execution cycles it uses Ant under the covers via Lancet.
114
0802503 @technomancy Fix markdown in readme.
authored
115 **Q:** But Ant is terrifying!
116 **A:** That's [true](http://www.defmacro.org/ramblings/lisp.html). Ant is
b3e0233 @technomancy Added FAQ, License.
authored
117 an interpreter for a [procedural language with a regrettable
118 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
119 But if you treat it as a standard library of build-related
120 functions and are able to write it with a more pleasing syntax, it's
121 not bad.
b3e0233 @technomancy Added FAQ, License.
authored
122
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
123 **Q:** What's a group ID? How do snapshots work?
124 **A:** See the
d36318c @technomancy Replace intro with tutorial.
authored
125 [tutorial](http://github.com/technomancy/leiningen/blob/master/TUTORIAL.md)
eea1ebb @technomancy Misc documentation tweaks.
authored
126 for background.
127
128 **Q:** How should I pick my version numbers?
129 **A:** Use [semantic versioning](http://semver.org).
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
130
045e24d @technomancy Minor readme tweaks.
authored
131 **Q:** What if my project depends on jars that aren't in any repository?
72ff86d @technomancy Minor readme/todo tweaks.
authored
132 **A:** Open-source jars can be uploaded to Clojars (see "Publishing"
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
133 in the tutorial), though be sure to use the group-id of
134 "org.clojars.$USERNAME" in order to avoid conflicts and to allow the
135 original authors to claim it in the future once they get around to
136 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
137 local repository in ~/.m2 with Maven. Add a dependency to
138 project.clj that doesn't exist in any remote repository and run
dff976c @technomancy Documentation update.
authored
139 <tt>lein deps</tt>. It won't succeed, but the output will include
140 the <tt>mvn</tt> invocation to do this. It's _much_ better to get
141 the dependency in a remote repository for repeatability reasons
142 though. For teams working on private projects
143 [Hudson](http://hudson-ci.org/) works well.
f390c60 @technomancy Explain optional project.clj keys in readme. Note publishing deps on clo...
authored
144
eea1ebb @technomancy Misc documentation tweaks.
authored
145 **Q:** How do I write my own tasks?
146 **A:** If it's a task that may be useful to more than just your
147 project, you should make it into a
148 [plugin](http://github.com/technomancy/leiningen/blob/master/PLUGINS.md).
149 You can also include one-off tasks in your src/leiningen/ directory
150 if they're not worth spinning off; the plugin guide shows how.
151
152 **Q:** I want to hack two projects in parallel, but it's annoying to switch between them.
dff976c @technomancy Documentation update.
authored
153 **A:** Use a feature called _checkout dependencies_. If you create
eea1ebb @technomancy Misc documentation tweaks.
authored
154 a directory called <tt>checkouts</tt> in your project root and
155 symlink some other projects into it, Leiningen will allow you to
156 hack on them in parallel. That means changes in the dependency will
157 be visible in the main project without having to go through the
158 whole install/switch-projects/deps/restart-swank cycle.
e535fe8 @technomancy Added INTRO.md with concept background thanks to slyphon.
authored
159
c0df45a Extra space at end of question.
Matt Revelle authored
160 **Q:** Is it possible to exclude indirect dependencies?
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
161 **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
162 not included in public repositories and unnecessary for basic
163 functionality. Projects listed as :dependencies may exclude
915e61a @technomancy Add sample.project.clj showing all honored project keys.
authored
164 any of their dependencies by using the :exclusions key. See
165 sample.project.clj for details.
166
167 **Q:** It says a required artifact is missing for "super-pom". What's that?
168 **A:** The Maven API that Leiningen uses refers to your project as
169 "super-pom". It's just a quirk of the API. It probably means there
170 is a typo in your :dependency declaration in project.clj.
bea0cfa Added documentation about :exclusions in :dependencies to the README and...
Matt Revelle authored
171
eea1ebb @technomancy Misc documentation tweaks.
authored
172 **Q:** What does java.lang.NoSuchMethodError: clojure.lang.RestFn.<init>(I)V mean?
173 **A:** It means you have some code that was AOT (ahead-of-time)
174 compiled with a different version of Clojure than the one you're
175 currently using. If it persists after running <tt>lein clean</tt> then it
176 is a problem with your dependencies. If you depend on contrib, make
177 sure the contrib version matches the Clojure version. Also note for
178 your own project that AOT compilation in Clojure is much less
179 important than it is in other languages. There are a few
180 language-level features that must be AOT-compiled to work, generally
181 for Java interop. If you are not using any of these features, you
182 should not AOT-compile your project if other projects may depend
183 upon it.
045e24d @technomancy Minor readme tweaks.
authored
184
ae98527 @technomancy Add Building section to README.
authored
185 ## Building
186
187 Generally a "lein self-install" will get you what you need.
e9a7f03 @technomancy Documentation updates for 1.3.0.
authored
188 Occasionally this will fail for very new SNAPSHOT versions since the
189 standalone jar will not have been uploaded yet.
ae98527 @technomancy Add Building section to README.
authored
190
191 If you have a copy of an older Leiningen version around (installed as
192 lein-stable, for example), then you can run "lein-stable deps" in your
193 checkout.
194
195 Otherwise you can use Maven:
196
e9a7f03 @technomancy Documentation updates for 1.3.0.
authored
197 $ mvn dependency:copy-dependencies
ae98527 @technomancy Add Building section to README.
authored
198 $ mv target/dependency lib
199
e9a7f03 @technomancy Documentation updates for 1.3.0.
authored
200 See the file HACKING.md for instructions on contributing.
cd4b569 @technomancy Keep dev-dependencies in lib/dev, out of the way of uberjar.
authored
201
88b5360 @technomancy Initial commit.
authored
202 ## License
203
6c36bbb @technomancy Refactor clean task. Fixes #64.
authored
204 Copyright (C) 2009-2010 Phil Hagelberg, Alex Osborne, Dan Larkin, and
205 contributors.
88b5360 @technomancy Initial commit.
authored
206
79b969b @technomancy Move away from build.clj to project.clj.
authored
207 Thanks to Stuart Halloway for Lancet and Tim Dysinger for convincing
208 me that good builds are important.
209
88b5360 @technomancy Initial commit.
authored
210 Distributed under the Eclipse Public License, the same as Clojure
211 uses. See the file COPYING.
Something went wrong with that request. Please try again.