Skip to content
Aaron Crow edited this page Aug 9, 2013 · 13 revisions

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.

Using Plugins

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.

Creating Plugins

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

Illustrative example

As an illustrative example of a simple plugin, take a look at drake-echostep.

Community guidelines

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"
 ...)

Share your plugin

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

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.

Setting Repos

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.