Added plugin writing guide.
This commit is contained in:
parent
915e61a830
commit
46fa7d392e
4 changed files with 77 additions and 4 deletions
2
NEWS
2
NEWS
|
@ -2,6 +2,8 @@ Leiningen NEWS -- history of user-visible changes
|
|||
|
||||
= 1.2.0 / ???
|
||||
|
||||
* Add plugin creation guide.
|
||||
|
||||
* Include arglists in help output.
|
||||
|
||||
* Make lein script usable from any subdirectory in the project root.
|
||||
|
|
68
PLUGINS.md
Normal file
68
PLUGINS.md
Normal file
|
@ -0,0 +1,68 @@
|
|||
# Leiningen Plugins
|
||||
|
||||
Leiningen tasks are simply functions in a leiningen.task namespace. So
|
||||
writing a Leiningen plugin is pretty straightforward; as long as it's
|
||||
available on the classpath, Leiningen will be able to use it.
|
||||
|
||||
To use a plugin, add it to your project.clj :dev-dependencies and run
|
||||
"lein deps". Then you'll be able to invoke it with "lein my-plugin".
|
||||
|
||||
## Writing a Plugin
|
||||
|
||||
Start by generating a new project with "lein new myplugin", and add a
|
||||
leiningen.myplugin namespace with a myplugin function. That function
|
||||
should take at least one argument: the current project. The project is
|
||||
a map which is based on the project.clj file, but it also has :name,
|
||||
:group, :version, and :root keys added in. If you want it to take
|
||||
parameters from the command-line invocation, you can make it take more
|
||||
arguments.
|
||||
|
||||
The docstring from the plugin's namespace will be displayed by the
|
||||
"lein help" task. The function's arglists will also be shown, so pick
|
||||
argument names that are clear and descriptive.
|
||||
|
||||
## Leiningen 1.2
|
||||
|
||||
The rest of this document only applies to Leiningen version 1.2+.
|
||||
|
||||
If your task returns an integer, it will be used as the exit code for
|
||||
the process.
|
||||
|
||||
You can set up aliases for your task by conjing a pair of strings with
|
||||
alias->task-name mappings on to the leiningen.core/aliases atom:
|
||||
|
||||
(swap! leiningen.core/aliases conj ["-v" "version"])
|
||||
|
||||
## Hooks
|
||||
|
||||
You can modify the behaviour of built-in tasks to a degree using
|
||||
hooks. Inspired by clojure.test's fixtures functionality, hooks are
|
||||
functions which wrap tasks and may alter their behaviour by using
|
||||
binding, altering the functions arguments or return value, only
|
||||
running the function conditionally, etc.
|
||||
|
||||
(defn skip-integration-hook [task]
|
||||
(binding [clojure.test/test-var (test-var-skip :integration)]
|
||||
(task)))
|
||||
|
||||
(add-hook 'test skip-integration-hook)
|
||||
|
||||
The add-hook function takes a symbol for which task it's meant to
|
||||
apply to. You can also pass in :all to have it apply to every task.
|
||||
|
||||
Hooks compose, so be aware that your hook may be running inside
|
||||
another hook. Hooks are loaded by looking for all namespaces under
|
||||
leiningen.hooks.* on the classpath and loading them in alphabetical
|
||||
order.
|
||||
|
||||
Please add your plugins to [the list on the
|
||||
wiki](http://wiki.github.com/technomancy/leiningen/plugins).
|
||||
|
||||
If you want to call another task from a plugin, don't call it
|
||||
directly. Call it with leiningen.core/run-task instead so it will load
|
||||
all its hooks and run the task wrapped inside them.
|
||||
|
||||
## Have Fun
|
||||
|
||||
Hopefully the plugin mechanism is simple and flexible enough to let
|
||||
you bend Leiningen to your will.
|
|
@ -10,6 +10,5 @@
|
|||
[ant/ant "1.6.5"]
|
||||
[jline "0.9.94"]
|
||||
[org.apache.maven/maven-ant-tasks "2.0.10"]]
|
||||
:dev-dependencies [[swank-clojure "1.2.1"]
|
||||
[autodoc "0.7.0"]]
|
||||
:dev-dependencies [[swank-clojure "1.2.1"]]
|
||||
:main leiningen.core)
|
||||
|
|
8
todo.org
8
todo.org
|
@ -18,8 +18,11 @@ Leiningen TODOs
|
|||
** DONE upgrade task (patch submitted)
|
||||
** DONE doc generation (autodoc plugin)
|
||||
* For 1.2.0
|
||||
** TODO document plugin creation
|
||||
** TODO document all known project.clj keys
|
||||
** TODO include lib/dev in find-lib-jars
|
||||
** TODO document version ranges
|
||||
** TODO document checkout dependencies
|
||||
** DONE document plugin creation
|
||||
** DONE document all known project.clj keys
|
||||
** DONE disable frickin [null] logging from ant (come on srsly)
|
||||
** DONE recover from missing test exit map gracefully
|
||||
** DONE Help task should display arglist
|
||||
|
@ -35,6 +38,7 @@ Leiningen TODOs
|
|||
** DONE classpath task to just print configured classpath
|
||||
** DONE move repl task from shell script to clojure code
|
||||
* For later
|
||||
** TODO test classification using metadata; run a subset of tests
|
||||
** TODO bin script has stabilized; self-install for dev versions should work
|
||||
** TODO differentiate between ns-level/fn-level help docstrings
|
||||
** TODO a list of dirs to include in the jar when building
|
||||
|
|
Loading…
Reference in a new issue