Hieraki recent changes

Daniel Berger: Specification Reference

This page is generated by hieraki rake task in the RubyGems CVS. Any changes to this page will be lost. Contact a member of the RubyGems team if you have suggestions.

Last generated: 2005-06-01 00:11:33 EDT (Wednesday)

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.

C compilation: extensions

Documentation: rdoc_options .. has_rdoc .. extra_rdoc_files

Testing: test_files

About: authors .. email .. homepage .. rubyforge_project

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

Type: String; Optional; default = nil

Description

The file that will be loaded when require_gem is called.

Usage

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

Notes

In the above example, when the user’s code calls require_gem ‘rake’, an implicit require ‘rake’ is called afterwards. It is a shortcut so the user doesn’t have to do what seems to be a redundant require.

Specifying autorequire is optional. If there is no single default file that should be loaded, then it doesn’t make sense to specify it.

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.

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

When the gem is built, the description is re-formatted into a single line with sensible whitespace. This means you can use here-docs with formatting, as demonstrated above, without worrying about the formatting.

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; Optional

Description

The author’s email address.

Usage

  spec.email = 'john.jones@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

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

  No usage ... 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

  No usage ... 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

Jim Weirich: Installing a remote gem

When you run (as root, if appropriate and necessary)

gem install --remote progressbar
# shortcut: gem i -r progressbar

the progressbar gem will be installed on your computer. Notice that you don’t need to specify the version, but you can if you want to. It will default to the last version available.

gem ins -r progressbar-0.0.3

gem ins -r progressbar --version '> 0.0.1'

In both cases, the output is simply:

Attempting remote installation of 'progressbar'
Successfully installed progressbar, version 0.0.3

RubyGems allows you to have multiple versions of a library installed and choose in your code which version you wish to use.

Useful extra options for installation are -gen-rdoc for generating the gem’s RDoc API documentation, and -run-tests to run the gem’s unit tests, if any.

Note too that when you remotely install a gem, it will download and install any specified dependencies. Try installing copland and see that it prompts you to accept log4r as well (if it’s not already installed).

Jim Weirich: Searching remotely installable gems

When you run

  gem query --remote --name-matches doom
  # shortcut: gem q -R -n doom

you will see a detailed list of matching gems on the remote server.

Sample output:

*** REMOTE GEMS ***

ruby-doom (0.8, 0.0.7)
    Ruby-DOOM provides a scripting API for creating DOOM
    maps. It also provides higher-level APIs to make map
    creation easier.

When you run

  gem query --remote --name-matches doom
  # shortcut: gem q -R -n doom

you will see a detailed list of matching gems on the remote server.

Sample output:

*** REMOTE GEMS ***

ruby-doom (0.8, 0.0.7)
    Ruby-DOOM provides a scripting API for creating DOOM
    maps. It also provides higher-level APIs to make map
    creation easier.

Jim Weirich: Installing gems in a non-standard directory.

How do I install gems in a non-standard location, such as my home directory?

You have to redefine the location of the GEM_HOME variable and add the paths to the gem repositories in the RUBYLIB variable before launching the installation into a custom directory.

GEM_HOME should point to $PREFIX/lib/ruby/gems/1.8 if it used with the 1.8 version of ruby.

RUBYLIB should point to the $PREFIX/lib/ruby and $PREFIX/lib/site_ruby/1.8

Here is a shell script that runs in the rubygems distribution directory to install into /home/user :

PREFIX=$HOME
export GEM_HOME=$PREFIX/lib/ruby/gems/1.8 
export RUBYLIB=$PREFIX/lib/ruby:$PREFIX/lib/site_ruby/1.8
ruby setup.rb all --prefix=$PREFIX

You may add GEM_HOME and RUBYLIB into your ~/.profile file to automatically load on login.

Jim Weirich: Installing gems in a non-standard directory.

How do I install gems in a non-standard location, such as my home directory?

You have to redefine the location of the GEM_HOME variable and add the paths to the gem repositories in the RUBYLIB variable before launching the installation into a custom directory.

GEM_HOME should point to $PREFIX/lib/ruby/gems/1.8 if it used with the 1.8 version of ruby.

RUBYLIB should point to the $PREFIX/lib/ruby and $PREFIX/lib/site_ruby/1.8

Here is a shell script that runs in the rubygems distribution directory to install into /home/user :

PREFIX=/home/user
export GEM_HOME=$PREFIX/lib/ruby/gems/1.8 
export RUBYLIB=$PREFIX/lib/ruby:PREFIX/lib/site_ruby/1.8
ruby setup.rb all --prefix=$PREFIX

You may add GEM_HOME and RUBYLIB into your ~/.profile file to automatically load on login.

Jim Weirich: Q: How do I install gems in my home directory?

A: You have to redefine the location of the GEM_HOME variable and add the paths to the gem repositories in the RUBYLIB variable before launching the installation into a custom directory.

GEM_HOME should point to $PREFIX/lib/ruby/gems/1.8 if it used with the 1.8 version of ruby.

RUBYLIB should point to the $PREFIX/lib/ruby and $PREFIX/lib/site_ruby/1.8

Here is a shell script that runs in the rubygems distribution directory to install into /home/user :

PREFIX=/home/user
export GEM_HOME=$PREFIX/lib/ruby/gems/1.8 
export RUBYLIB=$PREFIX/lib/ruby:PREFIX/lib/site_ruby/1.8
ruby setup.rb all --prefix=$PREFIX

You may add GEM_HOME and RUBYLIB into your ~/.profile file to automatically load on login.

Jim Weirich: Q1

Chad Fowler: Using a gem in your code

Here we demonstrate the use of the progressbar gem. This library may use terminal features that are not available in your system.

If you wish, enter the following code into a file and run it. (Note that you must require the rubygems library before executing this code, as detailed in chapter 3 of this manual.)

require 'progressbar'

bar = ProgressBar.new("Example progress", 50)
total = 0
until total >= 50
  sleep(rand(2)/2.0)
  increment = (rand(6) + 3)
  bar.inc(increment)
  total += increment
end

Here is a “screenshot” of the partially complete progress bar.

Example progr:  29% |ooooooooooo                             | ETA:  00:00:04

The first line of the program requires the progressbar library file. RubyGems will look for the progressbar.rb file in the standard library locations. If not found, it will look through its gem repository for a gem that contains progressbar.rb. If a gem is used, RubyGems attempts to use the latest installed version by default.

Note that the program was able to use the latest available installed gem by default without any explicit action in the code. The developer may develop a library without worrying about using RubyGems.

However, to run the code, the environment does need to be “gem enabled”. See Setting Up the RubyGems Environment for details on how to make this happen.

Jim Weirich: Why does require return false when loading a file from a gem?

Require returns false when loading a file from a gem. Usually require will return true when it has loaded correctly. What’s wrong?

Answer

Nothing. Well, something. But nothing you need to worry about.

A false return from the require method does not indicate an error. It just means that the file has already been loaded.

RubyGems has a feature that allows a file to be automatically loaded when a gem is activated (i.e. selected). When you require a file that is in an inactive gem, the RubyGems software will activate that gem for you. During that activation, any autoloaded files will be loaded for you.

So, by the time your require statement actually does the work of loading the file, it has already been autoloaded via the gem activation, and therefore it returns false.

As we said, it is not a problem, but it sure is confusing to folks doing requires in an irb session. Future versions of RubyGems will correct this behavior.

Jim Weirich: Why does require return false when loading a file from a gem?

Require returns false when loading a file from a gem. Usually require will return true when its loaded correctly. What’s wrong?

Answer

Nothing. Well, something. But nothing you need to worry about.

A false return from the require method does not indicate an error. It means that the file is already loaded. Proabably the file was listed as an auto-required file in the gem, so when the gem was activated, the file was already loaded. So when you explicitly require the file, the file has already been loaded, so require returns false.

I repeat, there is nothing wrong.

The only time this causes concern is when someone requires the file in an irb session and notices the return type.

However, the next version of RubyGems will correct this problem so that newcomers wont be surprised by the result.

Jim Weirich: Why does require return false when loading a file from a gem?

Require returns false when loading a file from a gem. Usually requrie will return true when its loaded correctly. What’s wrong?

Answer

Nothing. Well, something. But nothing you need to worry about.

I repeat, there is nothing wrong.

The only time this causes concern is when someone requires the file in an irb session and notices the return type.

However, the next version of RubyGems will correct this problem so that newcomers wont be surprised by the result.

Jim Weirich: Why does returns false when loading a file from a gem?

Require returns false when loading a file from a gem. Usually requrie will return true when its loaded correctly. What’s wrong?

Answer

Nothing. Well, something. But nothing you need to worry about.

I repeat, there is nothing wrong.

The only time this causes concern is when someone requires the file in an irb session and notices the return type.

However, the next version of RubyGems will correct this problem so that newcomers wont be surprised by the result.

Jim Weirich: `gemlock` script

(new in version 0.9.0)

The gemlock script will generate a series of require_gem commands that will lock down an application or library to a particular version of their dependent gems.

For example, if you wish to lock down a particular version of the Rails library, use:

  $ gemlock rails-1.0.0
  require "rubygems" 
  require_gem 'rails', '= 1.0.0'
  require_gem 'rake', '= 0.7.0.1'
  require_gem 'activesupport', '= 1.2.5'
  require_gem 'activerecord', '= 1.13.2'
  require_gem 'actionpack', '= 1.11.2'
  require_gem 'actionmailer', '= 1.1.5'
  require_gem 'actionwebservice', '= 1.0.0'

gemlock will find all the direct and indirect gems required by rails-1.0.0 and specify the most recent, currently installed version of those gems. The output should be place in the application (or library) will it will be run before any other require statement in the program.

If your application depends on more than one gem, just list all the gems in the command line and gemlock will display the locking commands for all of them.

Usage

  Usage: bin/gemlock [options] GEM_NAME-VERSION...

  Where options are:
    -v, --verbose                    Verbose output
    -s, --[no-]strict                Fail if unable to satisfy a dependency
    -h, --help                       Show this message
    -V, --version                    Show version

Jim Weirich: `gemlock` script

(new in version 0.9.0)

The gemlock script will generate a series of require_gem commands that will lock down an application or library to a particular version of their dependent gems.

For example, if you wish to lock down a particular version of the Rails library, use:

$ gemlock rails-1.0.0
require "rubygems" 
require_gem 'rails', '= 1.0.0'
require_gem 'rake', '= 0.7.0.1'
require_gem 'activesupport', '= 1.2.5'
require_gem 'activerecord', '= 1.13.2'
require_gem 'actionpack', '= 1.11.2'
require_gem 'actionmailer', '= 1.1.5'
require_gem 'actionwebservice', '= 1.0.0'

If your application depends on more than one gem, just list all the gems in the command line and gemlock will display the locking commands for all of them.

Usage

Usage: bin/gemlock [options] GEM_NAME-VERSION...

Where options are:
  -v, --verbose                    Verbose output
  s, -[no-]strict                Fail if unable to satisfy a dependency
  -h, --help                       Show this message
  -V, --version                    Show version

Jim Weirich: `gemlock` script

The gemlock script will generate a series of require_gem commands that will lock down an application or library to a particular version of their dependent gems.

For example, if you wish to lock down a particular version of the Rails library, use:

$ gemlock rails-1.0.0
require "rubygems" 
require_gem 'rails', '= 1.0.0'
require_gem 'rake', '= 0.7.0.1'
require_gem 'activesupport', '= 1.2.5'
require_gem 'activerecord', '= 1.13.2'
require_gem 'actionpack', '= 1.11.2'
require_gem 'actionmailer', '= 1.1.5'
require_gem 'actionwebservice', '= 1.0.0'

If your application depends on more than one gem, just list all the gems in the command line and gemlock will display the locking commands for all of them.

Usage

Jim Weirich: `gemlock` script

The gemlock script will generate a series of require_gem commands that will lock down an application or library to a particular version of their dependent gems.

Jim Weirich: No such file to load -- rubygems

When I run the gem command, I get the following error message:

 ruby: No such file to load -- rubygems (LoadError)

What’s wrong?

Answer

It looks like executing copy of Ruby does not have the RubyGems library installed. RubyGems was probably installed at one time (because the gem command is recognized), but it may have been installed on a different installation of Ruby than the one you are currently running.

Things to check

Check that the installation of Ruby that is running is the same one that has RubyGems installed. On a unix system, the which command (or type command) will help figure this out.

Verify that the currently running installation of Ruby does indeed have the RubyGems library installed. You should find a “rubygems.rb” file in the site_ruby/1.8 directory of the Ruby installation.

These mixup can easily happen after installing a new instance of Ruby, but the old instance preceeds the new one in the PATH list.

Jim Weirich: No such file to load -- rubygems

When I run the gem command, I get the following error message: ruby:

No such file to load -- rubygems (LoadError)

What’s wrong?

Answer

Things to check

Check that the installation of Ruby that is running is the same one that has RubyGems installed. On a unix system, the which command (or type command) will help figure this out.

Verify that the currently running installation of Ruby does indeed have the RubyGems library installed. You should find a “rubygems.rb” file in the site_ruby/1.8 directory of the Ruby installation.

These mixup can easily happen after installing a new instance of Ruby, but the old instance preceeds the new one in the PATH list.

Jim Weirich: No such file to load -- rubygems

When I run the gem command, I get the following error message: ruby:

No such file to load -- rubygems (LoadError)

What’s wrong?

Answer

Jim Weirich: RubyGems hangs while updating the source index.

I have a problem with RubyGems. It doesn’t matter what I try to install with, it freezez.

Particulary I tried to execute:

gem install rails --include-dependencies

but the command freezez at the following message:

"Updating Gem source index for: http://gems.rubyforge.org"

Answer

[I lost my internet connection while composing the answer to this question. Unfortunately, I now no longer recall what I intended to write. The answer (or at least part of the answer) is buried deep in the RubyGems mail archive. I’ll try to update this after a bit of research. Sorry for leaving this question hanging.]

Hieraki recent changes

Daniel Berger: Specification Reference

Introduction

Alphabetical

Themed

Attribute Survey

Description

Usage

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Description

Usage

Description

Usage

Notes

Description

Usage

Notes

Description

Usage

Notes

Jim Weirich: Installing a remote gem

Jim Weirich: Searching remotely installable gems

Jim Weirich: `gemlock` script

Jim Weirich: `gemlock` script

Jim Weirich: `gemlock` script

Jim Weirich: `gemlock` script