Class: Hoe

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: | Create news email 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.
deps:email: | Print a contact list for gems dependent on this gem
deps:fetch: | Fetch all the dependent gems of this gem into tarballs
deps:list: | List all the dependent gems of this gem
docs: | Build the docs HTML Files
email: | Generate email announcement file.
gem: | Build the gem file hoe-1.8.0.gem
generate_key: | Generate a key for signing your gems.
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.
tasks: | Generate a list of tasks for doco.
test: | Run the test suite.
test_deps: | Show which test files fail when run alone.

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

### Platform awareness

Hoe allows bundling of pre-compiled extensions in the `package` task.

To create a package for your current platform:

      rake package INLINE=1

This will force Hoe analize your `Inline` already compiled extensions and include them in your gem.

If somehow you need to force a specific platform:

      rake package INLINE=1 FORCE_PLATFORM=mswin32

This will set the +Gem::Specification+ platform to the one indicated in `FORCE_PLATFORM` (instead of default Gem::Platform::CURRENT)

### Methods

add_include_dirs dependent_upon developer get_gems_by_name get_latest_gems get_source_index missing normalize_deps normalize_names paragraphs_of

### Constants

VERSION | = | '1.8.3'
GEMURL | = | URI.parse 'http://gems.rubyforge.org'
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.
blog_categories | [RW] | Optional: An array of the project‘s blog categories. Defaults to project name.
changes | [RW] | Optional: A description of the release‘s latest changes. Auto-populates.
clean_globs | [RW] | Optional: An array of file patterns to delete on clean.
description | [RW] | Optional: A description of the project. Auto-populates.
description_sections | [RW] | Optional: What sections from the readme to use for auto-description. Defaults to %w(description).
email | [RW] | Recommended: The author‘s email address(es). (can be array)
extra_deps | [RW] | Optional: An array of rubygem dependencies.
extra_dev_deps | [RW] | Optional: An array of rubygem developer dependencies.
multiruby_skip | [RW] | Optional: Array of incompatible versions for multiruby filtering. Used as a regex.
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]
post_install_message | [RW] | Optional: A post-install message to be displayed when gem is installed.
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] | Optional: A short summary of the project. Auto-populates.
summary_sentences | [RW] | Optional: Number of sentences from description for summary. Defaults to 1.
test_globs | [RW] | Optional: An array of test file patterns [default: test/**/test_*.rb]
testlib | [RW] | Optional: What test library to require [default: test/unit]
url | [RW] | Optional: The url(s) of the project. (can be array). Auto-populates.
version | [RW] | MANDATORY: The version. Don‘t hardcode! use a constant in the project.

### Public Class methods

add_include_dirs(*dirs)

Add extra dirs to both $: and RUBY_FLAGS (for test runs)

dependent_upon(name)
get_gems_by_name()
get_latest_gems()
get_source_index()
normalize_names(project)

### Public Instance methods

developer(name, email)
missing(name)
normalize_deps(deps)
paragraphs_of(path, *paragraphs)

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]