Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 441 lines (348 sloc) 17.497 kB
d36318c @technomancy Replace intro with tutorial.
authored
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
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
5 tutorial will help you get started and explain Leiningen's take on
44994c9 @technomancy Re-word docs in favour of the term "project automation".
authored
6 project automation and JVM-land dependency management.
d36318c @technomancy Replace intro with tutorial.
authored
7
8 ## Creating a Project
9
10 We'll assume you've got Leiningen installed as per the
b3fe397 @technomancy Switching all Github URLs to https.
authored
11 [README](https://github.com/technomancy/leiningen/blob/stable/README.md).
d36318c @technomancy Replace intro with tutorial.
authored
12 Generating a new project is easy:
13
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
14 $ lein new my-stuff
d36318c @technomancy Replace intro with tutorial.
authored
15
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
16 Generating a project called my-stuff based on the 'default' template.
d36318c @technomancy Replace intro with tutorial.
authored
17
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
18 $ cd my-stuff
d36318c @technomancy Replace intro with tutorial.
authored
19 $ tree
20 .
21 |-- project.clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
22 |-- README.md
d36318c @technomancy Replace intro with tutorial.
authored
23 |-- src
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
24 | `-- my
25 | `-- stuff.clj
d36318c @technomancy Replace intro with tutorial.
authored
26 `-- test
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
27 `-- my
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
28 `-- test
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
29 `-- stuff.clj
d36318c @technomancy Replace intro with tutorial.
authored
30
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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.
d36318c @technomancy Replace intro with tutorial.
authored
35
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
36 Note that we use `my.stuff` instead of just `stuff` since
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
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.
d36318c @technomancy Replace intro with tutorial.
authored
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
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
49 Created ~/src/my-stuff/my-stuff-0.1.0-SNAPSHOT.jar
d36318c @technomancy Replace intro with tutorial.
authored
50
51 Libraries for the JVM are packaged up as .jar files, which are
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
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
33cd209 @technomancy Tutorial updates.
authored
55 files. Leiningen downloads jar files of dependencies from remote Maven
56 repositories for you.
d36318c @technomancy Replace intro with tutorial.
authored
57
58 ## project.clj
59
60 $ cat project.clj
61
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
62 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
63 (defproject my-stuff "0.1.0-SNAPSHOT"
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
64 :description "FIXME: write description"
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
65 :dependencies [[org.clojure/clojure "1.3.0"]])
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
66 ```
d36318c @technomancy Replace intro with tutorial.
authored
67
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
68 Fill in the `:description` with a short sentence so that your project
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
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
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
71 to setting `:dependencies`. Note that Clojure is just another
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
72 dependency here. Unlike most languages, it's easy to swap out any
73 version of Clojure.
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
74
d36318c @technomancy Replace intro with tutorial.
authored
75 ## Dependencies
76
a761394 @technomancy Tutorial updates for 1.6.
authored
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.
d36318c @technomancy Replace intro with tutorial.
authored
82
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
83 The `lein search` command will search each remote repository:
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
84
a761394 @technomancy Tutorial updates for 1.6.
authored
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.
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
89
a761394 @technomancy Tutorial updates for 1.6.
authored
90 This shows two versions available with the dependency vector notation
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
91 for each. You can copy one of these directly into the `:dependencies`
92 section in `project.clj`.
a761394 @technomancy Tutorial updates for 1.6.
authored
93
94 The "artifact id" here is "lancet", and "1.0.1" is the version you
33cd209 @technomancy Tutorial updates.
authored
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
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
98 libraries often a reversed domain name is used as the group id.
eea1ebb @technomancy Misc documentation tweaks.
authored
99
d36318c @technomancy Replace intro with tutorial.
authored
100 Sometimes versions will end in "-SNAPSHOT". This means that it is not
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
101 an official release but a development build. Relying on snapshot
102 dependencies is discouraged but is sometimes necessary if you need bug
cc62c1a @technomancy Don't allow release versions that depend upon snapshots.
authored
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
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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.
d36318c @technomancy Replace intro with tutorial.
authored
111
112 Speaking of the local repository, all the dependencies you pull in
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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:
d36318c @technomancy Replace intro with tutorial.
authored
116
117 $ lein install
118
119 Wrote pom.xml
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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
d36318c @technomancy Replace intro with tutorial.
authored
121
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
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
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
125 consult the library's documentation before writing your `:require`
126 clauses.
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
127
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
128 You can add third-party repositories by setting the `:repositories` key
a761394 @technomancy Tutorial updates for 1.6.
authored
129 in project.clj. See the
b3fe397 @technomancy Switching all Github URLs to https.
authored
130 [sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj).
d36318c @technomancy Replace intro with tutorial.
authored
131
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
132 ## Profiles
d36318c @technomancy Replace intro with tutorial.
authored
133
b1046bc @technomancy General cleanup.
authored
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`
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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.
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
140
a761394 @technomancy Tutorial updates for 1.6.
authored
141 Using [midje](https://github.com/marick/Midje) for your tests would be
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
142 a typical example; you would not want it included in production, but it's
143 needed to run the tests:
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
144
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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 ```
d36318c @technomancy Replace intro with tutorial.
authored
151
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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
a761394 @technomancy Tutorial updates for 1.6.
authored
157 just for convenience (things like
158 [Swank Clojure](http://github.com/technomancy/swank-clojure) for Emacs
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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.
a761394 @technomancy Tutorial updates for 1.6.
authored
163
d36318c @technomancy Replace intro with tutorial.
authored
164 ## Writing the Code
165
166 This is the part Leiningen can't really help you with; you're on your
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
167 own here. Well—not quite. Leiningen can help you with running your
d36318c @technomancy Replace intro with tutorial.
authored
168 tests.
169
170 $ lein test
171
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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
d36318c @technomancy Replace intro with tutorial.
authored
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
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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:
d36318c @technomancy Replace intro with tutorial.
authored
187
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
188 $ lein test my.test.stuff.parser
d36318c @technomancy Replace intro with tutorial.
authored
189
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
190 Testing my.test.stuff.parser
d36318c @technomancy Replace intro with tutorial.
authored
191 Ran 2 tests containing 10 assertions.
192 0 failures, 0 errors.
193
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
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
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
198 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
199 (deftest ^:integration network-heavy-test
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
200 (is (= [1 2 3] (:numbers (network-operation)))))
201 ```
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
202
203 Then add a :test-selectors map to project.clj:
204
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
205 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
206 :test-selectors {:default (complement :integration)
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
207 :integration :integration
208 :all (fn [_] true)}
209 ```
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
210
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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
86bea50 @technomancy Mention in tutorial that test selectors need hooke.
authored
214 can include test selectors and listing test namespaces in the same
a761394 @technomancy Tutorial updates for 1.6.
authored
215 run.
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
216
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
217 Running `lein test` from the command-line is not a good solution for
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
218 test-driven development due to the slow startup time of the JVM. For
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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).
47c0e61 @technomancy Explain why clojure-test-mode is generally nicer than lein test.
authored
224
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
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
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
227 the files on disk—functions that are loaded and then deleted from the
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
228 file will remain in memory, making it easy to miss problems arising
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
229 from missing functions (often referred to as "getting
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
230 slimed"). Because of this it's advised to do a `lein test` run with a
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
231 fresh instance periodically, perhaps before you commit.
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
232
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
233 ## AOT Compiling
d36318c @technomancy Replace intro with tutorial.
authored
234
235 If you're lucky you'll be able to get away without doing any AOT
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
236 (ahead-of-time) compilation. But there are some Java interop features
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
239 you want AOT-compiled. Again, the
b3fe397 @technomancy Switching all Github URLs to https.
authored
240 [sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj)
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
241 has example usage.
242
e9a7f03 @technomancy Documentation updates for 1.3.0.
authored
243 Like dependencies, this should happen for you automatically when
244 needed, but if you need to force it you can:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
245
246 $ lein compile
247
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
248 Compiling my.stuff
d36318c @technomancy Replace intro with tutorial.
authored
249
473250b @technomancy Add note that compilation involves running.
authored
250 For your code to compile, it must be run. This means that you
33cd209 @technomancy Tutorial updates.
authored
251 shouldn't have any code with side-effects in the top-level. Anything
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
252 outside a function definition that doesn't start with "def" is
33cd209 @technomancy Tutorial updates.
authored
253 suspect. If you have code that should run on startup, place it in a
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
254 `-main` function as explained below under "Uberjar".
473250b @technomancy Add note that compilation involves running.
authored
255
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
256 For projects that include some Java code, you can set the
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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.
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
262
33cd209 @technomancy Tutorial updates.
authored
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
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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.
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
271
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
272 ## What to do with it
d36318c @technomancy Replace intro with tutorial.
authored
273
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
274 Generally speaking, there are three different goals that are typical
275 of Leiningen projects:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
276
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
277 * An application you can distribute to end-users
278 * A server-side application
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
279 * A library for other Clojure projects to consume
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
280
33cd209 @technomancy Tutorial updates.
authored
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.
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
285
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
286 ### Uberjar
287
77d8a5c @technomancy Document 1.3.0 features.
authored
288 The simplest thing to do is to distribute an uberjar. This is a single
c52f044 @technomancy Documentation updates preparing for 1.3.1.
authored
289 standalone executable jar file most suitable for giving to
290 nontechnical users. For this to work you'll need to specify a
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
291 namespace as your `:main` in `project.clj`. By this point our
292 `project.clj` file should look like this:
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
293
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
294 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
295 (defproject my-stuff "0.1.0-SNAPSHOT"
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
296 :description "This project is MINE."
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
297 :dependencies [[org.clojure/clojure "1.3.0"]
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
298 [org.apache.lucene/lucene-core "3.0.2"]
299 [lancet "1.0.0"]]
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
300 :test-selectors {:default (complement :integration)
301 :integration :integration
302 :all (fn [_] true)}
303 :main my.stuff)
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
304 ```
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
305
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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`:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
311
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
312 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
313 (ns my.stuff
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
314 (:gen-class))
d36318c @technomancy Replace intro with tutorial.
authored
315
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
316 (defn -main [& args]
317 (println "Welcome to my project! These are your args:" args))
318 ```
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
319
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
320 Now we're ready to generate your uberjar:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
321
322 $ lein uberjar
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
323 Cleaning up
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
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
33cd209 @technomancy Tutorial updates.
authored
328 Including lancet-1.0.0.jar
c749a49 @technomancy Update version numbers in tutorial, for kicks.
authored
329 Including clojure-1.2.0.jar
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
330 Including lucene-core-3.0.2.jar
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
331 Created my-stuff-0.1.0-standalone.jar
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
332
333 This creates a single jar file that contains the contents of all your
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
334 dependencies. Users can run it with a simple `java` invocation,
9b823c2 @technomancy Minor tutorial tweaks.
authored
335 or on some systems just by double-clicking the jar file.
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
336
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
337 $ java -jar my-stuff-0.1.0-standalone.jar Hello world.
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
338 Welcome to my project! These are your args: (Hello world.)
339
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
340 You can run a regular (non-uber) jar with the `java`
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
341 command-line tool, but that requires constructing the classpath
342 yourself, so it's not a good solution for end-users.
343
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
344 Invoking `lein run` will launch your project's `-main` function as if
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
345 from an uberjar, but without going through the packaging process. You
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
346 can also specify an alternate namespace in which to look for `-main`
347 with `lein run -m my.alternate.namespace ARG1 ARG2`.
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
348
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
349 For long-running `lein run` processes, you may wish to use the
a761394 @technomancy Tutorial updates for 1.6.
authored
350 trampoline task, which allows the Leiningen JVM process to exit before
351 launching your project's JVM. This can save memory:
352
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
353 $ lein trampoline run -m my-stuff.server 5000
a761394 @technomancy Tutorial updates for 1.6.
authored
354
77d8a5c @technomancy Document 1.3.0 features.
authored
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
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
362 `~/.lein/bin` directory at install time. Of course, this is
c52f044 @technomancy Documentation updates preparing for 1.3.1.
authored
363 only suitable if your users already use Leiningen.
77d8a5c @technomancy Document 1.3.0 features.
authored
364
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
365 If you simply include `:shell-wrapper true` in your
77d8a5c @technomancy Document 1.3.0 features.
authored
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
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
370 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
371 :shell-wrapper {:main my-stuff.core
372 :bin "bin/my-stuff"}
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
373 ```
77d8a5c @technomancy Document 1.3.0 features.
authored
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
fff6051 @technomancy Fix jar to work with custom shell wrappers.
authored
380 point to a file relative to the project's root to use as a shell
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
381 wrapper template instead of the default. The `format` function
77d8a5c @technomancy Document 1.3.0 features.
authored
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
b3fe397 @technomancy Switching all Github URLs to https.
authored
385 wrapper](https://github.com/technomancy/leiningen/blob/stable/resources/script-template)
77d8a5c @technomancy Document 1.3.0 features.
authored
386 for an example.
a920ab9 @technomancy Added documentation TODOs.
authored
387
33cd209 @technomancy Tutorial updates.
authored
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
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
398 be deployed using .war (web application archive) files created by the
33cd209 @technomancy Tutorial updates.
authored
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
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
405 It may be tempting to deploy by just checking out your project and
a761394 @technomancy Tutorial updates for 1.6.
authored
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
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
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
33cd209 @technomancy Tutorial updates.
authored
416 ### Publishing Libraries
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
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
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
420 a public repository. While it's possible to
2cb7ec9 @technomancy Update paths of documentation files.
authored
421 [maintain your own private repository](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md)
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
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:
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
425
c99af38 @technomancy Move to lancet as a separate project.
authored
426 $ lein jar, pom
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
427 $ scp pom.xml my-stuff-0.1.0.jar clojars@clojars.org:
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
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
33cd209 @technomancy Tutorial updates.
authored
435 For further details about publishing including setting up private
2cb7ec9 @technomancy Update paths of documentation files.
authored
436 repositories, see the [deploy guide](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md)
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
437
438 ## That's It!
439
33cd209 @technomancy Tutorial updates.
authored
440 Now go start coding your next project!
Something went wrong with that request. Please try again.