1. Gem::Specification Reference

1.1 Specification Reference

For the most up-to-date information, see Gem::Specification in the RubyGems API documention

Introduction

In order to create a gem, you need to define a gem specification, commonly
called a “gemspec”.

A gemspec consists of several attributes. Some of these are required;
most of them are optional. The main body of this document is an alphabetical
list of gemspec attributes, each with a description, example usage, notes, and
more.

See also:

Important Attributes

name .. version .. platform .. summary .. require_paths .. files .. dependencies

Alphabetical

Themed

Attribute Survey

authors

Type: String or Array; Optional

Description

The author or authors of the package contained in the gem.

Usage

  spec.author = 'John Jones'
  spec.authors = ['John Jones', 'Mary Smith']

Goto Table of Contents

autorequire (Deprecated)

Type: String; Optional; default = nil

Description

The file that will be loaded when the gem method is called.

Usage

  spec.files = ['lib/rake.rb", "lib/rake/**/*.rb", ...]
  spec.autorequire = 'rake'

Notes

This method is deprecated and should no longer be used. It is an artifact of older versions of Rubygems that used require_gem.

As of Rubygems 1.0, you can simply use require without any special handling so long as rubygems is required first, or loaded automatically via the RUBYOPT environment variable or the -r command line option.

The only exception to this rule are libraries from the Ruby standard library that are being independently maintained as third party gems, e.g. Test::Unit or RDoc. In those rare cases, you must call the gem method first, followed by a require.

Goto Table of Contents

bindir

Type: String; Optional; default = “bin”

Description

The directory containing the application files, if any.

Usage

  spec.bindir = 'bin'

Notes

An “application file” is a file that is intended to be run from the command line. If your package contains such files, they will typically be placed in a bin directory, hence the name bindir.

Goto Table of Contents

date

Type: Time; Required; default = “Time.now”

Description

The date/time that the gem was created.

Usage

  spec.date = File.utime('VERSION')

Notes

It’s generally sufficient to leave it to the default.

Goto Table of Contents

default_executable

Type: String; Optional; default = (see below)

Description

Of all the application files in the package, the default executable is the one that can be run directly through the gem.

Usage

  spec.executables = ['bin/foo', 'bin/bar']
  spec.default_executable = 'bin/bar'

Notes

If you only specify one application file in executables, that file becomes the default executable. Therefore, you only need to specify this value if you have more than one application file.

The notion of running applications directly through a gem is not well supported at the moment. The idea is that you can download a gem, say monopoly.gem (the board game), and run gem monopoly.gem, which would run the monopoly application. This is not an in-demand feature.

XXX: Is the full path necessary?

Goto Table of Contents

dependencies

Type: Array; Optional; default = []

Description

Lists the gems that must be installed for this gem to work.

Usage

  spec.add_dependency('log4r', '>= 1.0.5')

Notes

When installing a gem with gem install …, its dependencies will be checked. If they are not installed, gem will offer to install them.

See also requirements.

Goto Table of Contents

development dependencies

Type: Array; Optional; default = []

Description

Gems that are used for development purposes only.

Usage

  spec.add_development_dependency('rspec')

Notes

Development dependencies are not installed by default, and are not activated when the gem is.

Goto Table of Contents

description

Type: String; Optional

Description

Detailed description of the gem. See also summary.

Usage

  spec.description = <<-EOF
    Rake is a Make-like program implemented in Ruby. Tasks and
    dependencies are specified in standard Ruby syntax.
  EOF

Notes

As of Rubygems 1.3.2 there is no longer any automatic formatting of the description. Versions prior to this reformatted the description into a single line.

The description should be more detailed than the summary. You might consider copying all or part of your project’s README into this field.

Goto Table of Contents

email

Type: String or Array; Optional

Description

The author’s email address.

Usage

  spec.email = 'john.jones@example.com'
  spec.email = ['jack@example.com', 'jill@example.com']

Goto Table of Contents

executables

Type: Array; Optional

Description

A list of files in the package that are applications.

Usage

  # XXX: is this correct?
  spec.executables << 'rake'

Notes

For example, the rake gem has rake as an executable. You don’t specify the full path (as in bin/rake); all application-style files are expected to be found in bindir.

Goto Table of Contents

extensions

Type: Array; Optional

Description

The paths to extconf.rb-style files used to compile extensions.

Usage

  spec.extensions << 'ext/rmagic/extconf.rb'

Notes

These files will be run when the gem is installed, causing the C (or whatever) code to be compiled on the user’s machine.

XXX: Any other comments?

Goto Table of Contents

extra_rdoc_files

Type: Array; Optional

Description

A list of extra files that will be used by RDoc to generate the documentation.

Usage

  spec.extra_rdoc_files = ['README', 'doc/user-guide.txt']

Notes

When the user elects to generate the RDoc documentation for a gem (typically at install time), all the library files are sent to RDoc for processing. This option allows you to have some non-code files included for a more complete set of documentation.

Goto Table of Contents

files

Type: Array; Optional

Description

The list of files to be contained in the gem.

Usage

  require 'rake'
  spec.files = FileList['lib/**/*.rb', 'bin/*', '[A-Z]*', 'test/**/*'].to_a
  
  # or without Rake...
  spec.files = Dir['lib/**/*.rb'] + Dir['bin/*']
  spec.files += Dir['[A-Z]*'] + Dir['test/**/*']
  spec.files.reject! { |fn| fn.include? "CVS" }

Notes

You don’t need to use Rake, obviously, but it does make it much easier to specify files, as it automatically excludes CVS files, backups, etc.

Goto Table of Contents

has_rdoc

Type: boolean; Optional; default = false

Description

Indicates whether the code in the gem has been commented with RDoc in mind.

Usage

  spec.has_rdoc = true

Notes

This attribute has an advisory role only. Any gem can be submitted for RDoc processing.

Goto Table of Contents

homepage

Type: String; Optional

Description

URL of the project or author.

Usage

  spec.hompage = 'http://rake.rubyforge.org'

Goto Table of Contents

license

Type: String; Optional

Description

The license(s) for the library.

Usage

  # single license
  spec.license = 'MIT'

  # multiple licenses
  spec.licenses = ['MIT', 'GPL-2']

Notes

Each license must be a short name, no more than 64 characters.

Goto Table of Contents

name

Type: String; Required

Description

The name of the gem.

Usage

  spec.name = 'rake'

Notes

The name does not include the version number; see version.

Goto Table of Contents

platform

Type: String; Required; default = “Gem::Platform::Ruby”

Description

The target platform for the gem.

Usage

  spec.platform = Gem::Platform::Win32

Notes

Most gems contain pure Ruby code; they should simply leave the default value in place. Some gems contain C (or other) code to be compiled into a Ruby “extension”. The should leave the default value in place unless their code will only compile on a certain type of system. Some gems consist of pre-compiled code (“binary gems”). It’s especially important that they set the platform attribute appropriately. A shortcut is to set the platform to Gem::Platform::CURRENT, which will cause the gem builder to set the platform to the appropriate value for the system on which the build is being performed.

If this attribute is set to a non-default value, it will be included in the filename of the gem when it is built, e.g. fxruby-1.2.0-win32.gem.

Goto Table of Contents

rdoc_options

Type: Array; Optional; default = []

Description

Specifies the rdoc options to be used when generating API documentation.

Usage

  spec.rdoc_options << '--title' << 'Rake -- Ruby Make' <<
                       '--main' << 'README' <<
                       '--line-numbers'

Goto Table of Contents

require_paths

Type: Array; Required; default = [“lib”]

Description

List of ’’require’’ paths from the root of the gem.

Usage

  # If all library files are in the root directory...
  spec.require_path = '.'
  
  # If you have 'lib' and 'ext' directories...
  spec.require_paths << 'ext'

Notes

The default is sufficient in most cases, as Ruby packages tend to be structured so that library code is found under the lib directory.

The example above shows that you can use spec.require_path = ‘…’ instead of spec.require_paths = […]. This is a shortcut, acknowledging that nearly all gems will have only one require path element.

Be careful about interpreting this attribute, however. It is used to modify the LOAD_PATH, and thus to resolve require calls. So if code calls require ‘rake/packagetask’, for example, and the require_paths is set to lib, then there had better be a file lib/rake/packagetask.rb.

Goto Table of Contents

required_ruby_version

Type: Gem::Version::Requirement; Optional; default = “> 0.0.0”

Description

The version of Ruby required to use the gem.

Usage

  # If it will work with 1.6.8 or greater...
  spec.required_ruby_version = '>= 1.6.8'
  
  # ...but not with 1.7/1.8...
  spec.required_ruby_version = '~> 1.6.8'
  
  # The typical case these days...
  spec.required_ruby_version = '>= 1.8.1'

Notes

See the RubyGems wiki for documentation on specifying versions.

Goto Table of Contents

requirements

Type: Array; Optional; default = []

Description

Lists the external (to RubyGems) requirements that must be met for this gem to work. It’s simply information for the user.

Usage

  spec.requirements << 'libmagick, v6.0 or greater'
  spec.requirements << 'A powerful graphics card'

Notes

For requirements that can be met by other gems, see dependencies.

Goto Table of Contents

rubyforge_project

Type: String; Optional

Description

The RubyForge project corresponding to the gem.

Usage

  spec.rubyforge_project = 'rake'

Notes

Obviously, if your gem doesn’t have a Rubyforge project, leave this setting alone.

Goto Table of Contents

rubygems_version

Type: String; Optional; default = “current version of RubyGems”

Description

The version of RubyGems used to create this gem.

Usage

  DO NOT USE. It is set automatically when the gem is created.

Goto Table of Contents

specification_version

Type: Integer; Optional; default = “Revision level of the RubyGems specification this gem conforms to.”

Description

The revision level of the GemSpec specification that this gem conforms to.

Usage

  DO NOT USE. It is set automatically when the gem is created.

Goto Table of Contents

summary

Type: String; Required

Description

A short description of the gem.

Usage

  spec.summary = 'Ruby based make-like utility.'

Notes

The summary is used to describe the gem in lists produced by the gem tool. See also description, which is less important.

Goto Table of Contents

test_files

Type: Array; Optional; default = []

Description

A collection of unit test files. They will be loaded as unit tests when the user requests a gem to be unit tested.

Usage

  spec.test_files = Dir.glob('test/tc_*.rb')     # (1)
  spec.test_file  = 'tests/test-suite.rb'        # (2)
  spec.test_files = ['tests/test-suite.rb']      # (3)

Notes

Example (1) specifies that all files matching tc_*.rb in the test directory are unit test files.

Example (2) shows that you can specify a test suite instead, which presumably loads individual test cases. This uses the shortcut method test_file=, and has the same effect as example (3).

Goto Table of Contents

version

Type: String; Required

Description

The version of the gem. See RationalVersioningPolicy for some advice on specifying the version number for your gem.

Usage

  spec.version = '0.4.1'

Notes

The canonical way to represent versions in RubyGems is with the Gem::Version class. But the practical way to specify it in a gemspec is with a String.

The version string must consist purely of numbers and periods.

Goto Table of Contents