Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 450 lines (354 sloc) 18.177 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
14 $ lein new myproject
15
16 Created new project in: myproject
17
18 $ cd myproject
19 $ tree
20 .
21 |-- project.clj
22 |-- README
23 |-- src
24 | `-- myproject
25 | `-- core.clj
26 `-- test
27 `-- myproject
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
28 `-- test
29 `-- core.clj
d36318c @technomancy Replace intro with tutorial.
authored
30
e9a7f03 @technomancy Documentation updates for 1.3.0.
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/myproject/core.clj file corresponds to
34 the myproject.core namespace.
d36318c @technomancy Replace intro with tutorial.
authored
35
e9a7f03 @technomancy Documentation updates for 1.3.0.
authored
36 Note that we use myproject.core instead of just myproject 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
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
49 Created ~/src/myproject/myproject-1.0.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
63 (defproject myproject "1.0.0-SNAPSHOT"
64 :description "FIXME: write description"
65 :dependencies [[org.clojure/clojure "1.2.1"]])
66 ```
d36318c @technomancy Replace intro with tutorial.
authored
67
68 Fill in the :description with a short paragraph 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
71 to setting :dependencies. Note that Clojure is just another
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
a761394 @technomancy Tutorial updates for 1.6.
authored
75 If you've got a simple pure-clojure project, you may be fine with the
cc740d0 @technomancy Mention ant stdin bug.
authored
76 default of depending only on Clojure, but otherwise you'll need to
77 list other dependencies.
d36318c @technomancy Replace intro with tutorial.
authored
78
79 ## Dependencies
80
a761394 @technomancy Tutorial updates for 1.6.
authored
81 By default, Leiningen projects download dependencies from
82 [Clojars](http://clojars.org) and
83 [Maven Central](http://search.maven.org). Clojars is the Clojure
84 community's centralized jar repository, while Maven Central is for the
85 wider JVM community.
d36318c @technomancy Replace intro with tutorial.
authored
86
a761394 @technomancy Tutorial updates for 1.6.
authored
87 The <tt>lein search</tt> command will search each remote repository:
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
88
a761394 @technomancy Tutorial updates for 1.6.
authored
89 $ lein search lancet
90 == Results from clojars - Showing page 1 / 1 total
91 [lancet "1.0.0"] Dependency-based builds, Clojure Style.
92 [lancet "1.0.1"] Dependency-based builds, Clojure Style.
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
93
a761394 @technomancy Tutorial updates for 1.6.
authored
94 This shows two versions available with the dependency vector notation
95 for each. You can copy one of these directly into the :dependencies
96 section in project.clj.
97
98 The "artifact id" here is "lancet", and "1.0.1" is the version you
33cd209 @technomancy Tutorial updates.
authored
99 require. Every library also has a "group id", though for Clojure
100 libraries it is often the same as the artifact-id, in which case you
101 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
102 libraries often a reversed domain name is used as the group id.
eea1ebb @technomancy Misc documentation tweaks.
authored
103
d36318c @technomancy Replace intro with tutorial.
authored
104 Sometimes versions will end in "-SNAPSHOT". This means that it is not
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
105 an official release but a development build. Relying on snapshot
106 dependencies is discouraged but is sometimes necessary if you need bug
cc62c1a @technomancy Don't allow release versions that depend upon snapshots.
authored
107 fixes, etc. that have not made their way into a release yet. However,
108 snapshot versions are not guaranteed to stick around, so it's
109 important that released code never depends upon snapshot versions that
110 you don't control. Adding a snapshot dependency to your project will
111 cause Leiningen to actively go seek out the latest version of the
112 dependency once a day when you run <tt>lein deps</tt>, (whereas normal
113 release versions are cached in the local repository) so if you have a
114 lot of snapshots it will slow things down.
d36318c @technomancy Replace intro with tutorial.
authored
115
116 Speaking of the local repository, all the dependencies you pull in
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
117 using Leiningen or Maven get cached in $HOME/.m2/repository since
118 Leiningen uses the Maven API under the covers. You can install the
119 current project in the local repository with this command:
d36318c @technomancy Replace intro with tutorial.
authored
120
121 $ lein install
122
123 Wrote pom.xml
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
124 [INFO] Installing myproject-1.0.0-SNAPSHOT.jar to ~/.m2/repository/myproject/myproject/1.0.0-SNAPSHOT/myproject-1.0.0-SNAPSHOT.jar
d36318c @technomancy Replace intro with tutorial.
authored
125
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
126 Note that some libraries make their group-id and artifact-id
127 correspond with the namespace they provide inside the jar, but this is
128 just a convention. There is no guarantee they will match up at all, so
129 consult the library's documentation before writing your :require clauses.
130
a761394 @technomancy Tutorial updates for 1.6.
authored
131 If you set :checksum-deps to true in project.clj, Leiningen will
132 automatically detect when your :dependencies key changes and run
133 <tt>lein deps</tt> behind the scenes when necessary.
d36318c @technomancy Replace intro with tutorial.
authored
134
a761394 @technomancy Tutorial updates for 1.6.
authored
135 You can add third-party repositories by setting the :repositories key
136 in project.clj. See the
b3fe397 @technomancy Switching all Github URLs to https.
authored
137 [sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj).
d36318c @technomancy Replace intro with tutorial.
authored
138
139 If you've confirmed that your project will work with a number of
140 different versions of a given dependency, you can provide a range
141 instead of a single version:
142
143 [org.clojure/clojure "[1.1,1.2]"] ; <= will match 1.1.0 through 1.2.0.
144
dee34fa @technomancy Split out find-jars and find-deps-jars.
authored
145 See [Maven's version range specification](http://j.mp/twc713)
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
146 for details. Don't do this unless you have manually confirmed that it
cc62c1a @technomancy Don't allow release versions that depend upon snapshots.
authored
147 works with each of those versions though. You can't assume that your
148 dependencies will use semantic versions; some projects even introduce
149 backwards-incompatible changes in bugfix point releases.
d36318c @technomancy Replace intro with tutorial.
authored
150
151 ## Dev Dependencies
152
153 Sometimes you want to pull in dependencies that are really only for
154 your convenience while developing; they aren't strictly required for
155 the project to function. Leiningen calls these
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
156 :dev-dependencies. They're listed in project.clj alongside regular
d36318c @technomancy Replace intro with tutorial.
authored
157 dependencies and downloaded when you run <tt>lein deps</tt>, but they
158 are not brought along when another project depends on your
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
159 project.
160
a761394 @technomancy Tutorial updates for 1.6.
authored
161 Using [midje](https://github.com/marick/Midje) for your tests would be
162 a typical example; you would not want it included at runtime, but it's
163 needed to run the tests.
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
164
165 Dev dependencies may include plugin code that runs in Leiningen's
166 process (providing additional tasks or augmenting existing ones)
167 or code that runs in the context of your project.
d36318c @technomancy Replace intro with tutorial.
authored
168
a761394 @technomancy Tutorial updates for 1.6.
authored
169 Note that dependencies that are not _necessary_ for developing but
170 just for convenience (things like
171 [Swank Clojure](http://github.com/technomancy/swank-clojure) for Emacs
172 support or
173 [lein-difftest](http://github.com/brentonashworth/lein-difftest)) are
174 better suited for user-level plugins than dev-deps:
175
176 $ lein plugin install swank-clojure 1.3.1
177
d36318c @technomancy Replace intro with tutorial.
authored
178 ## Writing the Code
179
180 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
181 own here. Well—not quite. Leiningen can help you with running your
d36318c @technomancy Replace intro with tutorial.
authored
182 tests.
183
184 $ lein test
185
186 Testing myproject.core-test
187 FAIL in (replace-me) (core_test.clj:6)
188 No tests have been written.
189 expected: false
190 actual: false
191 Ran 1 tests containing 1 assertions.
192 1 failures, 0 errors.
193
194 Of course, we haven't written any tests yet, so we've just got the
195 skeleton failing tests that Leiningen gave us with <tt>lein
196 new</tt>. But once we fill it in the test suite will become more
197 useful. Sometimes if you've got a large test suite you'll want to run
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
198 just one or two namespaces at a time:
d36318c @technomancy Replace intro with tutorial.
authored
199
200 $ lein test myproject.parser-test
201
202 Testing myproject.parser-test
203 Ran 2 tests containing 10 assertions.
204 0 failures, 0 errors.
205
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
206 Rather than running your whole suite or just a few namespaces at a
207 time, you can run a subset of your tests using test selectors. To do
208 this, you attach metadata to various deftests.
209
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
210 ```clj
211 (deftest ^{:integration true} network-heavy-test
212 (is (= [1 2 3] (:numbers (network-operation)))))
213 ```
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
214
215 Then add a :test-selectors map to project.clj:
216
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
217 ```clj
218 :test-selectors {:default (fn [v] (not (:integration v)))
219 :integration :integration
220 :all (fn [_] true)}
221 ```
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
222
223 Now if you run "lein test" it will only run deftests that don't have
224 :integration metadata, while "lein test :integration" will only run
38347be @technomancy Allow test selectors and namespaces to be specified in the same run.
authored
225 the integration tests and "lein test :all" will run everything. You
86bea50 @technomancy Mention in tutorial that test selectors need hooke.
authored
226 can include test selectors and listing test namespaces in the same
a761394 @technomancy Tutorial updates for 1.6.
authored
227 run.
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
228
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
229 Running "lein test" from the command-line is not a good solution for
230 test-driven development due to the slow startup time of the JVM. For
231 quick feedback, try starting an interactive session with "lein int"
232 and running tests from in there. Other options include editor
233 integration (see
b3fe397 @technomancy Switching all Github URLs to https.
authored
234 [clojure-test-mode](https://github.com/technomancy/clojure-mode) for
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
235 Emacs) or keeping a repl open and calling <tt>run-tests</tt> from
236 there as you work.
47c0e61 @technomancy Explain why clojure-test-mode is generally nicer than lein test.
authored
237
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
238 Keep in mind that while keeping a single process around is convenient,
239 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
240 the files on disk—functions that are loaded and then deleted from the
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
241 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
242 from missing functions (often referred to as "getting
243 slimed"). Because of this it's advised to do a "lein test" run with a
244 fresh instance periodically, perhaps before you commit.
7a3054c @technomancy Mention interactive task and getting slimed in tutorial.
authored
245
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
246 ## AOT Compiling
d36318c @technomancy Replace intro with tutorial.
authored
247
248 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
249 (ahead-of-time) compilation. But there are some Java interop features
9b823c2 @technomancy Minor tutorial tweaks.
authored
250 that require it, so if you need to use them you should add an :aot
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
251 option into your project.clj file. It should be a seq of namespaces
252 you want AOT-compiled. Again, the
b3fe397 @technomancy Switching all Github URLs to https.
authored
253 [sample.project.clj](https://github.com/technomancy/leiningen/blob/stable/sample.project.clj)
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
254 has example usage.
255
e9a7f03 @technomancy Documentation updates for 1.3.0.
authored
256 Like dependencies, this should happen for you automatically when
257 needed, but if you need to force it you can:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
258
259 $ lein compile
260
261 Compiling myproject.core
d36318c @technomancy Replace intro with tutorial.
authored
262
473250b @technomancy Add note that compilation involves running.
authored
263 For your code to compile, it must be run. This means that you
33cd209 @technomancy Tutorial updates.
authored
264 shouldn't have any code with side-effects in the top-level. Anything
1c85981 @technomancy New project structure has an extra level of dirs; Thanks Peter Goodall.
authored
265 outside a function definition that doesn't start with <tt>def</tt> is
33cd209 @technomancy Tutorial updates.
authored
266 suspect. If you have code that should run on startup, place it in a
267 <tt>-main</tt> function as explained below under "Uberjar".
473250b @technomancy Add note that compilation involves running.
authored
268
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
269 For projects that include some Java code, you can set the
270 <tt>:java-source-path</tt> key in project.clj to a directory
a761394 @technomancy Tutorial updates for 1.6.
authored
271 containing Java files. (You can set it to "src" to keep Java alongside
272 Clojure source or keep them it in a separate directory.) Then the
273 javac compiler will run before your Clojure code is AOT-compiled, or
274 you can run it manually with the <tt>javac</tt> task.
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
275
33cd209 @technomancy Tutorial updates.
authored
276 There's
277 [a problem in Clojure](http://dev.clojure.org/jira/browse/CLJ-322)
278 where AOT-compiling a namespace will also AOT compile all the
279 namespaces it depends upon. This often causes unrelated compilation
280 artifacts to be included in the jars, but you can set
281 :class-file-whitelist to a regex which will be matched against .class
282 file names you want to keep in order to remove the unwanted file.
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
283
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
284 ## What to do with it
d36318c @technomancy Replace intro with tutorial.
authored
285
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
286 Generally speaking, there are three different goals that are typical
287 of Leiningen projects:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
288
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
289 * An application you can distribute to end-users
290 * A server-side application
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
291 * A library for other Clojure projects to consume
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
292
33cd209 @technomancy Tutorial updates.
authored
293 For the first, you typically either build an uberjar or use a
294 shell-wrapper. For libraries, you will want to have them published to
295 a repository like Clojars or a private repository. For server-side
296 applications it varies as described below.
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
297
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
298 ### Uberjar
299
77d8a5c @technomancy Document 1.3.0 features.
authored
300 The simplest thing to do is to distribute an uberjar. This is a single
c52f044 @technomancy Documentation updates preparing for 1.3.1.
authored
301 standalone executable jar file most suitable for giving to
302 nontechnical users. For this to work you'll need to specify a
303 namespace as your :main in project.clj. By this point our project.clj
304 file should look like this:
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
305
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
306 ```clj
307 (defproject myproject "1.0.0-SNAPSHOT"
308 :description "This project is MINE."
309 :dependencies [[org.clojure/clojure "1.2.0"]
310 [org.apache.lucene/lucene-core "3.0.2"]
311 [lancet "1.0.0"]]
312 :main myproject.core)
313 ```
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
314
315 The namespace you specify will need to contain a <tt>-main</tt>
316 function that will get called when your standalone jar is run. This
317 namespace should have a <tt>(:gen-class)</tt> declaration in the
318 <tt>ns</tt> form at the top. The <tt>-main</tt> function will get
319 passed the command-line arguments. Let's try something simple in
320 src/myproject/core.clj:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
321
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
322 ```clj
323 (ns myproject.core
324 (:gen-class))
d36318c @technomancy Replace intro with tutorial.
authored
325
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
326 (defn -main [& args]
327 (println "Welcome to my project! These are your args:" args))
328 ```
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
329
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
330 Now we're ready to generate your uberjar:
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
331
332 $ lein uberjar
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
333 Cleaning up
cc740d0 @technomancy Mention ant stdin bug.
authored
334 Copying 3 files to /home/phil/src/leiningen/myproject/lib
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
335 Created ~/src/myproject/myproject-1.0.0.jar
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
336 Including myproject-1.0.0-SNAPSHOT.jar
33cd209 @technomancy Tutorial updates.
authored
337 Including lancet-1.0.0.jar
c749a49 @technomancy Update version numbers in tutorial, for kicks.
authored
338 Including clojure-1.2.0.jar
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
339 Including lucene-core-3.0.2.jar
9b823c2 @technomancy Minor tutorial tweaks.
authored
340 Created myproject-1.0.0-standalone.jar
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
341
342 This creates a single jar file that contains the contents of all your
9b823c2 @technomancy Minor tutorial tweaks.
authored
343 dependencies. Users can run it with a simple <tt>java</tt> invocation,
344 or on some systems just by double-clicking the jar file.
3377dab @technomancy Finish compilation, publishing, and uberjar sections of tutorial.
authored
345
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
346 $ java -jar myproject-1.0.0-standalone.jar Hello world.
347 Welcome to my project! These are your args: (Hello world.)
348
349 You can run a regular (non-uber) jar with the <tt>java</tt>
350 command-line tool, but that requires constructing the classpath
351 yourself, so it's not a good solution for end-users.
352
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
authored
353 Invoking "lein run" will launch your project's -main function as if
354 from an uberjar, but without going through the packaging process. You
355 can also specify an alternate namespace in which to look for -main
356 with "lein run -m my.alternate.namespace ARG1 ARG2".
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
authored
357
a761394 @technomancy Tutorial updates for 1.6.
authored
358 For long-running "lein run" processes, you may wish to use the
359 trampoline task, which allows the Leiningen JVM process to exit before
360 launching your project's JVM. This can save memory:
361
362 $ lein trampoline run -m myproject.server 5000
363
77d8a5c @technomancy Document 1.3.0 features.
authored
364 ### Shell Wrappers
365
366 There are a few downsides to uberjars. It's relatively awkward to
367 invoke them compared to other command-line tools. You also can't
368 control how the JVM is launched. To solve this, you can include a
369 shell script in your jar file that can be used to launch the
370 project. Leiningen places this shell script into the
c52f044 @technomancy Documentation updates preparing for 1.3.1.
authored
371 <tt>~/.lein/bin</tt> directory at install time. Of course, this is
372 only suitable if your users already use Leiningen.
77d8a5c @technomancy Document 1.3.0 features.
authored
373
374 If you simply include <tt>:shell-wrapper true</tt> in your
375 project.clj, Leiningen automatically generates a simple shell script
376 wrapper when you create your jar file. However, if you need more
377 control you can provide a map instead:
378
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
379 ```clj
77d8a5c @technomancy Document 1.3.0 features.
authored
380 :shell-wrapper {:main myproject.core
381 :bin "bin/myproject"}
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
authored
382 ```
77d8a5c @technomancy Document 1.3.0 features.
authored
383
384 Normally the shell wrapper will invoke the -main function in your
385 project's :main namespace, but specifying this option triggers AOT for
386 uberjars, so if you wish to avoid this or use a different :main for
387 the shell wrapper vs uberjar you can specify a :main ns inside the
388 :shell-wrapper map. You may also specify a :bin key, which should
fff6051 @technomancy Fix jar to work with custom shell wrappers.
authored
389 point to a file relative to the project's root to use as a shell
77d8a5c @technomancy Document 1.3.0 features.
authored
390 wrapper template instead of the default. The <tt>format</tt> function
391 is called with the contents of this file along with the necessary
392 classpath and the main namespace, so put %s in the right place. See
393 [the default
b3fe397 @technomancy Switching all Github URLs to https.
authored
394 wrapper](https://github.com/technomancy/leiningen/blob/stable/resources/script-template)
77d8a5c @technomancy Document 1.3.0 features.
authored
395 for an example.
a920ab9 @technomancy Added documentation TODOs.
authored
396
33cd209 @technomancy Tutorial updates.
authored
397 ### Server-side Projects
398
399 There are many ways to get your project deployed as a server-side
400 application. Simple programs can be packaged up as tarballs with
401 accompanied shell scripts using the
402 [lein-tar plugin](https://github.com/technomancy/lein-tar) and then
403 deployed using [pallet](http://hugoduncan.github.com/pallet/),
404 [chef](http://opscode.com/chef/), or other mechanisms. Debian packages
405 can be created with
406 [lein-deb](https://github.com/travis/lein-deb). Web applications may
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
407 be deployed using .war (web application archive) files created by the
33cd209 @technomancy Tutorial updates.
authored
408 [lein-ring plugin](https://github.com/weavejester/lein-ring). You
409 can even create
410 [Hadoop projects](https://github.com/ndimiduk/lein-hadoop). These
411 kinds of deployments are so varied that they are better-handled using
412 plugins rather than tasks that are built-in to Leiningen itself.
413
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
414 It may be tempting to deploy by just checking out your project and
a761394 @technomancy Tutorial updates for 1.6.
authored
415 using "lein run" on production servers. However, unless you take steps
416 to freeze all the dependencies before deploying, it could be easy to
417 end up with unrepeatable deployments. It's much better to use
418 Leiningen to create a deployable artifact in a continuous integration
419 setting instead. For example, you could have a
0dfa867 @technomancy Clarify deployment guidelines in tutorial and deploy guide.
authored
420 [Jenkins](http://jenkins-ci.org) CI server run your project's full
421 test suite, and if it passes, upload a tarball to S3. Then deployment
422 is just a matter of pulling down and extracting the known-good tarball
423 on your production servers.
424
33cd209 @technomancy Tutorial updates.
authored
425 ### Publishing Libraries
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
426
427 If your project is a library and you would like others to be able to
428 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
429 a public repository. While it's possible to
2cb7ec9 @technomancy Update paths of documentation files.
authored
430 [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
431 or get it into Maven central, the easiest way is to publish it at
432 [Clojars](http://clojars.org). Once you have created an account there,
433 publishing is easy:
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
434
c99af38 @technomancy Move to lancet as a separate project.
authored
435 $ lein jar, pom
ffe50ba @technomancy Rearrange and expand uberjar/publishing tutorial sections.
authored
436 $ scp pom.xml myproject-1.0.0.jar clojars@clojars.org:
437
438 Once that succeeds it will be available as a package on which other
439 projects may depend. You will need to have permission to publish to
440 the project's group-id under Clojars, though if that group-id doesn't
441 exist yet then Clojars will automatically create it and give you
442 permissions.
443
33cd209 @technomancy Tutorial updates.
authored
444 For further details about publishing including setting up private
2cb7ec9 @technomancy Update paths of documentation files.
authored
445 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
446
447 ## That's It!
448
33cd209 @technomancy Tutorial updates.
authored
449 Now go start coding your next project!
Something went wrong with that request. Please try again.