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:

Download the compressed package.
Unpack it.
Change into the unpacked directory.
run sudo ruby setup.rb

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

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