Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 92 lines (68 sloc) 3.599 kb
46fa7d3 @technomancy Added plugin writing guide.
authored
1 # Leiningen Plugins
2
dff976c @technomancy Documentation update.
authored
3 Leiningen tasks are simply functions named $TASK in a leiningen.$TASK
4 namespace. So writing a Leiningen plugin is pretty straightforward; as
5 long as it's available on the classpath, Leiningen will be able to use
6 it.
46fa7d3 @technomancy Added plugin writing guide.
authored
7
8 To use a plugin, add it to your project.clj :dev-dependencies and run
dff976c @technomancy Documentation update.
authored
9 "lein deps". Then you'll be able to invoke the tasks it provides with
10 "lein $TASK".
46fa7d3 @technomancy Added plugin writing guide.
authored
11
12 ## Writing a Plugin
13
14 Start by generating a new project with "lein new myplugin", and add a
15 leiningen.myplugin namespace with a myplugin function. That function
16 should take at least one argument: the current project. The project is
17 a map which is based on the project.clj file, but it also has :name,
18 :group, :version, and :root keys added in. If you want it to take
dff976c @technomancy Documentation update.
authored
19 parameters from the command-line invocation, you can make the function
20 take more arguments.
46fa7d3 @technomancy Added plugin writing guide.
authored
21
eea1ebb @technomancy Misc documentation tweaks.
authored
22 Note that Leiningen is an implied dependency of all plugins; you don't
23 need to explicitly list it in the project.clj file.
24
46fa7d3 @technomancy Added plugin writing guide.
authored
25 The docstring from the plugin's namespace will be displayed by the
26 "lein help" task. The function's arglists will also be shown, so pick
27 argument names that are clear and descriptive.
28
dff976c @technomancy Documentation update.
authored
29 If your task returns an integer, it will be used as the exit code for
30 the process.
31
32 You can set up aliases for your task by conjing a pair of strings with
33 alias->task-name mappings on to the leiningen.core/aliases atom:
34
35 (swap! leiningen.core/aliases conj ["-v" "version"])
36
eea1ebb @technomancy Misc documentation tweaks.
authored
37 ## Lancet
38
39 If your plugins need to do a fair amount of filesystem-y things, you
40 may want to take a look at using Ant tasks to do them since the JDK
41 lacks a lot of simple functionality of this kind. Using the Ant API
42 directly is a pain, but it can be eased to a degree using
43 [Lancet](http://github.com/stuarthalloway/lancet). Lancet is the
44 Clojure adapter for Ant that is developed as the sample project in the
45 [Programming
46 Clojure](http://www.pragprog.com/titles/shcloj/programming-clojure)
47 book.
48
49 You can look over the [Ant API documentation's listing of
50 tasks](http://www.jajakarta.org/ant/ant-1.6.1/docs/en/manual/api/org/apache/tools/ant/taskdefs/package-summary.html)
51 to find an appropriate task. See the <tt>deps</tt> task for an example
52 of how to call a task from Clojure.
d2e016c @technomancy Implemented documentation suggestions from readers.
authored
53
46fa7d3 @technomancy Added plugin writing guide.
authored
54 ## Hooks
55
56 You can modify the behaviour of built-in tasks to a degree using
dff976c @technomancy Documentation update.
authored
57 hooks. Hook functionality is provided by the [Robert
58 Hooke](http://github.com/technomancy/robert-hooke) library. This is an
59 implied dependency; as long as Leiningen 1.2 or higher is used it will
60 be available.
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
authored
61
62 Inspired by clojure.test's fixtures functionality, hooks are functions
63 which wrap tasks and may alter their behaviour by using binding,
64 altering the return value, only running the function conditionally,
65 etc. The add-hook function takes a var of the task it's meant to apply
66 to and a function to perform the wrapping:
67
68 (use 'robert.hooke)
69
70 (defn skip-integration-hook [task & args]
46fa7d3 @technomancy Added plugin writing guide.
authored
71 (binding [clojure.test/test-var (test-var-skip :integration)]
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
authored
72 (apply task args)))
46fa7d3 @technomancy Added plugin writing guide.
authored
73
4ff7dab @technomancy Keep hooks on the task function itself, genius.
authored
74 (add-hook #'leiningen.test/test skip-integration-hook)
46fa7d3 @technomancy Added plugin writing guide.
authored
75
76 Hooks compose, so be aware that your hook may be running inside
77 another hook. Hooks are loaded by looking for all namespaces under
78 leiningen.hooks.* on the classpath and loading them in alphabetical
79 order.
80
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
authored
81 See [the documentation for
82 Hooke](http://github.com/technomancy/robert-hooke/blob/master/README.md)
83 for more details.
46fa7d3 @technomancy Added plugin writing guide.
authored
84
85 ## Have Fun
86
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
authored
87 Please add your plugins to [the list on the
88 wiki](http://wiki.github.com/technomancy/leiningen/plugins).
89
46fa7d3 @technomancy Added plugin writing guide.
authored
90 Hopefully the plugin mechanism is simple and flexible enough to let
91 you bend Leiningen to your will.
Something went wrong with that request. Please try again.