Reap

Reap is a set of integrated tasks designed to simplify the life of Ruby application developers and project managers. The tasks cover the range of common nneds, from setting up a standard project structure to distributing and announcments. Because of the commonality between the tasks, Reap utilizes a central YAML-format configuration file to harvest project information, significantly simplifying usage.

Custom task can also be easily created to suit specific project requirements. In this respect Reap is much like Rake. In fact Reap can be used as a replacement for Rake. On the other hand Reap tasks can also be used via Rake just as if they were another set of avaiable Rake tasks.

Usage

To use Reap, you simply need to install it and add a ProjectInfo to your projects main directory. By default, Reap supports the standard project layout as promoted by setup.rb.

Once you ProjectInfo file is filled out you can see what tasks are ready to run simply by typing 'reap' into the command line. For example you might see something like:

    ~/myproj$ reap

      info           Display ProjectInfo file.
      testext        Extract unit-tests from lib scripts.
      test           Run unit-tests (each in a separate process).
      rdoc           Generate API Documentation.
      doap           Generate DOAP project file.
      publish        Publish documents to the web.
      perm           Normalize ownership and permissions of files.
      package        Build distribution packages.
      install        Locally install package using built-in setup.rb.
      release        Release distribution files.
      announce       Email project announcement.

To get started, it easiest to use a pre-existing ProjectInfo file and modifying it to fit your project. Besides copying another project's ProjectInfo file you can ask Reap for an empty one.

    ~/myproj$ reap template

Each task section of the project information file can be used as a task name and a YAML private type identifies the type of task it represents. To find out what parameters each task accepts see Reap's RDoc API.

If you prefer using Rake for all your project tasks. Reap provides an simple interface for doing so. Here's an example of a Rakefile.

    require 'rake'
    require 'reap/reap'

    task_package 'pack' do |pkg|
      pkg.distribute = [ 'gem' ]
      pkg.dependencies = [ facets ]
    end

In the above, all information is provided directly via the Ruby task code. You can also use Rake while utilizing the ProjectInfo file, if you prefer. In that case it is very simple. In your Rake file simple put:

    require 'rake'
    require 'reap/rake'

Then all the tasks defined in the ProjectInfo file will be available via Rake. You can add additional Rake tasks, of course.

Creating Tasks

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.

The first thing you need to know is where to put the tasks code. With Reap each task typically has it's own file. To create a custom task particular to a project add a task/ directory to your project and place your custom task file in it.

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.

It's a good idea to take some time and learn all the standard properties of a project's information file which you can draw on for your own tasks. Looking at the RDoc API documentation will elucidate most these.

The rest of building a task is a matter or writing the code to have it do what you want it to, of course. If you develop any nice tasks, be sure to pass them along!

Status

Reap works fairly well at this point, although not all intended functionality is complete. The primary tasks, like packaging, testing and rdocing are the most well developed. Other tasks have some limitations. For instance, the publish task is limited to uploading to RubyForge at the moment. And the announcment task can't route email via TLS servers. But Reap is very usable and is used in a number of projects including Facets and Nitro. Moreover, if you use it, contributions to it's improvement are very welcome and will be sung many wonderous praises ;)

IMPORTANT!!! Microsoft Windows support is weak at the moment. No doubt a few of the built-in tasks will fail under Windoes. But fixing this issues is a high priority for upcoming releases. So staty tuned --or heck, help out!

Future

The future of Reap looks very bright. Some of the plans for the future include:

1. Code audit to catch any overlooked bugs and potential gotchas.
2. Full Windows compatability, replacing most of the shell calls.
3. Switching from setup.rb to an improved package.rb install system.
4. SCM related tasks, starting with Darcs and later Subversion.

License

THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.