File: README

# README

Path: | README
Last Update: | Wed Mar 24 20:48:29 +0000 2010

Echoe

A Rubygems packaging tool that provides Rake tasks for documentation, extension compiling, testing, and deployment.

## License

Copyright 2007, 2008 Cloudburst, LLC. Licensed under the AFL 3. See the included LICENSE file. Portions copyright 2006 Ryan Davis/Zen Spider Software and used with permission. See the included MIT-LICENSE file.

The public certificate for the gem is here.

If you use this software, please make a donation, or recommend Evan at Working with Rails.

## Features

- simple configuration
- comprehensive gem deployment
- cross-packaging
- signed gem support
- automatic changeset parsing
- documentation upload to any host

# Usage

## Installation

Install the gem:

      sudo gem install echoe

If you haven‘t already, make sure Rubyforge is configured locally and your password is correctly set:

      rubyforge setup
      rubyforge config

## Project configuration

Organize your gem according to the usual structure:

      lib/
      README
      LICENSE
      CHANGELOG
      Rakefile

You can add the `bin/` or `ext/` folders if you have executables or extensions, respectively.

Your `CHANGELOG` should be formatted as follows (including newlines):

      v2.1. newest change

      v2. older change

      v1.9. oldest change

This way Echoe can parse the latest version and changeset message automatically.

Your `Rakefile` needs the following minimal contents:

      require 'echoe'
      Echoe.new('gem_name')

More advanced configuration is described in the Echoe class.

## Deploying your gem

To deploy the gem and documentation:

      rake manifest
      rake release
      rake publish_docs

Once you‘ve built your manifest, you only need to rebuild it if you add or remove files from the package structure.

# Extras

## All Rake tasks

The following tasks are made available to your gem.

Packaging:

- `manifest` - Build a manifest list. Shows added and removed files.
- `docs` - Build the documentation.
- `package` - Build all the packages.

Testing:

- `test` - Run the test suite.
- `coverage` - Generate a coverage report.
- `compile` - Compile C extensions, if available.
- `clean` - Clean up generated documentation, packaging, and build files.
- `install` - Install the gem locally.
- `uninstall` - Uninstall the gem.

Upload:

- `publish_docs` - Publish documentation to the web.
- `release` - Package and upload the latest release to Rubyforge.
- `announce` - Generate a release announcement, edit it, and post it to Rubyforge.

Cleaning:

- `clean` - Delete all the generated documentation and packages.
- `redocs` - Force a rebuild of the Rdoc files.
- `repackage` - Force a rebuild of the package files.

## Reporting problems

The support forum is here.

Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.

## Further resources

- blog.evanweaver.com/articles/2007/01/10/if-you-dont-want-to-hoe-echoe

[Validate]