-
Notifications
You must be signed in to change notification settings - Fork 110
Plugins
Drake supports plugins as of version 0.1.4.
Plugins allow anyone to create and use custom protocols in Drake. A plugin provides custom behaviour for a new protocol, associated with a protocol name. The protocol name is chosen by the plugin's creator.
The protocol implementation provided by the plugin has full access to all step data. Therefore it can do just about anything it needs to do to fulfill its requirements. Presumably this will revolve around processing the step's input(s) to produce some output(s), doing something cool along the way.
To use a plugin that someone else has published, specify it in your plugins.edn
file, located in the same directory as your Drakefile. (Create it if you don't already have one.)
The plugins.edn
file contains a hash-map of plugin configuration. The :plugins
entry specifies an array of Maven repository coordinates for published Drake plugins.
Example plugins.edn
file contents:
{:plugins [[dirtyvagabond/drake-echostep "0.1.0"]
[dirtyvagabond/drake-honeyql "0.0.3"]]}
By default, Drake will look for the specified plugins in Maven Central and clojars.org. See the Setting Repos section below if you need to use plugins from repositories other than the defaults.
To create a plugin you create and publish a Clojure project that provides the implementation for your protocol. Your project must follow these conventions:
- Define a namespace called
drake.[PROTOCOL_NAME]
, e.g.drake.myprotocol
- In that namespace define a function called [PROTOCOL_NAME], e.g.
myprotocol
- In that function take one argument -- the step's data
- In that function, do whatever you want your protocol to do
As an illustrative example of a simple plugin, take a look at drake-echostep.
It's suggested, but not required, that you name your Drake plugin project like drake-[PROTOCOL_NAME]
, e.g. drake-myprotocol
.
It's strongly suggested, but not required, that you use a unique group name, tied to you, when you publish your plugin to a public repo. E.g., your project.clj might be:
(defproject mycompany/drake-myprotocol "0.0.2"
...)
To share your plugin with the world, publish it to a public Maven repository. A common and easy approach is to use lein push
. But you can also publish your plugin to a private internal repo if you want to share it with workmates but not the whole wide world. Or you could use something like lein install
to publish the plugin only for your local development environment.
Your protocol function must take exactly one argument -- the step data. Drake will pass this to your function when your protocol is invoked by a worklow. The step data will be a typical Clojure hash-map with all the step's data as entries.
Here's an illustrative function, taken from the echostep
protocol implementation:
(defn echostep
"Formats the step hash-map and spits it to the step's output file."
[step]
(let [outfile (first (:outputs step))
pretty-step (with-out-str (clojure.pprint/pprint step))]
(spit outfile pretty-step)))
See TODO for more details about the contents of the step hash-map.
If you wish to use plugins from repositories other than the deafults, you can specify additional repos in your plugins.edn
file. E.g.:
{:repositories {"jboss" "https://repository.jboss.org/nexus/content/repositories/thirdparty-uploads"]
"mycorp" "http://mycorp.com/nexus/content/groups/public"}
:plugins [[dirtyvagabond/drake-echostep "0.1.0"]
[dirtyvagabond/drake-honeyql "0.0.3"]]}
These will be merged in with the defaults.