= Reap

Project Assitant for Ruby


== What's This Then?

Reap is an easy to use project assistant for Ruby developers.
By organizing your project in a conventional manner, 
(as promoted by setup.rb), Reap makes it easy to do the
following tasks:

* Generate RDoc API documentation.
* Run unit tests (each in it's ruby process).
* Extract embedded tests from source code.
* Run embedded unit test directly.
* Create source tar and/or zip packages.
* Create Ruby Gem and/or Debian packages.
* Publish documents to Rubyforge or other web sites.
* Announce a release to Ruby-talk or other mailing list.
* Prepare files for distribution (i.e. chmod, tag, etc.).
* Release distributions on Rubyforge or other host.
* Even generate a DOAP project file.

If you have special needs that Reap doesn't accomodate,
new tasks are farily easy to create. And I am always
happy to engage suggestions.


== Installation

Note that Reap requires Ruby Facets.

=== Gem Install

Install the ruby gem as you would any other:

  <tt>gem install reap</tt>

Gems still suffers from the datadir problem,
so the template and scaffold commands
may report missing files if you use this
installation method. A fix is in the works,
but for the moment it is better to use the 
manual install.

=== Manual Install

To install manually follow the usual setup.eb steps:

1. Download the compressed package.
2. Unpack it.
3. Change into the unpacked directory.
4. run <tt>sudo ruby setup.rb</tt>

You should be good to go.


== Usage

=== Using a Reap Task

Reap makes it pretty easy to use it's built-in tasks.
Largely this is because it grabs common data from the
ProjectInfo file. Some tasks can operate automatically based
on reasonable defaults, others require section entries 
in the ProjectInfo file.

For instance, to create a "package" target you generally do not need
an entry in the ProjectInfo file. Reap will package up everything
in the typical directories and makes compressed versions in the most
common formats. It will then place those in either dist/, pkg/,
../packages/, ../dist or ../pkg.  Depending on which of these exists.
The reasonable assumtions exist for other tasks. Reap will do
it's best to extrapolate the needed information waht's avaialbe
in the ProjectInfo file.

Of course, no matter the level of content, you will need to
create this file in you projects main directory. A template is provided
and a command to copy it to your current directory. Simply type:

  > reap template

Then edit the ProjectInfo file creted. The fields are fairly self
explanitiory. Apart from Reap, such a file is nice to have just on
it's own merits too.

Reap can also build an entire new project directory with all the 
standard components. Try:

  > reap scaffold myproj

A new directory will be created called 'myproj' with all the ususal
directories like lib/, bin/, etc.  If you use subversion for
version management, you can create a subversion layout easily
as well.

  > reap scaffold svn

For more help, use

  > reap help

or

  > reap help [task]

Supplying the task name provides specific help for that particular task.


=== Building a Reap Task

Building a Reap task is pretty easy too, but is is quite different
from building a Rake task. You are just defining a method, but a
whole class.

Here's an "oh so simple" example:

  class OhSoSimple < Reap::Task

     task_desc 'This is a custom reap task'

     task_help %{

       reap ohsosimple

       This is help information for a custom reap task.

     }

     alias_method :ohso, :task

     def run
       ohso.message ||= 'None Found!'
       ohso.another ||= 'Again!'

       puts ohso.message + "\n" + ohso.another
     end

   end

The corresponding settings in the ProjectInfo file (master) will then be:

   message: Default text, if any.

   ohsosimple:
     another: Your other message here.

And to use it

  > reap ohsosimple

While Reap had used instance varaibles for task properties in the past,
But has changed as of version 4.3.3. Now it uses the 'task' object,
which can be referenced by any name you like is you alias it.
The nice thing about using this interface instead of instance
variables is that reap will automatically search the
ProjectInfo's root if the property is not found in the task
specific section. This allows for a nice form of inheritance
within the document.

Sometimes you may need to override this inheritance behavor, though.
In that case just set the task property directly equal to the
section property in the run method. Eg.

     def run
       task.message = section.message
       ...
     end

Notice we used 'task' here rather than 'osho'. This task object
is always available. In the above, 'osho' is just being aliased
to 'task' for readability convenience. Both refer to the same
underlying object.


== Status

Reap is currently "Usable Beta". Most of the tasks
work very well. Refinements are still common though.


== Legal

Reap
Copyright(c)2004-2006 Thomas Sawyer
Ruby License