Class Hoe
In: lib/hoe-patched.rb
Parent: Object
Hoe dot/f_8.png

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

Constants

VERSION = '1.8.0'
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 extra dirs to both $: and RUBY_FLAGS (for test runs)

[Source]

# File lib/hoe-patched.rb, line 334
  def self.add_include_dirs(*dirs)
    dirs = dirs.flatten
    $:.unshift(*dirs)
    Hoe::RUBY_FLAGS.sub!(/-I/, "-I#{dirs.join(":")}:")
  end

[Source]

# File lib/hoe-patched.rb, line 702
      def self.dependent_upon name
        get_latest_gems.find_all { |gem|
          gem.dependencies.any? { |dep| dep.name == name }
        }
      end

[Source]

# File lib/hoe-patched.rb, line 696
      def self.get_gems_by_name
        @@by_name ||= Hash[*get_latest_gems.map { |gem|
                             [gem.name, gem, gem.full_name, gem]
                           }.flatten]
      end

[Source]

# File lib/hoe-patched.rb, line 692
      def self.get_latest_gems
        @@cache ||= get_source_index.latest_specs
      end

[Source]

# File lib/hoe-patched.rb, line 676
      def self.get_source_index
        return @@index if @@index

        dump = unless File.exist? '.source_index' then
                 url = GEMURL + "Marshal.#{Gem.marshal_version}.Z"
                 dump = Gem::RemoteFetcher.fetcher.fetch_path url
                 dump = Gem.inflate dump
                 open '.source_index', 'wb' do |io| io.write dump end
                 dump
               else
                 open '.source_index', 'rb' do |io| io.read end
               end

        @@index = Marshal.load dump
      end

Public Instance methods

[Source]

# File lib/hoe-patched.rb, line 438
  def developer name, email
    self.author << name
    self.email << email
  end

[Source]

# File lib/hoe-patched.rb, line 344
  def missing name
    warn "** #{name} is missing or in the wrong format for auto-intuiting."
    warn "   run `sow blah` and look at its text files"
  end

[Source]

# File lib/hoe-patched.rb, line 340
  def normalize_deps deps
    Array(deps).map { |o| String === o ? [o] : o }
  end

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)

[Source]

# File lib/hoe-patched.rb, line 1003
  def paragraphs_of(path, *paragraphs)
    File.read(path).delete("\r").split(/\n\n+/).values_at(*paragraphs)
  end

[Source]

# File lib/hoe-patched.rb, line 349
  def readme_name
    Dir['README*'].first || 'README.txt'
  end

[Validate]