icing
adds dependency management and interactive building to CoffeeScript's cake
command and Cakefiles.
Install with npm: npm install icing
To add icing to a Cakefile add include the line:
require 'icing'
There are two significant ways icing breaks backwards compatibility with pre-existing Cakefiles.
- Using the
invoke
function to call other tasks is replaced by dependencies. - Task should now end by calling this.finished() or this.failed('Error message') to signify the completion of a task.
-w, --watch, Interactively build to target as source files change
-v, --verbose Enable verbose output mode
task 'js:coffee', 'Compile Coffee Script', ['src/*.coffee'],
outputs: ->
for file in this.filePrereqs
file.replace /src\/(.*)\.coffee/, 'lib/$1.js'
recipe: ->
this.exec "coffee -c -o lib/ #{this.modifiedPrereqs.join(' ')}"
task 'js:run', 'Run all compiled scripts', ['outputs(js:coffee)'],
outputs: ->
for file in this.filePrereqs
"output/#{file.replace /\//, '_'}"
recipe: ->
commands = for file in this.modifiedPrereqs
"node #{file} > output/#{file.replace '/', '_'}"
commands = ['mkdir -p output/'].concat commands
this.exec commands
task 'all', 'Run all tasks', ['task(js:run)'], ->
console.log 'Done.'
this.finished()
icing
introduces a new form of the task
function that has four parameters:
task target, description = '', prereqs = [ ], recipe
The target
and description
strings are unchanged from cake. prereqs
is an
array of strings that can refer to three different kinds of prereqs:
- Filenames. Filename strings are globbed, i.e.
src/*.coffee
- Task completion.
task(target)
creates a prereq on the completion of a task. - Task outputs.
outputs(target)
uses the file outputs of another task as prereqs.
recipe
should be an object that responds to the methods recipe
and outputs
.
When recipe
is just a function, as it is in traditional Cakefiles, it is turned
into an object whose recipe
method is that function and whose outputs
returns [].
Like with Cakefiles these methods will be passed the options
array containing
command-line options. Unlike Cakefiles, the this
context of the methods contains
callbacks and data.
outputs
method's this
context contains:
filePrereqs
- array of filenames, post-globbing, that are direct prereqs to the rule. This array is often mapped to an array of outputs.recipe
- the objectoutputs
andrecipe
methods are defined onprereqs
- array of unprocessed prereqstarget
- the name of the task
recipe
method's this
context contains:
exec(command)
- helper method for command line edecution that can take a single string command or an array of commands. It will call the commands one-by-one and upon successful completion of all commands will automatically call thefinished
callback. Else it will call thefailed
callback.finished()
- callback to signal successful completion of taskfailed(msg)
- callback to signal unsuccessful completion of taskfilePrereqs
- array of strings of prerequisites. Often used as inputs to commands executed. In this context prereqs have already been globbed so['src/*.coffee']
could become['src/a.coffee','src/b.coffee']
.outputs
- array of strings resulting from calling the outputs method of the recipe object.modifiedPrereqs
- if prereqs and outputs are both defined this is the list of files that have been modified more recently than their outputs.
- In interactive / watch mode poll globbed locations to pick-up on new files and rebuild dependency graph when detected.
the subgraph between the modified source and the target to more efficiently recompute large dependency graphs.