Devoh

Building Gems and RDocs with Rake

While working on Ruby projects, you're bound to reach a point with some of them where a build file becomes necessary. Typically, Ruby projects rely on Rake to fulfill this role, and a typical Rakefile will handle such tasks as building gems and running tests or specs.

Here's a simple Rakefile excerpt that handles defining and building a gem.

require 'rake/gempackagetask'

spec = Gem::Specification.new do |spec|
  spec.name = 'project_name'
  spec.version = '0.0.1'
  spec.summary = 'A sample project for showing how to use Rake.'
  spec.author = 'Author Name'
  spec.email = 'author@example.com'
  spec.homepage = 'http://example.com/'
  spec.platform = Gem::Platform::RUBY
  spec.files = FileList['{bin,lib}/**/*'].to_a
  spec.require_path = 'lib'
  spec.autorequire = 'project_name'
  spec.has_rdoc = true
  spec.extra_rdoc_files = ['README', 'LICENSE']
  spec.add_dependency('hpricot', '>= 0.6')
end

Rake::GemPackageTask.new(spec) do |package|
  package.need_tar = true
end

There's quite a few parameters to set up here, but not all of them are required, and for the most part it's just a matter of filling in the blanks with the values specific to your project. Now, issuing a simple rake gem from the root of the project will scour the source files and bundle everything up into a nice, neat gem.

The next addition to your Rakefile you might want to make is to add support for RDocs.

Rake::RDocTask.new do |rdoc|
  rdoc.title = 'Project Documentation'
  rdoc.main = 'README'
  rdoc.rdoc_dir = 'doc'
  rdoc.rdoc_files.include('README', 'LICENSE', 'lib/**/*.rb')
end

Again, a very straightforward task, and a simple rake rdoc will generate and output the docs as HTML.