Skip to content
This repository
Newer
Older
100644 440 lines (348 sloc) 17.497 kb
d36318c0 »
2010-06-15 Replace intro with tutorial.
1 # Tutorial
2
3 For those of you new to the JVM who have never touched Ant or Maven in
4 anger: don't panic. Leiningen is designed with you in mind. This
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
5 tutorial will help you get started and explain Leiningen's take on
44994c9d »
2011-07-05 Re-word docs in favour of the term "project automation".
6 project automation and JVM-land dependency management.
d36318c0 »
2010-06-15 Replace intro with tutorial.
7
8 ## Creating a Project
9
10 We'll assume you've got Leiningen installed as per the
b3fe3978 »
2010-12-02 Switching all Github URLs to https.
11 [README](https://github.com/technomancy/leiningen/blob/stable/README.md).
d36318c0 »
2010-06-15 Replace intro with tutorial.
12 Generating a new project is easy:
13
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
14 $ lein new my-stuff
d36318c0 »
2010-06-15 Replace intro with tutorial.
15
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
16 Generating a project called my-stuff based on the 'default' template.
d36318c0 »
2010-06-15 Replace intro with tutorial.
17
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
18 $ cd my-stuff
d36318c0 »
2010-06-15 Replace intro with tutorial.
19 $ tree
20 .
21 |-- project.clj
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
22 |-- README.md
d36318c0 »
2010-06-15 Replace intro with tutorial.
23 |-- src
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
24 | `-- my
25 | `-- stuff.clj
d36318c0 »
2010-06-15 Replace intro with tutorial.
26 `-- test
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
27 `-- my
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
28 `-- test
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
29 `-- stuff.clj
d36318c0 »
2010-06-15 Replace intro with tutorial.
30
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
31 Here we've got your project's README, a `src/` directory containing the
32 code, a `test/` directory, and a `project.clj` file which describes your
33 project to Leiningen. The `src/my/stuff.clj` file corresponds to
34 the `my.stuff` namespace.
d36318c0 »
2010-06-15 Replace intro with tutorial.
35
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
36 Note that we use `my.stuff` instead of just `stuff` since
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
37 single-segment namespaces are discouraged in Clojure. Also if you have
38 namespaces with dashes in the name, the corresponding file will need
39 to use underscores instead since the JVM has trouble loading files
40 with dashes in the name.
d36318c0 »
2010-06-15 Replace intro with tutorial.
41
42 ## Packaging
43
44 You can package your project up now, even though at this stage it's
45 fairly useless:
46
47 $ lein jar
48
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
49 Created ~/src/my-stuff/my-stuff-0.1.0-SNAPSHOT.jar
d36318c0 »
2010-06-15 Replace intro with tutorial.
50
51 Libraries for the JVM are packaged up as .jar files, which are
d2e016c4 »
2010-06-18 Implemented documentation suggestions from readers.
52 basically just .zip files with a little extra JVM-specific metadata.
53 They usually contain .class files (JVM bytecode) and .clj source
54 files, but they can also contain other things like config
33cd2094 »
2011-03-15 Tutorial updates.
55 files. Leiningen downloads jar files of dependencies from remote Maven
56 repositories for you.
d36318c0 »
2010-06-15 Replace intro with tutorial.
57
58 ## project.clj
59
60 $ cat project.clj
61
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
62 ```clj
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
63 (defproject my-stuff "0.1.0-SNAPSHOT"
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
64 :description "FIXME: write description"
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
65 :dependencies [[org.clojure/clojure "1.3.0"]])
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
66 ```
d36318c0 »
2010-06-15 Replace intro with tutorial.
67
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
68 Fill in the `:description` with a short sentence so that your project
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
69 will show up in search results once you publish it. At some point
70 you'll need to flesh out the README too, but for now let's skip ahead
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
71 to setting `:dependencies`. Note that Clojure is just another
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
72 dependency here. Unlike most languages, it's easy to swap out any
73 version of Clojure.
d2e016c4 »
2010-06-18 Implemented documentation suggestions from readers.
74
d36318c0 »
2010-06-15 Replace intro with tutorial.
75 ## Dependencies
76
a761394d »
2011-06-23 Tutorial updates for 1.6.
77 By default, Leiningen projects download dependencies from
78 [Clojars](http://clojars.org) and
79 [Maven Central](http://search.maven.org). Clojars is the Clojure
80 community's centralized jar repository, while Maven Central is for the
81 wider JVM community.
d36318c0 »
2010-06-15 Replace intro with tutorial.
82
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
83 The `lein search` command will search each remote repository:
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
84
a761394d »
2011-06-23 Tutorial updates for 1.6.
85 $ lein search lancet
86 == Results from clojars - Showing page 1 / 1 total
87 [lancet "1.0.0"] Dependency-based builds, Clojure Style.
88 [lancet "1.0.1"] Dependency-based builds, Clojure Style.
d2e016c4 »
2010-06-18 Implemented documentation suggestions from readers.
89
a761394d »
2011-06-23 Tutorial updates for 1.6.
90 This shows two versions available with the dependency vector notation
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
91 for each. You can copy one of these directly into the `:dependencies`
92 section in `project.clj`.
a761394d »
2011-06-23 Tutorial updates for 1.6.
93
94 The "artifact id" here is "lancet", and "1.0.1" is the version you
33cd2094 »
2011-03-15 Tutorial updates.
95 require. Every library also has a "group id", though for Clojure
96 libraries it is often the same as the artifact-id, in which case you
97 may leave it out of the Leiningen dependency notation. For Java
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
98 libraries often a reversed domain name is used as the group id.
eea1ebb8 »
2010-06-21 Misc documentation tweaks.
99
d36318c0 »
2010-06-15 Replace intro with tutorial.
100 Sometimes versions will end in "-SNAPSHOT". This means that it is not
d2e016c4 »
2010-06-18 Implemented documentation suggestions from readers.
101 an official release but a development build. Relying on snapshot
102 dependencies is discouraged but is sometimes necessary if you need bug
cc62c1a8 »
2010-12-07 Don't allow release versions that depend upon snapshots.
103 fixes, etc. that have not made their way into a release yet. However,
104 snapshot versions are not guaranteed to stick around, so it's
105 important that released code never depends upon snapshot versions that
106 you don't control. Adding a snapshot dependency to your project will
107 cause Leiningen to actively go seek out the latest version of the
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
108 dependency (whereas normal release versions are cached in the local
109 repository) so if you have a lot of snapshots it will slow things
110 down.
d36318c0 »
2010-06-15 Replace intro with tutorial.
111
112 Speaking of the local repository, all the dependencies you pull in
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
113 using Leiningen or Maven get cached in `$HOME/.m2/repository` since
114 Leiningen uses the same library as Maven under the covers. You can
115 install the current project in the local repository with this command:
d36318c0 »
2010-06-15 Replace intro with tutorial.
116
117 $ lein install
118
119 Wrote pom.xml
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
120 [INFO] Installing my-stuff-0.1.0-SNAPSHOT.jar to ~/.m2/repository/myproject/myproject/0.1.0-SNAPSHOT/myproject-0.1.0-SNAPSHOT.jar
d36318c0 »
2010-06-15 Replace intro with tutorial.
121
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
122 Note that some libraries make their group-id and artifact-id
123 correspond with the namespace they provide inside the jar, but this is
124 just a convention. There is no guarantee they will match up at all, so
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
125 consult the library's documentation before writing your `:require`
126 clauses.
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
127
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
128 You can add third-party repositories by setting the `:repositories` key
a761394d »
2011-06-23 Tutorial updates for 1.6.
129 in project.clj. See the
b3fe3978 »
2010-12-02 Switching all Github URLs to https.
130 [sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj).
d36318c0 »
2010-06-15 Replace intro with tutorial.
131
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
132 ## Profiles
d36318c0 »
2010-06-15 Replace intro with tutorial.
133
b1046bc8 »
2012-01-13 General cleanup.
134 Sometimes you want to pull in dependencies that are really only
135 necessary while developing; they aren't required for the project to
136 function in production. You can do this by adding a `:dependencies`
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
137 entry to the `:dev` profile. These will be available by default unless
138 you specify another profile from the defaults, but they are not
139 brought along when another project depends on your project.
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
140
a761394d »
2011-06-23 Tutorial updates for 1.6.
141 Using [midje](https://github.com/marick/Midje) for your tests would be
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
142 a typical example; you would not want it included in production, but it's
143 needed to run the tests:
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
144
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
145 ```clj
146 (defproject my-stuff "0.1.0-SNAPSHOT"
147 :description "FIXME: write description"
148 :dependencies [[clojure "1.3.0"]]
149 :profiles {:dev {:dependencies [[midje "1.3.1"]]}})
150 ```
d36318c0 »
2010-06-15 Replace intro with tutorial.
151
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
152 Note that profile-specific dependencies are different from plugins in
153 context; plugins run in Leiningen's process while dependencies run in
154 your project itself.
155
156 If you have dependencies that are not _necessary_ for developing but
a761394d »
2011-06-23 Tutorial updates for 1.6.
157 just for convenience (things like
158 [Swank Clojure](http://github.com/technomancy/swank-clojure) for Emacs
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
159 support or [clj-stacktrace](http://github.com/mmcgrana/clj-stacktrace)
160 you should add them to the `:user` profile in `~/.lein/profiles`
161 instead of the `:dev` profile. Both those profiles are active by
162 default; the difference is the convention for where they are specified.
a761394d »
2011-06-23 Tutorial updates for 1.6.
163
d36318c0 »
2010-06-15 Replace intro with tutorial.
164 ## Writing the Code
165
166 This is the part Leiningen can't really help you with; you're on your
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
167 own here. Well—not quite. Leiningen can help you with running your
d36318c0 »
2010-06-15 Replace intro with tutorial.
168 tests.
169
170 $ lein test
171
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
172 Testing my.test.stuff
173
174 FAIL in (a-test) (stuff.clj:7)
175 FIXME, I fail.
176 expected: (= 0 1)
177 actual: (not (= 0 1))
178
d36318c0 »
2010-06-15 Replace intro with tutorial.
179 Ran 1 tests containing 1 assertions.
180 1 failures, 0 errors.
181
182 Of course, we haven't written any tests yet, so we've just got the
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
183 skeleton failing tests that Leiningen gave us with `lein new`. But
184 once we fill it in the test suite will become more useful. Sometimes
185 if you've got a large test suite you'll want to run just one or two
186 namespaces at a time:
d36318c0 »
2010-06-15 Replace intro with tutorial.
187
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
188 $ lein test my.test.stuff.parser
d36318c0 »
2010-06-15 Replace intro with tutorial.
189
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
190 Testing my.test.stuff.parser
d36318c0 »
2010-06-15 Replace intro with tutorial.
191 Ran 2 tests containing 10 assertions.
192 0 failures, 0 errors.
193
fa2a0a0f »
2010-11-09 Mention features for 1.4 in tutorial/plugin docs.
194 Rather than running your whole suite or just a few namespaces at a
195 time, you can run a subset of your tests using test selectors. To do
196 this, you attach metadata to various deftests.
197
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
198 ```clj
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
199 (deftest ^:integration network-heavy-test
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
200 (is (= [1 2 3] (:numbers (network-operation)))))
201 ```
fa2a0a0f »
2010-11-09 Mention features for 1.4 in tutorial/plugin docs.
202
203 Then add a :test-selectors map to project.clj:
204
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
205 ```clj
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
206 :test-selectors {:default (complement :integration)
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
207 :integration :integration
208 :all (fn [_] true)}
209 ```
fa2a0a0f »
2010-11-09 Mention features for 1.4 in tutorial/plugin docs.
210
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
211 Now if you run `lein test` it will only run deftests that don't have
212 `:integration` metadata, while `lein test :integration` will only run
213 the integration tests and `lein test :all` will run everything. You
86bea509 »
2011-04-09 Mention in tutorial that test selectors need hooke.
214 can include test selectors and listing test namespaces in the same
a761394d »
2011-06-23 Tutorial updates for 1.6.
215 run.
fa2a0a0f »
2010-11-09 Mention features for 1.4 in tutorial/plugin docs.
216
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
217 Running `lein test` from the command-line is not a good solution for
7a3054cb »
2010-11-20 Mention interactive task and getting slimed in tutorial.
218 test-driven development due to the slow startup time of the JVM. For
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
219 quick feedback, either keep a repl open for running the appropriate
220 call to
221 [clojure.test/run-tests](http://clojuredocs.org/clojure_core/1.3.0/clojure.test/run-tests)
222 or look into editor integration such as
223 [clojure-test-mode](https://github.com/technomancy/clojure-mode).
47c0e611 »
2010-08-10 Explain why clojure-test-mode is generally nicer than lein test.
224
7a3054cb »
2010-11-20 Mention interactive task and getting slimed in tutorial.
225 Keep in mind that while keeping a single process around is convenient,
226 it's easy for that process to get into a state that doesn't reflect
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
227 the files on disk—functions that are loaded and then deleted from the
7a3054cb »
2010-11-20 Mention interactive task and getting slimed in tutorial.
228 file will remain in memory, making it easy to miss problems arising
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
229 from missing functions (often referred to as "getting
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
230 slimed"). Because of this it's advised to do a `lein test` run with a
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
231 fresh instance periodically, perhaps before you commit.
7a3054cb »
2010-11-20 Mention interactive task and getting slimed in tutorial.
232
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
233 ## AOT Compiling
d36318c0 »
2010-06-15 Replace intro with tutorial.
234
235 If you're lucky you'll be able to get away without doing any AOT
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
236 (ahead-of-time) compilation. But there are some Java interop features
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
237 that require it, so if you need to use them you should add an `:aot`
238 option into your `project.clj` file. It should be a seq of namespaces
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
239 you want AOT-compiled. Again, the
b3fe3978 »
2010-12-02 Switching all Github URLs to https.
240 [sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj)
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
241 has example usage.
242
e9a7f039 »
2010-08-19 Documentation updates for 1.3.0.
243 Like dependencies, this should happen for you automatically when
244 needed, but if you need to force it you can:
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
245
246 $ lein compile
247
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
248 Compiling my.stuff
d36318c0 »
2010-06-15 Replace intro with tutorial.
249
473250b1 »
2010-06-29 Add note that compilation involves running.
250 For your code to compile, it must be run. This means that you
33cd2094 »
2011-03-15 Tutorial updates.
251 shouldn't have any code with side-effects in the top-level. Anything
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
252 outside a function definition that doesn't start with "def" is
33cd2094 »
2011-03-15 Tutorial updates.
253 suspect. If you have code that should run on startup, place it in a
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
254 `-main` function as explained below under "Uberjar".
473250b1 »
2010-06-29 Add note that compilation involves running.
255
fa2a0a0f »
2010-11-09 Mention features for 1.4 in tutorial/plugin docs.
256 For projects that include some Java code, you can set the
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
257 `:java-source-path` key in project.clj to a directory containing Java
258 files. (You can set it to "src" to keep Java alongside Clojure source
259 or keep them it in a separate directory.) Then the javac compiler will
260 run before your Clojure code is AOT-compiled, or you can run it
261 manually with the `javac` task.
89f2a77a »
2010-11-07 Documentation updates in preparation for 1.4 release.
262
33cd2094 »
2011-03-15 Tutorial updates.
263 There's
264 [a problem in Clojure](http://dev.clojure.org/jira/browse/CLJ-322)
265 where AOT-compiling a namespace will also AOT compile all the
266 namespaces it depends upon. This often causes unrelated compilation
267 artifacts to be included in the jars, but you can set
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
268 `:class-file-whitelist` to a regex which will be matched against
269 .class file names you want to keep in order to remove the unwanted
270 file.
89f2a77a »
2010-11-07 Documentation updates in preparation for 1.4 release.
271
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
272 ## What to do with it
d36318c0 »
2010-06-15 Replace intro with tutorial.
273
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
274 Generally speaking, there are three different goals that are typical
275 of Leiningen projects:
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
276
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
277 * An application you can distribute to end-users
278 * A server-side application
0dfa8672 »
2011-05-13 Clarify deployment guidelines in tutorial and deploy guide.
279 * A library for other Clojure projects to consume
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
280
33cd2094 »
2011-03-15 Tutorial updates.
281 For the first, you typically either build an uberjar or use a
282 shell-wrapper. For libraries, you will want to have them published to
283 a repository like Clojars or a private repository. For server-side
284 applications it varies as described below.
d2e016c4 »
2010-06-18 Implemented documentation suggestions from readers.
285
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
286 ### Uberjar
287
77d8a5c4 »
2010-08-17 Document 1.3.0 features.
288 The simplest thing to do is to distribute an uberjar. This is a single
c52f044e »
2010-09-05 Documentation updates preparing for 1.3.1.
289 standalone executable jar file most suitable for giving to
290 nontechnical users. For this to work you'll need to specify a
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
291 namespace as your `:main` in `project.clj`. By this point our
292 `project.clj` file should look like this:
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
293
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
294 ```clj
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
295 (defproject my-stuff "0.1.0-SNAPSHOT"
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
296 :description "This project is MINE."
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
297 :dependencies [[org.clojure/clojure "1.3.0"]
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
298 [org.apache.lucene/lucene-core "3.0.2"]
299 [lancet "1.0.0"]]
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
300 :test-selectors {:default (complement :integration)
301 :integration :integration
302 :all (fn [_] true)}
303 :main my.stuff)
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
304 ```
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
305
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
306 The namespace you specify will need to contain a `-main` function that
307 will get called when your standalone jar is run. This namespace should
308 have a `(:gen-class)` declaration in the `ns` form at the top. The
309 `-main` function will get passed the command-line arguments. Let's try
310 something simple in `src/my/stuff.clj`:
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
311
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
312 ```clj
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
313 (ns my.stuff
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
314 (:gen-class))
d36318c0 »
2010-06-15 Replace intro with tutorial.
315
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
316 (defn -main [& args]
317 (println "Welcome to my project! These are your args:" args))
318 ```
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
319
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
320 Now we're ready to generate your uberjar:
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
321
322 $ lein uberjar
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
323 Cleaning up
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
324 Compiling my.stuff
325 Compilation succeeded.
326 Created /home/phil/src/leiningen/my-stuff/target/my-stuff-0.1.0-SNAPSHOT.jar
327 Including my-stuff-0.1.0-SNAPSHOT.jar
33cd2094 »
2011-03-15 Tutorial updates.
328 Including lancet-1.0.0.jar
c749a497 »
2010-11-20 Update version numbers in tutorial, for kicks.
329 Including clojure-1.2.0.jar
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
330 Including lucene-core-3.0.2.jar
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
331 Created my-stuff-0.1.0-standalone.jar
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
332
333 This creates a single jar file that contains the contents of all your
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
334 dependencies. Users can run it with a simple `java` invocation,
9b823c2c »
2010-06-16 Minor tutorial tweaks.
335 or on some systems just by double-clicking the jar file.
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
336
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
337 $ java -jar my-stuff-0.1.0-standalone.jar Hello world.
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
338 Welcome to my project! These are your args: (Hello world.)
339
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
340 You can run a regular (non-uber) jar with the `java`
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
341 command-line tool, but that requires constructing the classpath
342 yourself, so it's not a good solution for end-users.
343
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
344 Invoking `lein run` will launch your project's `-main` function as if
fa2a0a0f »
2010-11-09 Mention features for 1.4 in tutorial/plugin docs.
345 from an uberjar, but without going through the packaging process. You
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
346 can also specify an alternate namespace in which to look for `-main`
347 with `lein run -m my.alternate.namespace ARG1 ARG2`.
89f2a77a »
2010-11-07 Documentation updates in preparation for 1.4 release.
348
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
349 For long-running `lein run` processes, you may wish to use the
a761394d »
2011-06-23 Tutorial updates for 1.6.
350 trampoline task, which allows the Leiningen JVM process to exit before
351 launching your project's JVM. This can save memory:
352
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
353 $ lein trampoline run -m my-stuff.server 5000
a761394d »
2011-06-23 Tutorial updates for 1.6.
354
77d8a5c4 »
2010-08-17 Document 1.3.0 features.
355 ### Shell Wrappers
356
357 There are a few downsides to uberjars. It's relatively awkward to
358 invoke them compared to other command-line tools. You also can't
359 control how the JVM is launched. To solve this, you can include a
360 shell script in your jar file that can be used to launch the
361 project. Leiningen places this shell script into the
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
362 `~/.lein/bin` directory at install time. Of course, this is
c52f044e »
2010-09-05 Documentation updates preparing for 1.3.1.
363 only suitable if your users already use Leiningen.
77d8a5c4 »
2010-08-17 Document 1.3.0 features.
364
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
365 If you simply include `:shell-wrapper true` in your
77d8a5c4 »
2010-08-17 Document 1.3.0 features.
366 project.clj, Leiningen automatically generates a simple shell script
367 wrapper when you create your jar file. However, if you need more
368 control you can provide a map instead:
369
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
370 ```clj
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
371 :shell-wrapper {:main my-stuff.core
372 :bin "bin/my-stuff"}
1ba201f4 »
2011-11-11 Explain eval-in-project with dummy project arg in plugin docs.
373 ```
77d8a5c4 »
2010-08-17 Document 1.3.0 features.
374
375 Normally the shell wrapper will invoke the -main function in your
376 project's :main namespace, but specifying this option triggers AOT for
377 uberjars, so if you wish to avoid this or use a different :main for
378 the shell wrapper vs uberjar you can specify a :main ns inside the
379 :shell-wrapper map. You may also specify a :bin key, which should
fff60515 »
2010-08-20 Fix jar to work with custom shell wrappers.
380 point to a file relative to the project's root to use as a shell
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
381 wrapper template instead of the default. The `format` function
77d8a5c4 »
2010-08-17 Document 1.3.0 features.
382 is called with the contents of this file along with the necessary
383 classpath and the main namespace, so put %s in the right place. See
384 [the default
b3fe3978 »
2010-12-02 Switching all Github URLs to https.
385 wrapper](https://github.com/technomancy/leiningen/blob/stable/resources/script-template)
77d8a5c4 »
2010-08-17 Document 1.3.0 features.
386 for an example.
a920ab98 »
2010-08-16 Added documentation TODOs.
387
33cd2094 »
2011-03-15 Tutorial updates.
388 ### Server-side Projects
389
390 There are many ways to get your project deployed as a server-side
391 application. Simple programs can be packaged up as tarballs with
392 accompanied shell scripts using the
393 [lein-tar plugin](https://github.com/technomancy/lein-tar) and then
394 deployed using [pallet](http://hugoduncan.github.com/pallet/),
395 [chef](http://opscode.com/chef/), or other mechanisms. Debian packages
396 can be created with
397 [lein-deb](https://github.com/travis/lein-deb). Web applications may
0dfa8672 »
2011-05-13 Clarify deployment guidelines in tutorial and deploy guide.
398 be deployed using .war (web application archive) files created by the
33cd2094 »
2011-03-15 Tutorial updates.
399 [lein-ring plugin](https://github.com/weavejester/lein-ring). You
400 can even create
401 [Hadoop projects](https://github.com/ndimiduk/lein-hadoop). These
402 kinds of deployments are so varied that they are better-handled using
403 plugins rather than tasks that are built-in to Leiningen itself.
404
0dfa8672 »
2011-05-13 Clarify deployment guidelines in tutorial and deploy guide.
405 It may be tempting to deploy by just checking out your project and
a761394d »
2011-06-23 Tutorial updates for 1.6.
406 using "lein run" on production servers. However, unless you take steps
407 to freeze all the dependencies before deploying, it could be easy to
408 end up with unrepeatable deployments. It's much better to use
409 Leiningen to create a deployable artifact in a continuous integration
410 setting instead. For example, you could have a
0dfa8672 »
2011-05-13 Clarify deployment guidelines in tutorial and deploy guide.
411 [Jenkins](http://jenkins-ci.org) CI server run your project's full
412 test suite, and if it passes, upload a tarball to S3. Then deployment
413 is just a matter of pulling down and extracting the known-good tarball
414 on your production servers.
415
33cd2094 »
2011-03-15 Tutorial updates.
416 ### Publishing Libraries
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
417
418 If your project is a library and you would like others to be able to
419 use it as a dependency in their projects, you will need to get it into
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
420 a public repository. While it's possible to
2cb7ec9a »
2011-07-06 Update paths of documentation files.
421 [maintain your own private repository](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md)
1c85981d »
2011-05-03 New project structure has an extra level of dirs; Thanks Peter Goodall.
422 or get it into Maven central, the easiest way is to publish it at
423 [Clojars](http://clojars.org). Once you have created an account there,
424 publishing is easy:
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
425
c99af385 »
2011-03-09 Move to lancet as a separate project.
426 $ lein jar, pom
0cfd006f »
2012-01-12 Update tutorial for Leiningen 2.
427 $ scp pom.xml my-stuff-0.1.0.jar clojars@clojars.org:
ffe50baf »
2010-06-29 Rearrange and expand uberjar/publishing tutorial sections.
428
429 Once that succeeds it will be available as a package on which other
430 projects may depend. You will need to have permission to publish to
431 the project's group-id under Clojars, though if that group-id doesn't
432 exist yet then Clojars will automatically create it and give you
433 permissions.
434
33cd2094 »
2011-03-15 Tutorial updates.
435 For further details about publishing including setting up private
2cb7ec9a »
2011-07-06 Update paths of documentation files.
436 repositories, see the [deploy guide](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md)
3377dabc »
2010-06-16 Finish compilation, publishing, and uberjar sections of tutorial.
437
438 ## That's It!
439
33cd2094 »
2011-03-15 Tutorial updates.
440 Now go start coding your next project!
Something went wrong with that request. Please try again.