Skip to content
Newer
Older
100644 147 lines (114 sloc) 5.63 KB
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
1 # Leiningen Plugins
2
dff976c @technomancy Documentation update.
technomancy authored Jul 18, 2010
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
579fef7 @technomancy Add example of a trivial plugin to PLUGINS.md.
technomancy authored Dec 21, 2011
6 it:
7
8 ```clj
9 (ns leiningen.debug
10 (:require [clojure.pprint :as pprint]))
11
12 (defn debug
13 "Emit a pretty-printed representation of the project map."
14 [project]
15 (pprint/pprint project))
16 ```
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
17
fa2a0a0 @technomancy Mention features for 1.4 in tutorial/plugin docs.
technomancy authored Nov 9, 2010
18 Plugins may be installed on a per-project or user-wide basis. To use a
19 plugin in a single project, add it to your project.clj
20 :dev-dependencies and run "lein deps". To install it for your user,
21 run "lein plugin install ARTIFACT-ID VERSION".
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
technomancy authored Nov 7, 2010
22
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
23 ## Writing a Plugin
24
25 Start by generating a new project with "lein new myplugin", and add a
89f2a77 @technomancy Documentation updates in preparation for 1.4 release.
technomancy authored Nov 7, 2010
26 leiningen.myplugin namespace with a myplugin function. Add
27 :eval-in-leiningen true to your project.clj so Leiningen knows to
28 execute its code inside the Leiningen process rather than spinning up
29 a subprocess.
e9a7f03 @technomancy Documentation updates for 1.3.0.
technomancy authored Aug 19, 2010
30
31 Some tasks may only be run in the context of a project. For tasks like
32 this, name the first argument <tt>project</tt>. Leiningen will inspect
33 the argument list and pass in the current project if needed. The
34 project is a map which is based on the project.clj file, but it also
35 has :name, :group, :version, and :root keys added in. If you want it
36 to take parameters from the command-line invocation, you can make the
37 function take more arguments.
38
39 Tasks without a <tt>project</tt> argument will be able to be run from
40 anywhere.
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
41
f9138b1 @technomancy Use the first line of task defn docstrings as help summary.
technomancy authored Apr 12, 2011
42 The "lein help" task will display the first line of the task
43 function's docstring as a summary. Then "lein help $TASK" will use
44 the task function's full docstring for detailed help. The function's
45 arglists will also be shown, so pick argument names that are clear and
0d6aa48 @technomancy Update help task to use short summaries.
technomancy authored Nov 23, 2010
46 descriptive. If you set :help-arglists in the function's metadata, it
f9138b1 @technomancy Use the first line of task defn docstrings as help summary.
technomancy authored Apr 12, 2011
47 will be used instead for those cases where alternate arities exist
48 that aren't intended to be exposed to the user.
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
49
dff976c @technomancy Documentation update.
technomancy authored Jul 18, 2010
50 If your task returns an integer, it will be used as the exit code for
51 the process.
52
eea1ebb @technomancy Misc documentation tweaks.
technomancy authored Jun 21, 2010
53 ## Lancet
54
55 If your plugins need to do a fair amount of filesystem-y things, you
56 may want to take a look at using Ant tasks to do them since the JDK
57 lacks a lot of simple functionality of this kind. Using the Ant API
58 directly is a pain, but it can be eased to a degree using
b3fe397 @technomancy Switching all Github URLs to https.
technomancy authored Dec 2, 2010
59 [Lancet](https://github.com/stuarthalloway/lancet). Lancet is the
eea1ebb @technomancy Misc documentation tweaks.
technomancy authored Jun 22, 2010
60 Clojure adapter for Ant that is developed as the sample project in the
61 [Programming
62 Clojure](http://www.pragprog.com/titles/shcloj/programming-clojure)
63 book.
64
65 You can look over the [Ant API documentation's listing of
66 tasks](http://www.jajakarta.org/ant/ant-1.6.1/docs/en/manual/api/org/apache/tools/ant/taskdefs/package-summary.html)
67 to find an appropriate task. See the <tt>deps</tt> task for an example
68 of how to call a task from Clojure.
d2e016c @technomancy Implemented documentation suggestions from readers.
technomancy authored Jun 18, 2010
69
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
70 ## Hooks
71
72 You can modify the behaviour of built-in tasks to a degree using
dff976c @technomancy Documentation update.
technomancy authored Jul 18, 2010
73 hooks. Hook functionality is provided by the [Robert
b3fe397 @technomancy Switching all Github URLs to https.
technomancy authored Dec 3, 2010
74 Hooke](https://github.com/technomancy/robert-hooke) library. This is an
dff976c @technomancy Documentation update.
technomancy authored Jul 18, 2010
75 implied dependency; as long as Leiningen 1.2 or higher is used it will
76 be available.
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
technomancy authored Jun 11, 2010
77
78 Inspired by clojure.test's fixtures functionality, hooks are functions
79 which wrap tasks and may alter their behaviour by using binding,
80 altering the return value, only running the function conditionally,
81 etc. The add-hook function takes a var of the task it's meant to apply
82 to and a function to perform the wrapping:
83
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
technomancy authored Nov 11, 2011
84 ```clj
85 (use 'robert.hooke)
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
technomancy authored Jun 12, 2010
86
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
technomancy authored Nov 11, 2011
87 (defn skip-integration-hook [task & args]
88 (binding [clojure.test/test-var (test-var-skip :integration)]
89 (apply task args)))
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
90
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
technomancy authored Nov 11, 2011
91 (add-hook #'leiningen.test/test skip-integration-hook)
92 ```
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
93
94 Hooks compose, so be aware that your hook may be running inside
e9a7f03 @technomancy Documentation updates for 1.3.0.
technomancy authored Aug 20, 2010
95 another hook. To take advantage of your hooks functionality, projects
96 must set the :hooks key in project.clj to a seq of namespaces to load
97 that call add-hook. Note that in Leiningen 1.2, hooks get loaded and
98 used without being specified in project.clj; this is a bug. In 1.3 and
99 on they are opt-in only.
a920ab9 @technomancy Added documentation TODOs.
technomancy authored Aug 16, 2010
100
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
technomancy authored Jun 12, 2010
101 See [the documentation for
b3fe397 @technomancy Switching all Github URLs to https.
technomancy authored Dec 3, 2010
102 Hooke](https://github.com/technomancy/robert-hooke/blob/master/README.md)
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
technomancy authored Jun 12, 2010
103 for more details.
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
104
2940df0 @technomancy Replace .lein_classpath with .lein-classpath for consistency.
technomancy authored Jul 21, 2011
105 ## Altering Leiningen's Classpath
106
107 Leiningen's classpath will include all plugins from :dev-dependencies
108 as well as user plugins. To further modify the classpath of Leiningen
109 itself, add a '.lein-classpath' file a project's root. Its contents
110 will be prepended to Leiningen's classpath when Leiningen is invoked
111 upon that project.
112
1ba201f @technomancy Explain eval-in-project with dummy project arg in plugin docs.
technomancy authored Nov 11, 2011
113 ## Clojure Version
114
115 Note that Leiningen is an implied dependency of all plugins; you don't
116 need to explicitly list it in the project.clj file. You also don't
117 need to list Clojure or Contrib, but you will be locked into using the
118 same version of Clojure that Leiningen is using.
119
120 Versions of Leiningen prior to 1.2.0 used Clojure 1.1, while the rest
121 of the 1.x line uses Clojure 1.2. Leiningen 2.0 will use Clojure 1.3.
122 If you need to use a different version of Clojure from within a
123 Leiningen plugin, you can use `eval-in-project` with a dummy project
124 argument:
125
126 ```clj
127 (eval-in-project {:local-repo-classpath true
128 :dependencies '[[org.clojure/clojure "1.3.0"]]
129 :native-path "/tmp" :root "/tmp" :compile-path "/tmp"}
130 '(println "hello from" *clojure-version*))
131 ```
132
2940df0 @technomancy Replace .lein_classpath with .lein-classpath for consistency.
technomancy authored Jul 21, 2011
133 ## Lancet
7b42e09 @slagyr added docs for context specific classpath
slagyr authored Jul 1, 2011
134
135 Custom classpath elements can be added to Leiningen's startup command
4b369a3 renamed .classpath to .lein_classpath so that it doesn't conflict wit…
Phil Hagelberg authored Jul 16, 2011
136 by adding a '.lein_classpath' file the the working directory. When present,
137 the content from '.lein_.classclasspath' will be prepended to the classpath before
7b42e09 @slagyr added docs for context specific classpath
slagyr authored Jul 1, 2011
138 invoking the JVM.
139
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
140 ## Have Fun
141
7d44444 @technomancy Remove Leiningen's run-task in favour of Robert Hooke.
technomancy authored Jun 12, 2010
142 Please add your plugins to [the list on the
143 wiki](http://wiki.github.com/technomancy/leiningen/plugins).
144
46fa7d3 @technomancy Added plugin writing guide.
technomancy authored Jun 5, 2010
145 Hopefully the plugin mechanism is simple and flexible enough to let
146 you bend Leiningen to your will.
Something went wrong with that request. Please try again.