Task Writer's Guide

This document describes some conventions and idioms of the boot-o-sphere.

Note: This is a work in progress. Please feel free to edit here!

Naming Conventions

Using some standard naming conventions makes it easy for users to find and require your tasks into their projects.

Project

Tasks project group and artifact ids are generally of the form

<group-id>/boot-<task>

for instance,

adzerk/boot-cljs

Namespaces

Task projects should have a single namespace containing the task definitions. This namespace is generally named after the group and project ids. For the above example this namespace would be named:

adzerk.boot-cljs

This makes it easy for the user to require your tasks in their build.boot file without having to look up the namespace name.

Patterns

Metadata

(deftask example
  "Example demonstrating the metadata pattern"
  []
    (boot/with-pre-wrap fileset
      (let [metadata (:metadata (meta fileset))
            updated-metadata (do-something metadata)
            fs-with-meta (with-meta fileset {:metadata updated-metadata})]
        ...
        fs-with-meta))))

Use cases:

• Inter-task communication

For example:

1. boot-cljs adds dependency order of compiled js as metadata on the TmpFile objects in the fileset
2. boot-reload uses this metadata in order to send change events to the client in the correct reload order

Commentary: Tasks don't know anything about each other, and don't need to. Any task can add metadata on the immutable fileset. If we're writing a coffeescript task, as long as the coffee task adds its own dependency metadata to its own compiled js files in the fileset, the reload task will work correctly.

• Data about data (metadata, duh!)

See how the perun project, a static blog engine, saves its sitemap as metadata on the fileset.

Task Arguments/Options

There is a separate page describing the processing of task options.

https://github.com/boot-clj/boot/wiki/Task-Options-DSL