Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 689 lines (555 sloc) 27.386 kB
7b151b2 @ardumont Add TOC to the tutorial
ardumont authored
1 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
2 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
3 **Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)*
4
5 - [Tutorial](#tutorial)
6 - [What This Tutorial Covers](#what-this-tutorial-covers)
7 - [Getting Help](#getting-help)
8 - [Leiningen Projects](#leiningen-projects)
9 - [Creating a Project](#creating-a-project)
10 - [Directory Layout](#directory-layout)
11 - [Filename-to-Namespace Mapping Convention](#filename-to-namespace-mapping-convention)
12 - [project.clj](#projectclj)
13 - [Dependencies](#dependencies)
14 - [Overview](#overview)
15 - [Artifact IDs, Groups, and Versions](#artifact-ids-groups-and-versions)
16 - [Snapshot Versions](#snapshot-versions)
17 - [Repositories](#repositories)
18 - [Checkout Dependencies](#checkout-dependencies)
19 - [Search](#search)
20 - [Running Code](#running-code)
21 - [Tests](#tests)
22 - [Profiles](#profiles)
23 - [What to do with it](#what-to-do-with-it)
24 - [Uberjar](#uberjar)
25 - [Framework (Uber)jars](#framework-uberjars)
26 - [Server-side Projects](#server-side-projects)
27 - [Publishing Libraries](#publishing-libraries)
28 - [That's It!](#thats-it!)
29
30 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
31
d36318c @technomancy Replace intro with tutorial.
authored
32 # Tutorial
33
5ff555d @technomancy Tweak tutorial.
authored
34 Leiningen is for automating Clojure projects without setting your hair on fire.
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
35
5ff555d @technomancy Tweak tutorial.
authored
36 It offers various project-related tasks and can:
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
37
ad1f925 doc/tut: various minor updates
John Gabriele authored
38 * create new projects
5ff555d @technomancy Tweak tutorial.
authored
39 * fetch dependencies for your project
ad1f925 doc/tut: various minor updates
John Gabriele authored
40 * run tests
5ff555d @technomancy Tweak tutorial.
authored
41 * run a fully-configured REPL
ad1f925 doc/tut: various minor updates
John Gabriele authored
42 * compile Java sources (if any)
5ff555d @technomancy Tweak tutorial.
authored
43 * run the project (if the project isn't a library)
44 * generate a maven-style "pom" file for the project for interop
ad1f925 doc/tut: various minor updates
John Gabriele authored
45 * compile and package projects for deployment
5ff555d @technomancy Tweak tutorial.
authored
46 * publish libraries to repositories such as [Clojars](http://clojars.org)
ad1f925 doc/tut: various minor updates
John Gabriele authored
47 * run custom automation tasks written in Clojure (leiningen plug-ins)
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
48
5ff555d @technomancy Tweak tutorial.
authored
49 If you come from the Java world, Leiningen could be thought of as
50 "Maven meets Ant without the pain". For Ruby and Python folks,
51 Leiningen combines RubyGems/Bundler/Rake and pip/Fabric in a single
52 tool.
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
53
54
55 ## What This Tutorial Covers
56
5ff555d @technomancy Tweak tutorial.
authored
57 This tutorial will briefly cover project structure, dependency
58 management, running tests, the REPL, and topics related to deployment.
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
59
d36318c @technomancy Replace intro with tutorial.
authored
60 For those of you new to the JVM who have never touched Ant or Maven in
61 anger: don't panic. Leiningen is designed with you in mind. This
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
62 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
63 project automation and JVM-land dependency management.
d36318c @technomancy Replace intro with tutorial.
authored
64
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
65
66 ## Getting Help
67
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
68 Also keep in mind that Leiningen ships with fairly comprehensive help;
5ff555d @technomancy Tweak tutorial.
authored
69 `lein help` gives a list of tasks while `lein help $TASK` provides
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
70 details. Further documentation such as the readme, sample
71 configuration, and even this tutorial are also provided.
72
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
73
74 ## Leiningen Projects
75
5ff555d @technomancy Tweak tutorial.
authored
76 Leiningen works with *projects*. A project is a directory containing a
77 group of Clojure (and possibly Java) source files, along with a bit of
78 metadata about them. The metadata is stored in a file named
79 `project.clj` in the project's root directory, which is how you tell
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
80 Leiningen about things like
81
82 * Project name
83 * Project description
84 * What libraries the project depends on
85 * What Clojure version to use
86 * Where to find source files
87 * What's the main namespace of the app
88
89 and more.
90
5ff555d @technomancy Tweak tutorial.
authored
91 Most Leiningen tasks only make sense in the context of a project. Some
928fd88 @sebasoga Minor TUTORIAL fix
sebasoga authored
92 (for example, `repl` or `help`) can also be called from any directory.
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
93
5ff555d @technomancy Tweak tutorial.
authored
94 Next let's take a look at how projects are created.
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
95
d36318c @technomancy Replace intro with tutorial.
authored
96 ## Creating a Project
97
98 We'll assume you've got Leiningen installed as per the
3b53949 @technomancy Remove mention of preview from docs; use stable branch.
authored
99 [README](https://github.com/technomancy/leiningen/blob/stable/README.md).
d36318c @technomancy Replace intro with tutorial.
authored
100 Generating a new project is easy:
101
cd3338f @cldwalker update tutorial to correctly reference app template
cldwalker authored
102 $ lein new app my-stuff
d36318c @technomancy Replace intro with tutorial.
authored
103
cd3338f @cldwalker update tutorial to correctly reference app template
cldwalker authored
104 Generating a project called my-stuff based on the 'app' template.
d36318c @technomancy Replace intro with tutorial.
authored
105
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
106 $ cd my-stuff
f1b7365 @mybuddymichael Use `find .` instead of `tree` in the tutorial
mybuddymichael authored
107 $ find .
d36318c @technomancy Replace intro with tutorial.
authored
108 .
f1b7365 @mybuddymichael Use `find .` instead of `tree` in the tutorial
mybuddymichael authored
109 ./.gitignore
110 ./doc
111 ./doc/intro.md
b35aa83 @mblair mention all files created by the project generator
mblair authored
112 ./LICENSE
f1b7365 @mybuddymichael Use `find .` instead of `tree` in the tutorial
mybuddymichael authored
113 ./project.clj
114 ./README.md
b35aa83 @mblair mention all files created by the project generator
mblair authored
115 ./resources
f1b7365 @mybuddymichael Use `find .` instead of `tree` in the tutorial
mybuddymichael authored
116 ./src
117 ./src/my_stuff
118 ./src/my_stuff/core.clj
119 ./test
120 ./test/my_stuff
121 ./test/my_stuff/core_test.clj
d36318c @technomancy Replace intro with tutorial.
authored
122
5ff555d @technomancy Tweak tutorial.
authored
123 In this example we're using the `app` template, which is intended for
124 an application project rather than a library. Omitting the `app`
125 argument will use the `default` template, which is suitable for
126 libraries.
127
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
128 ### Directory Layout
129
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
130 Here we've got your project's README, a `src/` directory containing the
131 code, a `test/` directory, and a `project.clj` file which describes your
b3e3f04 @technomancy Fix example in tutorial. Fixes #449.
authored
132 project to Leiningen. The `src/my_stuff/core.clj` file corresponds to
133 the `my-stuff.core` namespace.
d36318c @technomancy Replace intro with tutorial.
authored
134
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
135 ### Filename-to-Namespace Mapping Convention
136
fc8aec4 @technomancy Update tutorial.
authored
137 Note that we use `my-stuff.core` instead of just `my-stuff` since
138 single-segment namespaces are discouraged in Clojure. Also note that
139 namespaces with dashes in the name will have the corresponding file
140 named with underscores instead since the JVM has trouble loading files
b3d84b2 @technomancy Link to namespace documentation in tutorial.
authored
141 with dashes in the name. The intricacies of namespaces are a common
142 source of confusion for newcomers, and while they are mostly outside
5ff555d @technomancy Tweak tutorial.
authored
143 the scope of this tutorial you can
b3d84b2 @technomancy Link to namespace documentation in tutorial.
authored
144 [read up on them elsewhere](http://blog.8thlight.com/colin-jones/2010/12/05/clojure-libs-and-namespaces-require-use-import-and-ns.html).
d36318c @technomancy Replace intro with tutorial.
authored
145
146 ## project.clj
147
efc580d @sergv Fix some typos
sergv authored
148 Your `project.clj` file will start off looking something like this:
d36318c @technomancy Replace intro with tutorial.
authored
149
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
150 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
151 (defproject my-stuff "0.1.0-SNAPSHOT"
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
152 :description "FIXME: write description"
fc8aec4 @technomancy Update tutorial.
authored
153 :url "http://example.com/FIXME"
154 :license {:name "Eclipse Public License"
155 :url "http://www.eclipse.org/legal/epl-v10.html"}
9291140 @drewnoakes Updated TUTORIAL.md for Leiningen 2.3.4.
drewnoakes authored
156 :dependencies [[org.clojure/clojure "1.5.1"]]
157 :main ^:skip-aot my-stuff.core
158 :target-path "target/%s"
159 :profiles {:uberjar {:aot :all}})
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
160 ```
d36318c @technomancy Replace intro with tutorial.
authored
161
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
162 If you don't fill in the `:description` with a short sentence, your
163 project will be harder to find in search results, so start there. Be
fafcdb7 remove mention of github as typ values for :url
John Gabriele authored
164 sure to fix the `:url` as well. At some point you'll need to flesh out
5ff555d @technomancy Tweak tutorial.
authored
165 the `README.md` file too, but for now let's skip ahead to setting
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
166 `:dependencies`. Note that Clojure is just another dependency here.
167 Unlike most languages, it's easy to swap out any version of Clojure.
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
168
d36318c @technomancy Replace intro with tutorial.
authored
169 ## Dependencies
170
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
171 ### Overview
172
173 Clojure is a hosted language and Clojure libraries are distributed the same
5ff555d @technomancy Tweak tutorial.
authored
174 way as in other JVM languages: as jar files.
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
175
5ff555d @technomancy Tweak tutorial.
authored
176 Jar files are basically just `.zip` files with a little extra JVM-specific
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
177 metadata. They usually contain `.class` files (JVM bytecode) and `.clj` source
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
178 files, but they can also contain other things like config
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
179 files, JavaScript files or text files with static data.
180
181 Published JVM libraries have *identifiers* (artifact group, artifact id) and
182 *versions*.
183
9ec66a8 clarify maven repository terminology. Also,
John Gabriele authored
184 ### Artifact IDs, Groups, and Versions
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
185
5ff555d @technomancy Tweak tutorial.
authored
186 You can [search Clojars](http://clojars.org/search?q=clj-http) using
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
187 its web interface or via `lein search $TERM`. On the Clojars page for
188 `clj-http` at the time of this writing it shows this:
596446b @offby1 Note that "lein search" can be slow
offby1 authored
189
b9dced1 @hyPiRion Clarify what "last one" means for profile override
hyPiRion authored
190 ```clj
191 [clj-http "0.9.1"]
192 ```
a761394 @technomancy Tutorial updates for 1.6.
authored
193
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
194 It also shows the Maven syntax for dependencies, which we'll skip for
195 now, though you'll need to learn to read it when looking for Java
196 libraries from [Central](http://search.maven.org). You can copy the
197 Leiningen version directly into the `:dependencies` vector in
198 `project.clj`. So for instance, if you change the `:dependencies`
199 line in the example `project.clj` above to
3e1d5fb @alexcoventry Mention `lein deps` in the tutorial.
alexcoventry authored
200
201 ```clj
9291140 @drewnoakes Updated TUTORIAL.md for Leiningen 2.3.4.
drewnoakes authored
202 :dependencies [[org.clojure/clojure "1.5.1"]
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
203 [clj-http "0.9.1"]]
3e1d5fb @alexcoventry Mention `lein deps` in the tutorial.
alexcoventry authored
204 ```
205
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
206 Leiningen will automatically download the `clj-http` jar and make sure
207 it is on your classpath. If you want to explicitly tell lein to
208 download new dependencies, you can do so with `lein deps`, but it will
209 happen on-demand if you don't.
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
210
211 Within the vector, "clj-http" is referred to as the "artifact id".
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
212 "0.9.1" is the version. Some libraries will also have "group ids",
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
213 which are displayed like this:
80bc331 @marick Example of group id
marick authored
214
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
215 ```clj
216 [com.cedarsoft.utils.legacy/hibernate "1.3.4"]
217 ```
80bc331 @marick Example of group id
marick authored
218
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
219 The group id is the part before the slash. Especially for Java
5d5f5c1 @technomancy Clarify group-id in tutorial.
authored
220 libraries, it's often a reversed domain name. Clojure libraries often
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
221 use the same group-id and artifact-id (as with clj-http), in which case
5d5f5c1 @technomancy Clarify group-id in tutorial.
authored
222 you can omit the group-id. If there is a library that's part of a
223 larger group (such as `ring-jetty-adapter` being part of the `ring`
224 project), the group-id is often the same across all the sub-projects.
eea1ebb @technomancy Misc documentation tweaks.
authored
225
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
226 ### Snapshot Versions
227
d36318c @technomancy Replace intro with tutorial.
authored
228 Sometimes versions will end in "-SNAPSHOT". This means that it is not
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
229 an official release but a development build. Relying on snapshot
230 dependencies is discouraged but is sometimes necessary if you need bug
cc62c1a @technomancy Don't allow release versions that depend upon snapshots.
authored
231 fixes, etc. that have not made their way into a release yet. However,
232 snapshot versions are not guaranteed to stick around, so it's
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
233 important that non-development releases never depend upon snapshot versions that
cc62c1a @technomancy Don't allow release versions that depend upon snapshots.
authored
234 you don't control. Adding a snapshot dependency to your project will
235 cause Leiningen to actively go seek out the latest version of the
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
236 dependency daily (whereas normal release versions are cached in the local
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
237 repository) so if you have a lot of snapshots it will slow things
238 down.
d36318c @technomancy Replace intro with tutorial.
authored
239
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
240 Note that some libraries make their group-id and artifact-id
241 correspond with the namespace they provide inside the jar, but this is
242 just a convention. There is no guarantee they will match up at all, so
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
243 consult the library's documentation before writing your `:require`
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
244 and `:import` clauses.
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
245
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
246 ### Repositories
247
5ff555d @technomancy Tweak tutorial.
authored
248 Dependencies are stored in *artifact repositories*. If you are
249 familiar with Perl's CPAN, Python's Cheeseshop (aka PyPi), Ruby's
250 rubygems.org, or Node.js's NPM, it's the same thing. Leiningen reuses
251 existing JVM repository infrastructure. There are several popular
252 open source repositories. Leiningen by default will use two of them:
253 [clojars.org](http://clojars.org) and
254 [Maven Central](http://search.maven.org/).
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
255
5ff555d @technomancy Tweak tutorial.
authored
256 [Clojars](https://clojars.org/) is the Clojure community's centralized
257 maven repository, while [Central](http://search.maven.org/) is for the
258 wider JVM community.
c5de124 @michaelklishin Minor tutorial improvements
michaelklishin authored
259
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
260 You can add third-party repositories by setting the `:repositories` key
a761394 @technomancy Tutorial updates for 1.6.
authored
261 in project.clj. See the
8aed31b @trevor update links to docs rc->stable
trevor authored
262 [sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj).
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
263
12856b5 @michaelklishin Move checkout deps documentation to the tutorial, expand it with exam…
michaelklishin authored
264 ### Checkout Dependencies
265
94c2c15 @technomancy The name of the directory is irrelevant in checkouts.
authored
266 Sometimes it is necessary to develop two projects in parallel but it
267 is very inconvenient to run `lein install` and restart your repl all
268 the time to get your changes picked up. Leiningen provides a solution
269 called *checkout dependencies* (or just *checkouts*). To use it,
270 create a directory called `checkouts` in the project root, like so:
12856b5 @michaelklishin Move checkout deps documentation to the tutorial, expand it with exam…
michaelklishin authored
271
272 .
273 |-- project.clj
274 |-- README.md
275 |-- checkouts
276 |-- src
277 | `-- my_stuff
278 | `-- core.clj
279 `-- test
280 `-- my_stuff
281 `-- core_test.clj
282
94c2c15 @technomancy The name of the directory is irrelevant in checkouts.
authored
283 Then, under the checkouts directory, create symlinks to projects you need.
12856b5 @michaelklishin Move checkout deps documentation to the tutorial, expand it with exam…
michaelklishin authored
284
285 .
286 |-- project.clj
287 |-- README.md
288 |-- checkouts
590a4e1 @michaelklishin A typo
michaelklishin authored
289 | `-- superlib2 [link to ~/code/oss/superlib2]
12856b5 @michaelklishin Move checkout deps documentation to the tutorial, expand it with exam…
michaelklishin authored
290 | `-- superlib3 [link to ~/code/megacorp/superlib3]
291 |-- src
292 | `-- my_stuff
293 | `-- core.clj
294 `-- test
295 `-- my_stuff
296 `-- core_test.clj
297
94c2c15 @technomancy The name of the directory is irrelevant in checkouts.
authored
298 Libraries located under the `checkouts` directory take precedence
299 over libraries pulled from repositories, but this is not a replacement
300 for listing the project in your main project's `:dependencies`; it
6e42cee @technomancy Clarify wording of checkout dependencies in tutorial.
authored
301 simply supplements that for convenience. If you have a project in
302 `checkouts` without putting it in `:dependencies` then its source will
2e852fb @technomancy Doc rewording for checkout deps.
authored
303 be visible but its dependencies will not be found. If you change the
304 dependencies of a checkout project you will still have to run `lein
305 install` and restart your repl; it's just that source changes will be
aa320f5 @alexcoventry `lein install` may not be needed if `lein` can find the library in an…
alexcoventry authored
306 picked up immediately.
307
308 After you've updated `:dependencies`, `lein` will still need to be able
309 to find the library in some repository like clojars or your `~/.m2`
310 directory. If `lein` complains that it could not find the library
311 artifact, you can install it locally by running `lein install` in the
312 checkout dependency project directory.
12856b5 @michaelklishin Move checkout deps documentation to the tutorial, expand it with exam…
michaelklishin authored
313
6e42cee @technomancy Clarify wording of checkout dependencies in tutorial.
authored
314 Checkouts are an opt-in feature; not everyone who is working on the
315 project will have the same set of checkouts, so your project should
316 work without checkouts before you push or merge.
12856b5 @michaelklishin Move checkout deps documentation to the tutorial, expand it with exam…
michaelklishin authored
317
6f24bd1 @zachpendleton add documentation on `lein search` options to tutorial.
zachpendleton authored
318 ### Search
319
320 Leiningen supports searching remote Maven repositories for matching
321 jars with the command `lein search $TERM`. The first time `lein search`
322 is run, a set of indices are downloaded. Once this is finished, the query
323 is evaluated as a Lucene search. This allows for simple string matching
324 or strings prefixed with one of the following operators:
325
326 * `artifact-id`, `artifact\_id`, `id`, `a`
327 * `group-id`, `group\_id`, `group`, `g`
328 * `description`, `desc`, `d`
329
330 These prefixes allow you to execute more advanced queries such as:
331
332 $ lein search clojure
333 $ lein search description:crawl
334 $ lein search group:clojurewerkz
335 $ lein search \"Riak client\"
336
337 `lein search` also accepts a second, optional parameter for fetching
338 successive pages, e.g. `lein search clojure 2`.
339
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
340 ## Running Code
d36318c @technomancy Replace intro with tutorial.
authored
341
ff6bf8a @technomancy Add "Running code" section to tutorial.
authored
342 Enough setup; let's see some code running. Start with a REPL
343 (read-eval-print loop):
344
345 $ lein repl
672d204 @laurentpetit Add nREPL URL to output along side the human readable message
laurentpetit authored
346 nREPL server started on port 55568 on host 127.0.0.1 - nrepl://127.0.0.1:55568
9291140 @drewnoakes Updated TUTORIAL.md for Leiningen 2.3.4.
drewnoakes authored
347 REPL-y 0.3.0
348 Clojure 1.5.1
ff6bf8a @technomancy Add "Running code" section to tutorial.
authored
349 Docs: (doc function-name-here)
350 (find-doc "part-of-name-here")
351 Source: (source function-name-here)
352 Javadoc: (javadoc java-object-or-class-here)
d37195b @technomancy Fix tutorial repl message. Addresses #1317.
authored
353 Exit: Control+D or (exit) or (quit)
9291140 @drewnoakes Updated TUTORIAL.md for Leiningen 2.3.4.
drewnoakes authored
354 Results: Stored in vars *1, *2, *3, an exception in *e
ff6bf8a @technomancy Add "Running code" section to tutorial.
authored
355
356 user=>
357
358 The REPL is an interactive prompt where you can enter arbitrary code
359 to run in the context of your project. Since we've added `clj-http` to
360 `:dependencies`, we are able to load it here along with code from the
361 `my-stuff.core` namespace in your project's own `src/` directory:
362
363 user=> (require 'my-stuff.core)
364 nil
365 user=> (my-stuff.core/-main)
366 Hello, World!
367 nil
368 user=> (require '[clj-http.client :as http])
369 nil
370 user=> (def response (http/get "http://leiningen.org"))
371 #'user/response
372 user=> (keys response)
373 (:trace-redirects :status :headers :body)
374
375 The call to `-main` shows both println output ("Hello, World!") and
376 the return value (nil) together.
377
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
378 Built-in documentation is available via `doc`, and you can examine the
379 source of functions with `source`:
ff6bf8a @technomancy Add "Running code" section to tutorial.
authored
380
381 user=> (source my-stuff.core/-main)
382 (defn -main
383 "I don't do a whole lot."
384 [& args]
385 (println "Hello, World!"))
386
387 user=> ; use control+d to exit
388
389 If you already have code in a `-main` function ready to go and don't
390 need to enter code interactively, the `run` task is simpler:
391
cd3338f @cldwalker update tutorial to correctly reference app template
cldwalker authored
392 $ lein run
ff6bf8a @technomancy Add "Running code" section to tutorial.
authored
393 Hello, World!
394
cd3338f @cldwalker update tutorial to correctly reference app template
cldwalker authored
395 Providing a `-m` argument will tell Leiningen to look for
ff6bf8a @technomancy Add "Running code" section to tutorial.
authored
396 the `-main` function in another namespace. Setting a default `:main` in
397 `project.clj` lets you omit `-m`.
398
399 For long-running `lein run` processes, you may wish to save memory
b84da7b @technomancy Mention :offline? and :local-repo for production deploys in tutorial.
authored
400 with the higher-order trampoline task, which allows the Leiningen JVM
ff6bf8a @technomancy Add "Running code" section to tutorial.
authored
401 process to exit before launching your project's JVM.
402
403 $ lein trampoline run -m my-stuff.server 5000
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
404
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
405 If you have any Java to be compiled in `:java-source-paths` or Clojure
406 namespaces listed in `:aot`, they will always be compiled before
407 Leiningen runs any other code, via any `run`, `repl`,
408 etc. invocations.
409
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
410 ## Tests
411
b84da7b @technomancy Mention :offline? and :local-repo for production deploys in tutorial.
authored
412 We haven't written any tests yet, but we can run the failing tests
413 included from the project template:
d36318c @technomancy Replace intro with tutorial.
authored
414
415 $ lein test
416
9291140 @drewnoakes Updated TUTORIAL.md for Leiningen 2.3.4.
drewnoakes authored
417 lein test my-stuff.core-test
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
418
9291140 @drewnoakes Updated TUTORIAL.md for Leiningen 2.3.4.
drewnoakes authored
419 lein test :only my-stuff.core-test/a-test
420
421 FAIL in (a-test) (core_test.clj:7)
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
422 FIXME, I fail.
423 expected: (= 0 1)
424 actual: (not (= 0 1))
425
d36318c @technomancy Replace intro with tutorial.
authored
426 Ran 1 tests containing 1 assertions.
427 1 failures, 0 errors.
9291140 @drewnoakes Updated TUTORIAL.md for Leiningen 2.3.4.
drewnoakes authored
428 Tests failed.
d36318c @technomancy Replace intro with tutorial.
authored
429
b84da7b @technomancy Mention :offline? and :local-repo for production deploys in tutorial.
authored
430 Once we fill it in the test suite will become more useful. Sometimes
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
431 if you've got a large test suite you'll want to run just one or two
9291140 @drewnoakes Updated TUTORIAL.md for Leiningen 2.3.4.
drewnoakes authored
432 namespaces at a time; `lein test my-stuff.core-test` will do that. You
f697682 @technomancy Tweaks to the tutorial.
authored
433 also might want to break up your tests using test selectors; see `lein
434 help test` for more details.
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
435
fc8aec4 @technomancy Update tutorial.
authored
436 Running `lein test` from the command-line is suitable for regression
437 testing, but the slow startup time of the JVM makes it a poor fit for
438 testing styles that require tighter feedback loops. In these cases,
439 either keep a repl open for running the appropriate call to
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
440 [clojure.test/run-tests](http://clojuredocs.org/clojure_core/1.3.0/clojure.test/run-tests)
441 or look into editor integration such as
442 [clojure-test-mode](https://github.com/technomancy/clojure-mode).
47c0e61 @technomancy Explain why clojure-test-mode is generally nicer than lein test.
authored
443
b84da7b @technomancy Mention :offline? and :local-repo for production deploys in tutorial.
authored
444 Keep in mind that while keeping a running process around is convenient,
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
445 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
446 the files on disk—functions that are loaded and then deleted from the
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
447 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
448 from missing functions (often referred to as "getting
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
449 slimed"). Because of this it's advised to do a `lein test` run with a
fc8aec4 @technomancy Update tutorial.
authored
450 fresh instance periodically in any case, perhaps before you commit.
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
451
4b099af @technomancy Improve coverage of profiles in tutorial and profiles doc.
authored
452 ## Profiles
453
454 Profiles are used to add various things into your project map in
455 different contexts. For instance, during `lein test` runs, the
456 contents of the `:test` profile, if present, will be merged into your
457 project map. You can use this to enable configuration that should only
458 be applied during test runs, either by adding directories containing
459 config files to your classpath via `:resource-paths` or by other
460 means. See `lein help profiles` for more details.
461
462 Unless you tell it otherwise, Leiningen will merge the default set of
463 profiles into the project map. This includes user-wide settings from
464 your `:user` profile, the `:dev` profile from `project.clj` if
465 present, and the built-in `:base` profile which contains dev tools
466 like nREPL and optimizations which help startup time at the expense of
467 runtime performance. Never benchmark with the default profiles. (See
468 the FAQ entry for "tiered compilation")
469
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
470 ## What to do with it
d36318c @technomancy Replace intro with tutorial.
authored
471
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
472 Generally speaking, there are three different goals that are typical
473 of Leiningen projects:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
474
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
475 * An application you can distribute to end-users
476 * A server-side application
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
477 * A library for other Clojure projects to consume
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
478
5ff555d @technomancy Tweak tutorial.
authored
479 For the first, you typically build an uberjar. For libraries, you will
480 want to have them published to a repository like Clojars or a private
481 repository. For server-side applications it varies as described below.
482 Generating a project with `lein new app myapp` will start you out with
483 a few extra defaults suitable for non-library projects, or you can
484 browse the
485 [available templates on Clojars](https://clojars.org/search?q=lein-template)
486 for things like specific web technologies or other project types.
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
487
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
488 ### Uberjar
489
77d8a5c @technomancy Document 1.3.0 features.
authored
490 The simplest thing to do is to distribute an uberjar. This is a single
c52f044 @technomancy Documentation updates preparing for 1.3.1.
authored
491 standalone executable jar file most suitable for giving to
492 nontechnical users. For this to work you'll need to specify a
83a120d @hura Update TUTORIAL.md
hura authored
493 namespace as your `:main` in `project.clj` and ensure it's also AOT (Ahead Of Time)
5ff555d @technomancy Tweak tutorial.
authored
494 compiled by adding it to `:aot`. By this point our `project.clj` file
495 should look like this:
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
496
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
497 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
498 (defproject my-stuff "0.1.0-SNAPSHOT"
fc8aec4 @technomancy Update tutorial.
authored
499 :description "FIXME: write description"
500 :url "http://example.com/FIXME"
501 :license {:name "Eclipse Public License"
502 :url "http://www.eclipse.org/legal/epl-v10.html"}
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
503 :dependencies [[org.clojure/clojure "1.3.0"]
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
504 [org.apache.lucene/lucene-core "3.0.2"]
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
505 [clj-http "0.9.1"]]
5ff555d @technomancy Tweak tutorial.
authored
506 :profiles {:dev {:dependencies [[ring/ring-devel "1.2.0"]]}}
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
507 :test-selectors {:default (complement :integration)
508 :integration :integration
509 :all (fn [_] true)}
5ff555d @technomancy Tweak tutorial.
authored
510 :main my.stuff
511 :aot [my.stuff])
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
512 ```
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
513
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
514 The namespace you specify will need to contain a `-main` function that
515 will get called when your standalone jar is run. This namespace should
516 have a `(:gen-class)` declaration in the `ns` form at the top. The
517 `-main` function will get passed the command-line arguments. Let's try
518 something simple in `src/my/stuff.clj`:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
519
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
520 ```clj
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
521 (ns my.stuff
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
522 (:gen-class))
d36318c @technomancy Replace intro with tutorial.
authored
523
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
524 (defn -main [& args]
525 (println "Welcome to my project! These are your args:" args))
526 ```
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
527
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
528 Now we're ready to generate your uberjar:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
529
530 $ lein uberjar
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
531 Compiling my.stuff
532 Compilation succeeded.
533 Created /home/phil/src/leiningen/my-stuff/target/my-stuff-0.1.0-SNAPSHOT.jar
534 Including my-stuff-0.1.0-SNAPSHOT.jar
fed957c @technomancy Clarify a few points of documentation. Fixes #1475.
authored
535 Including clj-http-0.9.1.jar
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
536 Including clojure-1.3.0.jar
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
537 Including lucene-core-3.0.2.jar
fc8aec4 @technomancy Update tutorial.
authored
538 Created /home/phil/src/leiningen/my-stuff/target/my-stuff-0.1.0-SNAPSHOT-standalone.jar
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
539
540 This creates a single jar file that contains the contents of all your
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
541 dependencies. Users can run it with a simple `java` invocation,
9b823c2 @technomancy Minor tutorial tweaks.
authored
542 or on some systems just by double-clicking the jar file.
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
543
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
544 $ java -jar my-stuff-0.1.0-standalone.jar Hello world.
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
545 Welcome to my project! These are your args: (Hello world.)
546
0cfd006 @technomancy Update tutorial for Leiningen 2.
authored
547 You can run a regular (non-uber) jar with the `java`
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
548 command-line tool, but that requires constructing the classpath
549 yourself, so it's not a good solution for end-users.
550
6c94392 @ato Tiny typo fix in tutorial
ato authored
551 Of course if your users already have Leiningen installed, you can
ff6bf8a @technomancy Add "Running code" section to tutorial.
authored
552 instruct them to use `lein run` as described above.
a761394 @technomancy Tutorial updates for 1.6.
authored
553
be6f571 @llasram Document :provided profile.
llasram authored
554 ### Framework (Uber)jars
555
556 Many Java frameworks expect deployment of a jar file or derived archive
557 sub-format containing a subset of the application's necessary
558 dependencies. The framework expects to provide the missing dependencies
559 itself at run-time. Dependencies which are provided by a framework in
560 this fashion may be specified in the `:provided` profile. Such
561 dependencies will be available during compilation, testing, etc., but
562 won't be included by default by the `uberjar` task or plugin tasks
563 intended to produce stable deployment artifacts.
564
565 For example, Hadoop job jars may be just regular (uber)jar files
566 containing all dependencies except the Hadoop libraries themselves:
567
568 ```clj
569 (project example.hadoop "0.1.0"
570 ...
571 :profiles {:provided
572 {:dependencies
573 [[org.apache.hadoop/hadoop-core "0.20.2-dev"]]}}
574 :main example.hadoop)
575 ```
576
577 $ lein uberjar
578 Compiling example.hadoop
579 Created /home/xmpl/src/example.hadoop/example.hadoop-0.1.0.jar
580 Including example.hadoop-0.1.0.jar
581 Including clojure-1.4.0.jar
582 Created /home/xmpl/src/example.hadoop/example.hadoop-0.1.0-standalone.jar
583 $ hadoop jar example.hadoop-0.1.0-standalone.jar
584 12/08/24 08:28:30 INFO util.Util: resolving application jar from found main method on: example.hadoop
585 12/08/24 08:28:30 INFO flow.MultiMapReducePlanner: using application jar: /home/xmpl/src/example.hadoop/./example.hadoop-0.1.0-standalone.jar
586 ...
587
588 Plugins are required to generate framework deployment jar derivatives
589 (such as WAR files) which include additional metadata, but the
590 `:provided` profile provides a general mechanism for handling the
591 framework dependencies.
592
33cd209 @technomancy Tutorial updates.
authored
593 ### Server-side Projects
594
595 There are many ways to get your project deployed as a server-side
f697682 @technomancy Tweaks to the tutorial.
authored
596 application. Aside from the obvious uberjar approach, simple
cd9a496 @technomancy Apply feedback from Steve Losh on tutorial.
authored
597 programs can be packaged up as tarballs with accompanied shell scripts
598 using the [lein-tar plugin](https://github.com/technomancy/lein-tar)
599 and then deployed using
600 [pallet](http://hugoduncan.github.com/pallet/),
50e14e0 @technomancy Document gpg key generation in deployment guide. Fixes #721.
authored
601 [chef](http://opscode.com/chef/), or other mechanisms.
f697682 @technomancy Tweaks to the tutorial.
authored
602 Web applications may be deployed as uberjars using embedded Jetty with
603 `ring-jetty-adapter` or as .war (web application archive) files
604 created by the
605 [lein-ring plugin](https://github.com/weavejester/lein-ring). For
606 things beyond uberjars, server-side deployments are so varied that they
607 are better-handled using plugins rather than tasks that are built-in
608 to Leiningen itself.
609
ad48331 @technomancy Encourage production use of uberjars over `lein run` in tutorial.
authored
610 It's possible to involve Leiningen during production, but there are
611 many subtle gotchas to that approach; it's strongly recommended to use
612 an uberjar if you can. If you need to launch with the `run` task, you
613 should use `lein trampoline run` in order to save memory, otherwise
614 Leiningen's own JVM will stay up and consume unnecessary memory.
615
616 In addition it's very important to ensure you take steps to freeze all
617 the dependencies before deploying, otherwise it could be easy to end
618 up with
fc8aec4 @technomancy Update tutorial.
authored
619 [unrepeatable deployments](https://github.com/technomancy/leiningen/wiki/Repeatability).
ad48331 @technomancy Encourage production use of uberjars over `lein run` in tutorial.
authored
620 Consider including `~/.m2/repository` in your unit of deployment
621 (tarball, .deb file, etc) along with your project code. It's
622 recommended to use Leiningen to create a deployable artifact in a
623 continuous integration setting. For example, you could have a
624 [Jenkins](http://jenkins-ci.org) CI server run your project's full
625 test suite, and if it passes, upload a tarball to S3. Then deployment
626 is just a matter of pulling down and extracting the known-good tarball
627 on your production servers. Simply launching Leiningen from a checkout
628 on the server will work for the most basic deployments, but as soon as
629 you get a number of servers you run the risk of running with a
630 heterogeneous cluster since you're not guaranteed that each machine
631 will be running with the exact same codebase.
f697682 @technomancy Tweaks to the tutorial.
authored
632
4b099af @technomancy Improve coverage of profiles in tutorial and profiles doc.
authored
633 Also remember that the default profiles are included unless you
634 specify otherwise, which is not suitable for production. Using `lein
635 trampoline with-profile production run -m myapp.main` is
b84da7b @technomancy Mention :offline? and :local-repo for production deploys in tutorial.
authored
636 recommended. By default the production profile is empty, but if your
637 deployment includes the `~/.m2/repository` directory from the CI run
638 that generated the tarball, then you should add its path as
639 `:local-repo` along with `:offline? true` to the `:production`
640 profile. Staying offline prevents the deployed project from diverging
641 at all from the version that was tested in the CI environment.
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
642
ad48331 @technomancy Encourage production use of uberjars over `lein run` in tutorial.
authored
643 Given these pitfalls, it's best to use an uberjar if possible.
644
33cd209 @technomancy Tutorial updates.
authored
645 ### Publishing Libraries
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
646
647 If your project is a library and you would like others to be able to
648 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
649 a public repository. While it's possible to
8aed31b @trevor update links to docs rc->stable
trevor authored
650 [maintain your own private repository](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md)
50e14e0 @technomancy Document gpg key generation in deployment guide. Fixes #721.
authored
651 or get it into [Central](http://search.maven.org), the easiest way is
652 to publish it at [Clojars](http://clojars.org). Once you have
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
653 [created an account](https://clojars.org/register) there, publishing
654 is easy:
655
656 $ lein deploy clojars
657 Created ~/src/my-stuff/target/my-stuff-0.1.0-SNAPSHOT.jar
658 Wrote ~/src/my-stuff/pom.xml
659 No credentials found for clojars
660 See `lein help deploying` for how to configure credentials.
661 Username: me
8aed31b @trevor update links to docs rc->stable
trevor authored
662 Password:
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
663 Retrieving my-stuff/my-stuff/0.1.0-SNAPSHOT/maven-metadata.xml (1k)
664 from https://clojars.org/repo/
665 Sending my-stuff/my-stuff/0.1.0-SNAPSHOT/my-stuff-0.1.0-20120531.032047-14.jar (5k)
666 to https://clojars.org/repo/
667 Sending my-stuff/my-stuff/0.1.0-SNAPSHOT/my-stuff-0.1.0-20120531.032047-14.pom (3k)
668 to https://clojars.org/repo/
669 Retrieving my-stuff/my-stuff/maven-metadata.xml (1k)
670 from https://clojars.org/repo/
671 Sending my-stuff/my-stuff/0.1.0-SNAPSHOT/maven-metadata.xml (1k)
672 to https://clojars.org/repo/
673 Sending my-stuff/my-stuff/maven-metadata.xml (1k)
674 to https://clojars.org/repo/
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
675
676 Once that succeeds it will be available as a package on which other
4050d44 @technomancy Update tutorial and deploy guide for HTTP deploy and credential storage.
authored
677 projects may depend. For instructions on storing your credentials so
50e14e0 @technomancy Document gpg key generation in deployment guide. Fixes #721.
authored
678 they don't have to be re-entered every time, see `lein help
679 deploying`. When deploying a release that's not a snapshot, Leiningen
680 will attempt to sign it using [GPG](http://gnupg.org) to prove your
681 authorship of the release. See the
3b53949 @technomancy Remove mention of preview from docs; use stable branch.
authored
682 [deploy guide](https://github.com/technomancy/leiningen/blob/stable/doc/DEPLOY.md).
50e14e0 @technomancy Document gpg key generation in deployment guide. Fixes #721.
authored
683 for details of how to set that up. The deploy guide includes
684 instructions for deploying to other repositories as well.
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
685
686 ## That's It!
687
33cd209 @technomancy Tutorial updates.
authored
688 Now go start coding your next project!
Something went wrong with that request. Please try again.