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

Hoe Plugin Loading Sequence

  Hoe.spec
    Hoe.load_plugins
      require
    activate_plugins
      extend plugin_module
      initialize_plugins
        initialize_XXX
      activate_plugin_deps
        activate_XXX_deps
    yield spec
    post_initialize
      define_spec # gemspec, not hoespec
      load_plugin_tasks
      add_dependencies

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 = '3.5.0'   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|TAGS|extconf.h|\.o$|\.log$/, }   Default configuration values for .hoerc. Plugins should populate this on load.
WINDOZE = RbConfig::CONFIG['host_os'] =~ /mswin|mingw/   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]
licenses  [RW]  Optional: An array containing the license(s) under which this gem is released.
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]
urls  [RW]  Optional: The urls of the project. This can be an array or (preferably) a hash. Auto-populates to the urls read from the beginning of README.txt.

See parse_urls for more details

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)

Returns plugins that could not be loaded by Hoe.load_plugins.

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.

Returns true if the gem name is installed.

Intuit values from the readme and history files.

Specify a license for your gem. Call it multiple times if you are releasing under multiple licenses.

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)

Parse the urls section of the readme file. Returns a hash or an array depending on the format of the section.

    label1 :: url1
    label2 :: url2
    label3 :: url3

vs:

    * url1
    * url2
    * url3

The hash format is preferred as it will be used to populate gem metadata. The array format will work, but will warn that you should update the readme.

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

Reads Manifest.txt and returns an Array of lines in the manifest.

Returns nil if no manifest was found.

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. If not provided, start and finis will default to 1/1 and 12/31 of the current year.

Deprecated: Optional: The url(s) of the project. (can be array). Auto-populates to a list of urls read from the beginning of README.txt.

Verify that mandatory fields are set.

Loads ~/.hoerc, merges it with a .hoerc in the current pwd (if any) and yields the configuration and its path

[Validate]