Permalink
Newer
Older
100644 126 lines (89 sloc) 4.13 KB
@mtyaka
Nov 9, 2010
1
# lein-oneoff
2
3
Dealing with dependencies and the classpath can be a
4
pain. [Leiningen](http://github.com/technomancy/leiningen) takes most
5
of the pain away, but creating a new leiningen project for a simple
6
one-off script may sometimes feel like overkill. This is where
7
[lein-oneoff](http://github.com/mtyaka/lein-oneoff) comes in.
8
9
With the help of lein-oneoff you can open a file, declare
@mtyaka
Dec 6, 2010
10
dependencies at the top, and write the rest of the code as
@mtyaka
Nov 9, 2010
11
usually. lein-oneoff will let you run the file, open a repl or start a swank
12
server while taking care of fetching dependencies and constructing the
13
classpath automatically.
14
@mtyaka
Dec 6, 2010
15
You might find lein-oneoff useful when you want to play with a brand
16
new alpha release of clojure, but would rather not dowload the jar
17
manually, when you think you know the answer to a question about a
18
particular library posted to the clojure mailing list, but would
19
rather test your idea out in the repl before posting the answer, or when
20
you quickly want to analyse and plot some data using
21
[Incanter](http://incanter.org/).
22
@mtyaka
Nov 9, 2010
23
## Usage
24
25
lein-oneoff scripts usually consist of a single file. Dependencies
26
should be stated at the top using the `defdeps` form. You may
27
optionally prefix the `defdeps` form with the reader macro #_ (ignore
28
next form). Here's an example:
@mtyaka
Nov 9, 2010
29
@mtyaka
Jan 1, 2012
31
[[org.clojure/clojure "1.2.0"]
32
[compojure "0.5.2"]
33
[ring/ring-jetty-adapter "0.3.3"]])
@mtyaka
Nov 9, 2010
34
35
(ns example
36
(:use [compojure.core :only [defroutes GET]]
@mtyaka
Nov 9, 2010
37
[ring.adapter.jetty :only [run-jetty]]))
38
39
(defroutes routes
40
(GET "/" [] "Hello world!"))
41
42
(def server
43
(run-jetty routes {:port 8080 :join? false}))
44
45
Save this file as `example.clj`, then run it with:
46
47
$ lein oneoff example.clj
48
49
This command will check the specified dependencies and install them
50
into the local maven repository (`~/.m2/repository`) unless already
51
installed, and then run `example.clj` with the necessary dependencies
52
in the classpath. Note that the dependencies are referenced directly
53
from the local maven repository.
54
55
### The defdeps form
56
57
The `defdeps` form must be the first form in the file. It has the following
58
signature:
59
60
(defdeps dependencies additional-entries?)
61
62
where dependencies should be specified as a vector using the same
63
syntax as inside regular leiningen `defproject` form under the
64
`:dependencies` key. The second argument is an optional map of
65
additional standard `defproject` entries. Please note that not all of
66
the available leinigen options make sense for a one-off script and
67
might not work correctly. Adding a `#_` prefix will make it possible
@mtyaka
Jan 1, 2012
68
to ignore the `defdeps` form when re-compiling the file in a repl.
@mtyaka
Nov 9, 2010
69
70
One of the entries that can be useful is the `:repositories` entry. Here's
71
an example:
72
73
(defdeps
74
[[org.clojure/clojure "1.3.0-alpha3"]
75
[org.apache.pivot/pivot-web "1.5.2"]]
76
{:repositories
77
{"apache" "https://repository.apache.org/content/repositories/releases/"}})
78
79
The `defdeps` form may be omitted in which case the only assumed
80
dependency is `org.clojure/clojure` of the same version as your leiningen
81
installation is using.
82
83
### repl
84
85
To start a repl in the context of a one-off script, use the `--repl`
86
command (or its shorter equivalent, `-r`):
87
88
$ lein oneoff --repl example.clj
89
$ lein oneoff -r example.clj
90
91
### swank
92
93
A swank server can be started with the `--swank` (or `-s`)
94
command:
95
96
$ lein oneoff --swank example.clj
97
$ lein oneoff -s example.clj
98
99
Please note that for the swank command to work, you'll need to have
100
`swank-clojure 1.3.0` or newer installed as a user-level leiningen
101
plugin.
@mtyaka
Nov 9, 2010
102
103
### classpath
104
105
lein-oneoff offers an equivalent to leiningen's built-in `classpath`
106
task which prints the project's classpath for one-off scripts:
107
108
$ lein oneoff --classpath example.clj
109
$ lein oneoff -cp example.clj
@mtyaka
Nov 9, 2010
110
111
## Installation
112
@mtyaka
Dec 6, 2010
113
This plugin should be installed as a user-level leiningen
114
plugin. Leiningen 1.4.0 comes with a built-in task for installing
115
user-level plugins:
@mtyaka
Jan 1, 2012
117
$ lein plugin install lein-oneoff 0.2.0
@mtyaka
Nov 9, 2010
118
@mtyaka
Dec 6, 2010
119
lein-oneoff works with leiningen 1.4.0 or newer.
@mtyaka
Nov 9, 2010
120
121
## License
122
123
Copyright (C) 2010 Matjaz Gregoric
124
125
Distributed under the Eclipse Public License, the same as Clojure.