Automatically Building a Gem

Table of contents:

Credit: Stefan Lang

Problem

You want to automatically build a gem package for your application or library whenever you do a release.

Solution

Require the rake/gempackagetask library within your Rakefile, and create a Gem:: Specification instance that describes your project. Feed it to the Rake:: GemPackageTask constructor, which automatically defines a number of gem-related tasks:

	require 
ake/gempackagetask

	# Create a gem specification
	gem_spec = Gem::Specification.new do |s|
	 s.name = docbook
	 s.version = 1.0.0
	 s.summary = DocBook formatting program and library.

	 # Files containing Test::Unit test cases.
	 s.test_files = FileList[	ests/**/*]

	 # Executable scripts under the "bin" directory.
	 s.executables = [voc]

	 # List of other files to be included.
	 s.files = FileList[README, ChangeLog, lib/**/*.rb]
	end

	Rake::GemPackageTask.new(gem_spec) do |pkg|
	 pkg.need_zip = false
	 pkg.need_tar = false
	end

Run the command rake package, and (assuming those files actually exist), Rake will build a gem file docbook-1.0.0.gem under the pkg/ directory.

Discussion

The RubyGems library provides the Gem::Specification class, and Rake provides the Rake::GemPackageTask class that uses it. Creating a new Rake::GemPackageTask object automatically defines the three tasks: package, clobber_package, and repackage.

The package task builds a gem inside the projects pkg/ directory. The clobber_package task removes the pkg/ directory and its contents. The repackage task just invokes clobber_package to remove any old package file, and then invokes package to rebuild them from scratch.

The example above sets to false the attributes need_zip and need_tar of the Rake::GemPackageTask. If you set them to true, then in addition to a gem youll get a ZIP file and a gzipped tar archive containing the same files as the gem. Note that Rake uses the zip and tar command-line tools, so if your system doesn provide them (the way a standard Windows installation doesn ), the package task won be able to create these ZIP or tar archives.

The package task recreates a package file only if it doesn already exist, or if youve updated one of your input files since you last built the package. The most common problem youll run into here is that youll decide to stop packaging a certain file. Rake won recognize the change (since the file is gone), and running rake package won do anything. To force a rebuild of your package file(s), run rake repackage.

Problem

Solution

Discussion

See Also