Class Hoe
In: lib/hoe.rb
Parent: Object

hoe - a tool to help rake

Hoe is a simple rake/rubygems helper for project Rakefiles. It generates all the usual tasks for projects including rdoc generation, testing, packaging, and deployment.

Using Hoe

Basics

Use this as a minimal starting point:

  require 'hoe'

  Hoe.new("project_name", '1.0.0') do |p|
    p.rubyforge_name = "rf_project"
    # add other details here
  end

  # add other tasks here

Tasks Provided:

announce:Generate email announcement file and post to rubyforge.
audit:Run ZenTest against the package
check_manifest:Verify the manifest
clean:Clean up all the extras
config_hoe:Create a fresh ~/.hoerc file
debug_gem:Show information about the gem.
default:Run the default tasks
docs:Build the docs HTML Files
email:Generate email announcement file.
gem:Build the gem file only.
install:Install the package. Uses PREFIX and RUBYLIB
install_gem:Install the package as a gem
multi:Run the test suite using multiruby
package:Build all the packages
post_blog:Post announcement to blog.
post_news:Post announcement to rubyforge.
publish_docs:Publish RDoc to RubyForge
release:Package and upload the release to rubyforge.
ridocs:Generate ri locally for testing
test:Run the test suite. Use FILTER to add to the command line.
test_deps:Show which test files fail when run alone.
uninstall:Uninstall the package.

Extra Configuration Options:

Run config_hoe to generate a new ~/.hoerc file. The file is a YAML formatted config file with the following settings:

exclude:A regular expression of files to exclude from check_manifest.
publish_on_announce:Run publish_docs when you run release.
signing_key_file:Signs your gems with this private key.
signing_cert_file:Signs your gem with this certificate.
blogs:An array of hashes of blog settings.

Run config_hoe and see ~/.hoerc for examples.

Signing Gems:

Run the ‘generate_key’ task. This will:

  1. Configure your ~/.hoerc.
  2. Generate a signing key and certificate.
  3. Install the private key and public certificate files into ~/.gem.
  4. Upload the certificate to RubyForge.

Hoe will now generate signed gems when the package task is run. If you have multiple machines you build gems on, be sure to install your key and certificate on each machine.

Keep your private key secret! Keep your private key safe!

To make sure your gems are signed run:

  rake package; tar tf pkg/yourproject-1.2.3.gem

If your gem is signed you will see:

  data.tar.gz
  data.tar.gz.sig
  metadata.gz
  metadata.gz.sig

Methods

Constants

VERSION = '1.3.0'
PREFIX = ENV['PREFIX'] || ruby_prefix   Used to specify a custom install location (for rake install).
RUBY_DEBUG = ENV['RUBY_DEBUG']   Used to add extra flags to RUBY_FLAGS.
RUBY_FLAGS = ENV['RUBY_FLAGS'] || default_ruby_flags   Used to specify flags to ruby [has smart default].
FILTER = ENV['FILTER']   Used to add flags to test_unit (e.g., -n test_borked).

Attributes

author  [RW]  Recommended: The author(s) of the package. (can be array) Really. Set this or we‘ll tease you.
changes  [RW]  Recommended: A description of the release‘s latest changes.
clean_globs  [RW]  Optional: An array of file patterns to delete on clean.
description  [RW]  Recommended: A description of the project.
email  [RW]  Recommended: The author‘s email address(es). (can be array)
extra_deps  [RW]  Optional: An array of rubygem dependencies.
name  [RW]  MANDATORY: The name of the release.
need_tar  [RW]  Optional: Should package create a tarball? [default: true]
need_zip  [RW]  Optional: Should package create a zipfile? [default: false]
rdoc_pattern  [RW]  Optional: A regexp to match documentation files against the manifest.
remote_rdoc_dir  [RW]  Optional: Name of RDoc destination directory on Rubyforge. [default: name]
rsync_args  [RW]  Optional: Flags for RDoc rsync. [default: "-av —delete"]
rubyforge_name  [RW]  Optional: The name of the rubyforge project. [default: name.downcase]
spec_extras  [RW]  Optional: A hash of extra values to set in the gemspec. Value may be a proc.
summary  [RW]  Recommended: A short summary of the project.
test_globs  [RW]  Optional: An array of test file patterns [default: test/**/test_*.rb]
url  [RW]  Recommended: The url(s) of the project. (can be array)
version  [RW]  MANDATORY: The version. Don‘t hardcode! use a constant in the project.

Public Instance methods

Reads a file at path and spits out an array of the paragraphs specified.

  changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
  summary, *description = p.paragraphs_of('README.txt', 3, 3..8)

[Validate]