Reap – A Project Assistant for Ruby

Reap is an easy to use project assistant for Ruby developers. Reap makes it easy to do the following tasks:

  • Build new convention-based project folders.

  • Generate RDoc API documentation.

  • Run unit tests (each in it’s ruby process).

  • Extract comment embedded tests from source code.

  • Run comment embedded unit test directly from source.

  • Create source tar.gz, tar.bz2 and zip packages.

  • Create RubyGem and Debian packages, plus pacman PKGBUILDs.

  • Publish documents to Rubyforge or other web sites.

  • Make announcement to ruby-talk or other mailing list.

  • Prepare files for distribution (i.e. chmod, tag, etc.)

  • Release distributions on Rubyforge or other such host.

  • Generate XML-format DOAP project file.

New features continue to be be developed. If you have special needs that Reap doesn’t accomodate, new tasks are farily easy to create. And Reap’s maintainers are always happy to engage suggestions.

Installation

Requirements

Reap requires Ruby Facets. If manually installing be sure to have the latest version of Facets installed too.

Gem Install

Install the ruby gem as you would any other:

gem install reap

Gems still suffers from the datadir problem, so we’ve had to create some work arounds, for the template and scaffold tasks in particular. If you have any trouble with the Gem install please let us know so we can correct.

Manual Install

To install manually follow the usual setup.rb steps:

  1. Download the compressed package.

  2. Unpack it.

  3. Change into the unpacked directory.

  4. 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 utilizes a single data file, called the ProjectInfo file, to describe project procedures.

To use Reap the first thing your project will need is a ProjectInfo file in it’s main directory. A template is provided and a task to copy it to your current directory. Simply type:

% reap template

Then edit the ProjectInfo file created. The fields are fairly self explanitiory. The template has a number of commented-out exmaples. Apart from utilization by Reap, such a file is even nice to have just on it’s own informative merits too.

Alternatively, Reap can build an entire new project directory with all the conventional components pre-arranged. Try it by creating a new empty directory, changing into it and then typing:

% reap scaffold

The directory will be filled out with all the ususal directories, lib/, bin/, etc. If you use subversion for version management, you can create a subversion layout instead.

% reap scaffold svn

Filling out a ProjectInfo file is simply a matter adding entries for the primary information of you project and adding sections for the tasks you wish to use in for project. For example to use the RDoc task you could add:

document: !!rdoc
  dir: rdoc

By default Reap’s Rdoc task will look in the bin/ lib/ and ext/ directories for ruby scripts to document. Or you can specify exactly which files to include (See the Reap RDocs themselves for parameter details.) Some tasks can operate automatically based on reasonable defaults. Indeed in some cases all one might need is the one line:

name: !!task

In others cases certain parameters are required for the task to function. But Reap will do it’s best to extrapolate the needed information from what’s available in the ProjectInfo file.

Once you have some entries in your ProjectInfo file, enter:

% reap

And you will see a list of executable tasks. To run a task enter:

% reap [task]

For basic help try:

% reap help

For a list of all avaialbe tasks or to get more detailed help on how to use a particular task have a look at the RDoc API documentation.

Building a Reap Task

Building a Reap task is pretty easy too. In fact if you ever used Rake you already have a good idea about how to do it.

First make sure your project has a task/ folder. Any file in that folder will be read by Reap and used to setup tasks. In a file with in that folder you can add a task or collection of tasks. Here’s an “oh-so-simple” example:

module Tasks

  def simple( name, data )

    desc 'This is a custom reap task class.'

    task name do
      data.message ||= master.message
      puts data.message + "\n\n" + data.signed
    end

  end

end

The corresponding settings in the ProjectInfo file will then be:

message: Hi, how are you?

simple: !!simple
  signed: Your friend, Tom.

And to use it type:

% reap simple

Notice the reference to ‘master’. This is an OpenCascade interface (similar to OpenObject and OpenStruct) to the whole ProjectInfo dataset.

You might recognize the core methods of creating a task, ‘desc’ and ‘task’. These are used exactly as they are in Rake. We encapsulate them in a task-definition method (eg. simple) so the task can be generated dyanmically if such a section (!!simple) appears in the ProjectInfo file. Such task-definition methods are recognized by reap b/c they are stored in the special purpose Tasks module.

Status

Reap is currently what one might call “usable beta”. Most of the tasks work very well. Refinements are still common though.

Also, Windows support is weak. Reap hasn’t been fully tested in that environment so it is likely a few tasks will not yet work in this case. If you are Windows user and would like to use Reap, we would really appreciate someone working out the issues here.

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