= DRAKE -- Distributed Rake

A branch of Rake supporting parallel task execution.

== Synopsis

Run up to three tasks in parallel:

  % drake -j3

or equivalently,

  % drake --threads 3

== Installation

  % gem install drake

== Notes

=== Compatibility

Drake is 100% compatible with Rake.  The code path for --threads=1 is
effectively identical to that of Rake's.  Drake passes all of Rake's
unit tests, with any number of threads from 1 to 1000 (that's the most
I tested).

=== Dependencies

In a given Rakefile, it is possible (even likely) that the dependency
tree has not been properly defined.  Consider

   task :a => [:x, :y, :z]

With single-threaded Rake, _x_,_y_,_z_ will be invoked *in that order*
before _a_ is invoked.  However with drake --threads=N (for N > 1),
one should not expect any particular order of execution.  Since there
is no dependency specified between _x_,_y_,_z_ above, Drake is free to
run them in any order.

If you wish _x_,_y_,_z_ to be invoked sequentially, then write

   task :a => seq[:x, :y, :z]

This is shorthand for

   task :a => :z
   task :z => :y
   task :y => :x

Upon invoking _a_, the above rules say: "Can't do _a_ until _z_ is
complete; can't do _z_ until _y_ is complete; can't do _y_ until _x_
is complete; therefore do _x_."  In this fashion the sequence
_x_,_y_,_z_ is enforced.

The problem of insufficient dependencies plagues Makefiles as well.
Package maintainers affectionately call it "not j-safe."

=== MultiTask

The use of +multitask+ is deprecated.  Tasks which may properly be run
in parallel will be run in parallel; those which cannot, will not.  It
is not the user's job to decide.

Drake's +multitask+ is an alias of +task+.

=== Task#invoke inside Task#invoke

Parallelizing code means surrendering control over the
micro-management of its execution.  Manually invoking tasks inside
other tasks is rather contrary to this notion, throwing a monkey
wrench into the system.  An exception will be raised when this is
attempted in non-single-threaded mode.

== Links

* Download: * http://rubyforge.org/frs/?group_id=6530
* Rubyforge home: http://rubyforge.org/projects/drake
* Repository: http://github.com/quix/rake

== Author

* James M. Lawrence <quixoticsycophant / gmail.com>