File: README.markdown

package info (click to toggle)
clojure-maven-plugin 1.7.1-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 664 kB
  • sloc: xml: 1,402; java: 1,357; makefile: 2
file content (595 lines) | stat: -rw-r--r-- 17,505 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
Welcome to the clojure-maven-plugin plugin for Apache Maven 2.

This plugin has been designed to make working with clojure as easy as possible, when working in a
mixed language, enterprise project.

## Available goals

 * clojure:add-source
 * clojure:add-test-source
 * clojure:compile
 * clojure:test
 * clojure:test-with-junit
 * clojure:run
 * clojure:repl
 * clojure:nrepl
 * clojure:swank
 * clojure:nailgun
 * clojure:gendoc
 * clojure:autodoc
 * clojure:marginalia

## Getting started with Clojure and Maven

To use this plugin and start working with clojure, start with a blank maven project and declare the plugin and
add a dependency on clojure:

    <packaging>clojure</packaging>
    ....
    <build>
      <plugins>
        <plugin>
          <groupId>com.theoryinpractise</groupId>
          <artifactId>clojure-maven-plugin</artifactId>
          <version>1.3.23</version>
          <extensions>true</extensions>
        </plugin>
      </plugins>
    </build>
    ....
    <dependencies>
      <dependency>
        <groupId>org.clojure</groupId>
        <artifactId>clojure</artifactId>
        <version>1.6.0</version>
      </dependency>
    </dependencies>

By changing your projects <packaging> type to clojure, the plugin will automatically bind itself to the compile,
test-compile, and test maven phases.

Without any additional configuration, the clojure-maven-plugin will compile any namespaces
in ./src/main/clojure/*.clj (or .cljc) and ./src/test/clojure/*.clj (or .cljc).

### Adding additional source directories

To change, or add additional source directories you can add the following configuration:

    <configuration>
      <sourceDirectories>
        <sourceDirectory>src/main/clojure</sourceDirectory>
      </sourceDirectories>
      <testSourceDirectories>
        <testSourceDirectory>src/test/clojure</testSourceDirectory>
      </testSourceDirectories>
    </configuration>

NOTE: The plugin will prepend the project's ${basedir} before each source/testSource directory specified.

### Temporary Compile Paths

If you wish to take advantage of the compilers syntax checking, but wish to prevent any AOT classes from
appearing in the maven generated JAR file, you can tell the plugin to compile to a temporary directory:

    <configuration>
      <temporaryOutputDirectory>true</temporaryOutputDirectory>
    </configuration>

### Namespace configuration

If you wish to limit or filter out namespaces during your compile/test, simply add a `<namespaces>` or `<testNamespaces>`
configuration section:

    <configuration>
      <namespaces>
        <namespace>com.foo</namespace>
        <namespace>net.*</namespace>
        <namespace>!testing.*</namespace>
      </namespaces>
    </configuration>

The namespace declaration is actually a regex match against discovered namespaces, and can also be
prepended with an ! to filter the matching namespace.

If you wish to further limit test/compile usage to only the namespaces you define, you can enable this with the
configuration block:

    <configuration>
      <compileDeclaredNamespaceOnly>true</compileDeclaredNamespaceOnly>
      <testDeclaredNamespaceOnly>true</testDeclaredNamespaceOnly>
    </configuration>

## Interactive Coding

The plugin supports several goals intended to make it easier for developers to run interactive clojure shells
in the context of maven projects.  This means that all dependencies in a project's runtime and test scopes
will be automatically added to the classpath and available for experimentation.

By default these goals will use the test classpath, if you wish to only use the compile classpath/dependencies,
you can disable this with:

    <configuration>
      <runWithTests>false</runWithTests>
    </configuration>

or by running maven with:

    -Dclojure.runwith.test=false

### Goals

<table>
  <tr>
  	<th></th>
    <th>Property</th>
    <th>Variable</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
  <tr>
  	<td colspan="5"><b>clojure:repl</b>&nbsp;&mdash;&nbsp;Starts an interactive clojure REPL right on the command line.</td>
  </tr>
  <tr>
  	<td></td>
    <td>replScript</td>
    <td></td>
    <td></td>
    <td>An initialization script can be specified in the pom using the replScript configuration element.</td>
  </tr>
  <tr>
  	<td></td>
    <td>windowsRepl</td>
    <td></td>
    <td>cmd /c start</td>
    <td>Allows to configure the command line that will be executed in Windows.</td>
  </tr>
  <tr>
  	<td colspan="5"><b>clojure:swank</b>&nbsp;&mdash;&nbsp;Starts a Swank server that accepts connections.</td>
  </tr>
  <tr>
  	<td></td>
    <td>replScript</td>
    <td></td>
    <td></td>
    <td>The clojure script to run before starting the repl</td>
  </tr>
  <tr>
  	<td></td>
    <td>port</td>
    <td>clojure.swank.port</td>
    <td>4005</td>
    <td>The swank server port</td>
  </tr>
  <tr>
  	<td></td>
    <td>protocolVersion</td>
    <td>clojure.swank.protocolVersion</td>
    <td>2009-09-14</td>
    <td>The swank protocol version</td>
  </tr>
  <tr>
  	<td></td>
    <td>encoding</td>
    <td>clojure.swank.encoding</td>
    <td>iso-8859-1</td>
    <td>The swank encoding to use</td>
  </tr>
  <tr>
  	<td></td>
    <td>swankHost</td>
    <td>clojure.swank.host</td>
    <td>localhost</td>
    <td>The host to bind the swank server to/td>
  </tr>
  <tr>
  	<td colspan="5"><b>clojure:nailgun</b>&nbsp;&mdash;&nbsp;Starts a nailgun server.</td>
  </tr>
  <tr>
  	<td></td>
    <td>replScript</td>
    <td></td>
    <td></td>
    <td>The clojure script to run before starting the repl</td>
  </tr>
  <tr>
  	<td></td>
    <td>port</td>
    <td>clojure.nailgun.port</td>
    <td>2113</td>
    <td>The nailgun server port</td>
  </tr>
  <tr>
  	<td colspan="5"><b>clojure:run</b>&nbsp;&mdash;&nbsp;Runs a clojure script.</td>
  </tr>
  <tr>
  	<td></td>
    <td>script</td>
    <td>clojure.script</td>
    <td></td>
    <td>The clojure script to run</td>
  </tr>
  <tr>
  	<td></td>
    <td>scripts</td>
    <td></td>
    <td></td>
    <td>A list of clojure scripts to run</td>
  </tr>
  <tr>
  	<td></td>
    <td>mainClass</td>
    <td>clojure.mainClass</td>
    <td></td>
    <td>A java class to run</td>
  </tr>
  <tr>
  	<td></td>
    <td>args</td>
    <td>clojure.args</td>
    <td></td>
    <td>Arguments to the clojure script(s)</td>
  </tr>
  <tr>
  	<td colspan="5"><b>clojure:add-source</b>&nbsp;&mdash;&nbsp;Includes clojure source directory in -sources.jar.</td>
  </tr>
  <tr>
  	<td colspan="5"><b>clojure:add-testsource</b>&nbsp;&mdash;&nbsp;Includes clojure test source directory in -testsources.jar.</td>
  </tr>
  <tr>
  	<td colspan="5"><b>clojure:nrepl</b>&nbsp;&mdash;&nbsp;Starts a nREPL server that accepts connections.</td>
  </tr>
  <tr>
  	<td></td>
    <td>replScript</td>
    <td></td>
    <td></td>
    <td>The clojure script to run before starting the repl</td>
  </tr>
  <tr>
  	<td></td>
    <td>port</td>
    <td>clojure.nrepl.port</td>
    <td>4005</td>
    <td>The nREPL server port</td>
  </tr>
  <tr>
  	<td></td>
    <td>nreplHost</td>
    <td>clojure.nrepl.host</td>
    <td>localhost</td>
    <td>The host to bind the nREPL server to/td>
  </tr>
</table>

## Testing Clojure Code

Whilst you could easily launch your tests from the clojure:run goal, the plugin provides two goals targeted
specifically to testing: clojure:test and clojure:test-with-junit

Without any additional configuration the plugin will run a temporary clojure "test launcher" script:

The script runs all discovered *test* namespaces, and fails the build when any FAIL or
ERROR cases are found.

If you require different test behavior, you can provide your own test script with the following configuration:

    <configuration>
      <testScript>src/test/clojure/com/jobsheet/test.clj</testScript>
    </configuration>

The first argument to the script is the name of a properties file that has in it a config for the user selected.
These configs can be parsed out using the following code

```
(def props (Properties.))
(.load props (FileInputStream. (first *command-line-args*)))

;;namespaces to run tests for
(def namespaces  (into [] 
                       (for [[key val] props
                             :when (.startsWith key "ns.")]
                               (symbol val))))

;; should there be junit compatible output or not
(def junit (Boolean/valueOf (.get props "junit")))
;; what is the output directory that results should be written to
(def output-dir (.get props "outputDir"))
;; should we xml-escape *out* while the tests are running
(def xml-escape (Boolean/valueOf (.get props "xmlEscape")))
```

We reserve the right to add new configs in the future, and possibly new command line arguments as well.

## Configuring your clojure session

If you want to provide additional arguments to all spawned java/clojure processes, the plugin provides several configuration properties:

<table>
  <tr>
    <th>Property</th>
    <th>Variable</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
  <tr>
	<td>vmargs</td>
	<td>clojure.vmargs</td>
	<td></td>
	<td>JVM Arguments</td>
  </tr>
  <tr>
	<td>clojureOptions</td>
	<td></td>
	<td></td>
	<td>Additional JVM Options such as system property definitions</td>
  </tr>
  <tr>
	<td>warnOnReflection</td>
	<td></td>
	<td>false</td>
	<td>Enable reflection warnings</td>
  </tr>
  <tr>
	<td>prependClasses</td>
	<td></td>
	<td></td>
	<td>A list of classnames to prepend to the command line before the mainClass</td>
  </tr>
</table>

The plugin can also copy source files to the output directory, filtered using the namespace mechanism
that is used to control compilation. If you want to copy all compiled source files to the output:

    <configuration>
      <copyAllCompiledNamespaces>true</copyAllCompiledNamespaces>
    <configuration>

If you want to copy only a subset:

    <configuration>
      <copiedNamespaces>
        <namespace>com.foo</namespace>
        <namespace>!com.foo.private.*</namespace>
      </copiedNamespaces>
      <copyDeclaredNamespaceOnly>true</copyDeclaredNamespaceOnly>
    <configuration>

If you want to do no compilation at all, but copy all source files:

    <configuration>
      <copyDeclaredNamespaceOnly>true</copyDeclaredNamespaceOnly>
      <namespaces>
        <namespace>!.*</namespace>
      </namespaces>
      <compileDeclaredNamespaceOnly>true</compileDeclaredNamespaceOnly>
    <configuration>

Note that it will only copy clojure source files, which must a) end in .clj or .cljc and b) contain a
namespace declaration.

Enjoy.

### Dependencies

In order to run clojure:repl, clojure:swank or clojure:nailgun, your project
needs to have a recent (1.0 or later) version of clojure as a dependency in
pom.xml.

In order to run clojure:autodoc, your project needs to have autodoc as a
dependency in pom.xml.

In order to run clojure:nrepl, your project needs to have org.clojure/tools.nrepl as a
dependency in pom.xml.

#### JLine/IClojure/REPL-y

If JLine is detected in the classpath, it will be used to provide the
clojure:repl goal with history, tab completion, etc. A simple way of
enabling this is to put the following in your pom.xml:

		<dependency>
		   <groupId>jline</groupId>
		   <artifactId>jline</artifactId>
		   <version>0.9.94</version>
		</dependency>

If you prefer [IClojure](https://github.com/cosmin/IClojure) you can add:

		<dependency>
		   <groupId>com.offbytwo.iclojure</groupId>
		   <artifactId>iclojure</artifactId>
		   <version>1.1.0</version>
		</dependency>

Or [REPL-y](https://github.com/trptcolin/reply/):

		<dependency>
		   <groupId>reply</groupId>
		   <artifactId>reply</artifactId>
		   <version>0.1.0-beta9</version>
		</dependency>

#### Swank

The clojure:swank goal requires swank-clojure as a projet dependency.
Unfortunatly, this library is currently not available in the central maven
repository, but is available from clojars by first declaring the repository:

    <repositories>
      <repository>
        <id>clojars</id>
        <url>http://clojars.org/repo/</url>
      </repository>
    </repositories>

and then declaring the dependency itself:

    <dependency>
      <groupId>swank-clojure</groupId>
      <artifactId>swank-clojure</artifactId>
      <version>1.3.0-SNAPSHOT</version>
    </dependency>

By default the swank process will run against the local loopback device, if you wish to change the host your
swank server runs against, you can configure it via:

    <configuration>
      <swankHost>localhost</swankHost>
    </configuration>

or by defining the clojure.swank.host system property.

#### nREPL

The clojure:nrepl goal requires org.clojure/tools.nrepl as a projet dependency as:

    <dependency>
      <groupId>org.clojure</groupId>
      <artifactId>tools.nrepl</artifactId>
      <version>0.2.0-beta9</version>
    </dependency>

By default the nREPL process will run against the local loopback device on port 4005, if you wish to change the host
your nREPL server runs against or the port, you can configure it via:

    <configuration>
      <nreplHost>localhost</nreplHost>
      <nreplPort>9001</nreplPort>
    </configuration>

or by defining the clojure.nrepl.host and clojure.nrepl.port system property.

#### Nailgun for Vimclojure < 2.2.0

The clojure:nailgun goal requires a recent version of vimclojure as a
dependency. Unfortunately, this library is currently not available in
the central maven repository, and has to be downloaded and installed
manually:

 1. Download vimclojure source code from `http://cloud.github.com/downloads/jochu/swank-clojure/swank-clojure-1.0-SNAPSHOT-distribution.zip`.
 2. Follow the README to compile and install vimclojure.
 3. Locate vimclojure.jar and run the following command to install it to your local repository (replace X.X.X with your version of vimclojure):

    	mvn install:install-file -DgroupId=de.kotka -DartifactId=vimclojure -Dversion=X.X.X -Dpackaging=jar -Dfile=/path/to/jarfile

 4. Put the following in your pom.xml (replace X.X.X with your version of vimclojure)

    	<dependency>
		<groupId>de.kotka</groupId>
		<artifactId>vimclojure</artifactId>
		<version>X.X.X</version>
    	</dependency>

 5. You will need to run `mvn clojure:nailgun -Dclojure.nailgun.server=com.martiansoftware.nailgun.NGServer` in order to
    work with the old version (pre 2.2.0) of vimclojure.

#### Nailgun for Vimclojure >= 2.2.0

To use `clojure 1.2.0` comfortably, you will need to upgrade to `Vimclojure
2.2.0` which isn't backwards compatible with previous vimclojure versions.  Now
you will need a dependency on the `vimclojure:server:2.2.0` which contains the
modified Nailgun server.

    <dependency>
        <groupId>vimclojure</groupId>
        <artifactId>server</artifactId>
        <version>2.2.0</version>
    </dependency>

The jar can be found in [clojars](http://clojars.org/) maven repo (you'll have
to add it to the `repositories` section)

    <repository>
        <id>clojars</id>
        <name>Clojars</name>
        <url>http://clojars.org/repo/</url>
    </repository>

The installation process for vimclojure remains the same (except for the
`vimclojure.jar` which you don't need to install anymore).  Just get the
vimclojure package from http://kotka.de/projects/clojure/vimclojure.html and
follow the README.

Notes for migration from the previous version of vimclojure:

* `clj_highlight_builtins` was deprecated in favor of `vimclojure#HighlightBuiltins`
* `clj_highlight_contrib` was removed
* `g:clj_paren_rainbow` was deprecated in favor of `vimclojure#ParenRainbow`
* `g:clj_want_gorilla` was deprecated in favor of `vimclojure#WantNailgun`

#### Windows configuration

As the default Windows console doesn't allow to easily copy and paste code, you can use the `windowsConsole`
configuration option to specify which console command to run in Windows. For example if you are using
http://code.google.com/p/conemu-maximus5/, you can configure the plugin with:

`<windowsConsole>"C:\\Program Files\\ConEmu\\ConEmu64.exe" /cmd</windowsConsole>`

which will give you a sane Windows console

### Configuration

The following options that can be configured as system properties:

<table>
	<tr>
		<th>Property</th>
		<th>Default value</th>
		<th>Description</th>
	</tr>
	<tr>
		<td>clojure.nailgun.port</td>
		<td>4005</td>
		<td>
			Only applicable for the <code>clojure:nailgun</code> goal.
			The port number that the Nailgun server should listen to.
		</td>
	</tr>
	<tr>
		<td>clojure.swank.port</td>
		<td>4005</td>
		<td>
			Only applicable for the <code>clojure:swank</code> goal.
			The port number that the Swank server should listen to.
		</td>
	</tr>
	<tr>
		<td>clojure.swank.protocolVersion</td>
		<td>2009-09-14</td>
		<td>
			Only applicable for the <code>clojure:swank</code> goal.
			Specifies the version of the swank protocol.
		</td>
	</tr>
	<tr>
		<td>clojure.swank.encoding</td>
		<td>iso-8859-1</td>
		<td>
			Only applicable for the <code>clojure:swank</code> goal.
			Specifies the encoding used by the swank protocol.
		</td>
	</tr>
	<tr>
		<td>clojure.nrepl.port</td>
		<td>4005</td>
		<td>
			Only applicable for the <code>clojure:nrepl</code> goal.
			The port number that the nREPL should listen to.
		</td>
	</tr>
	<tr>
		<td>clojure.nrepl.host</td>
		<td>4005</td>
		<td>
			Only applicable for the <code>clojure:nrepl</code> goal.
			The host that the nREPL should listen to.
		</td>
	</tr>
</table>

### Support

Join the discussion mailing list at:

http://groups.google.com/group/clojure-maven-plugin