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

Hoe is a simple rake/rubygems helper for project Rakefiles. It helps generate rubygems and includes a dynamic plug-in system allowing for easy extensibility. Hoe ships with plug-ins for all your usual project tasks including rdoc generation, testing, packaging, and deployment.

Using Hoe

Basics

Sow generates a new project from scratch. Sow uses a simple ERB templating system allowing you to capture patterns common to your projects. Run `sow` and then see ~/.hoe_template for more info:

  % sow project_name
  ...
  % cd project_name

and have at it.

Extra Configuration Options:

Hoe maintains a config file for cross-project values. The file is located at ~/.hoerc. The file is a YAML formatted config file with the following settings (extended by plugins):

exclude:A regular expression of files to exclude from check_manifest.

Run `rake config_hoe` and see ~/.hoerc for examples.

Extending Hoe

Hoe can be extended via its plugin system. Hoe searches out all installed files matching ‘hoe/*.rb‘ and loads them. Those files are expected to define a module matching the file name. The module must define a define task method and can optionally define an initialize method. Both methods must be named to match the file. eg

  module Hoe::Blah
    def initialize_blah # optional
      # ...
    end

    def define_blah_tasks
      # ...
    end
  end

Methods

Included Modules

Rake::DSL

Classes and Modules

Module Hoe::Clean
Module Hoe::Compiler
Module Hoe::Debug
Module Hoe::Deps
Module Hoe::Flay
Module Hoe::Flog
Module Hoe::GemPreludeSucks
Module Hoe::Gemcutter
Module Hoe::Inline
Module Hoe::Newb
Module Hoe::Package
Module Hoe::Publish
Module Hoe::RCov
Module Hoe::Racc
Module Hoe::RubyForge
Module Hoe::Signing
Module Hoe::Test

Constants

VERSION = '2.9.4'   duh
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].
DEFAULT_CONFIG = { "exclude" => /tmp$|CVS|\.svn|\.log$/, }   Default configuration values for .hoerc. Plugins should populate this on load.
WINDOZE = /mswin|mingw/ =~ RUBY_PLATFORM unless defined? WINDOZE   True if you‘re a masochistic developer. Used for building commands.

Attributes

author  [RW]  MANDATORY: The author(s) of the package. (can be array)

Use the developer method to fill in both author and email cleanly.

changes  [RW]  Optional: A description of the release‘s latest changes. Auto-populates to the top entry of History.txt.
description  [RW]  Optional: A description of the project. Auto-populates from the first paragraph of the DESCRIPTION section of README.txt.

See also: Hoe#summary and Hoe.paragraphs_of.

description_sections  [RW]  Optional: What sections from the readme to use for auto-description. Defaults to %w(description).
email  [RW]  MANDATORY: The author‘s email address(es). (can be array)

Use the developer method to fill in both author and email cleanly.

extra_deps  [RW]  Optional: An array of rubygem dependencies.
  extra_deps << ['blah', '~> 1.0']
extra_dev_deps  [RW]  Optional: An array of rubygem developer dependencies.
extra_rdoc_files  [RW]  Optional: Extra files you want to add to RDoc.

.txt files are automatically included (excluding the obvious).

history_file  [RW]  Optional: The filename for the project history. [default: History.txt]
name  [RW]  MANDATORY: The name of the release.

Set via Hoe.spec.

post_install_message  [RW]  Optional: A post-install message to be displayed when gem is installed.
readme_file  [RW]  Optional: The filename for the project readme. [default: README.txt]
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.
  spec_extras[:required_rubygems_version] = '>= 1.3.2'

(tho, see pluggable! if that‘s all you want to do)

summary  [RW]  Optional: A short summary of the project. Auto-populates from the first sentence of the description.

See also: Hoe#description and Hoe.paragraphs_of.

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]
url  [RW]  Optional: The url(s) of the project. (can be array). Auto-populates to a list of urls read from the beginning of README.txt.
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 and rakefile deps)

Find and load all plugin files.

It is called at the end of hoe.rb

Activates plugins. If a plugin cannot be loaded it will be ignored.

Plugins may also be activated through a plugins array in ~/.hoerc. This should only be used for plugins that aren‘t critical to your project and plugins that you want to use on other projects.

The list of active plugins.

Execute the Hoe DSL to define your project‘s Hoe specification (which interally creates a gem specification). All hoe attributes and methods are available within block. Eg:

  Hoe.spec name do
    # ... project specific data ...
  end

Public Instance methods

Activate plugin modules and add them to the current instance.

Add standard and user defined dependencies to the spec.

Define the Gem::Specification.

Add a dependency declaration to your spec. Pass :dev to type for developer dependencies.

Returns the proper dependency list for the thingy.

Convenience method to set add to both the author and email fields.

Intuit values from the readme and history files.

Load activated plugins by calling their define tasks method.

Bitch about a file that is missing data or unparsable for intuiting values.

Normalize the dependencies.

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)

Tell the world you‘re a pluggable package (ie you require rubygems 1.3.1+)

This uses require_rubygems_version. Last one wins. Make sure you account for that.

Is a plugin activated? Used for guarding missing plugins in your hoe spec:

  Hoe.spec "blah" do
    if plugin? :enhancement then
      self.enhancement = true # or whatever...
    end
  end

Finalize configuration

Declare that your gem requires a specific ruby version. Last one wins.

Declare that your gem requires a specific rubygems version. Last one wins.

Provide a linear degrading value from n to m over start to finis dates.

Verify that mandatory fields are set.

Loads ~/.hoerc and yields the configuration and its path

[Validate]