h1. RubyGems GemSpec Reference



h2. Gemspec Reference

h3. Specification Reference

p(((. <em>This page is generated by <tt>hieraki</tt> 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.</em>

p(((. <em>Last generated: 2005-06-01 00:11:33 EDT (Wednesday)</em>

h3. 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:

h3. <a name="toc">Important Attributes</a>

<a href="#name">name</a> .. <a href="#version">version</a> .. <a href="#platform">platform</a> .. <a href="#summary">summary</a> .. <a href="#require_paths">require_paths</a> .. <a href="#files">files</a> .. <a href="#dependencies">dependencies</a>

h3. Alphabetical

* *A* <a href="#authors">authors</a> .. <a href="#autorequire">autorequire</a>
* *B* <a href="#bindir">bindir</a>
* *D* <a href="#default_executable">default_executable</a> .. <a href="#dependencies">dependencies</a> .. <a href="#description">description</a>
* *E* <a href="#email">email</a> .. <a href="#executables">executables</a> .. <a href="#extensions">extensions</a> .. <a href="#extra_rdoc_files">extra_rdoc_files</a>
* *F* <a href="#files">files</a>
* *H* <a href="#has_rdoc">has_rdoc</a> .. <a href="#homepage">homepage</a>
* *N* <a href="#name">name</a>
* *P* <a href="#platform">platform</a>
* *R* <a href="#rdoc_options">rdoc_options</a> .. <a href="#require_paths">require_paths</a> .. <a href="#required_ruby_version">required_ruby_version</a> .. <a href="#requirements">requirements</a> .. <a href="#rubyforge_project">rubyforge_project</a>
* *S* <a href="#summary">summary</a>
* *T* <a href="#test_files">test_files</a>
* *V* <a href="#version">version</a>

h3. Themed


* *Basics:* 
<a href="#name">name</a> .. <a href="#version">version</a> .. <a href="#summary">summary</a> .. <a href="#description">description</a> .. <a href="#platform">platform</a> .. <a href="#required_ruby_version">required_ruby_version</a> .. <a href="#requirements">requirements</a> .. <a href="#dependencies">dependencies</a>

* *Files, Libraries, and Executables:* 
<a href="#files">files</a> .. <a href="#require_paths">require_paths</a> .. <a href="#autorequire">autorequire</a> .. <a href="#bindir">bindir</a> .. <a href="#executables">executables</a> .. <a href="#default_executable">default_executable</a>

* *C compilation:* 
<a href="#extensions">extensions</a>

* *Documentation:* 
<a href="#rdoc_options">rdoc_options</a> .. <a href="#has_rdoc">has_rdoc</a> .. <a href="#extra_rdoc_files">extra_rdoc_files</a>

* *Testing:* 
<a href="#test_files">test_files</a>

* *About:* 
<a href="#authors">authors</a> .. <a href="#email">email</a> .. <a href="#homepage">homepage</a> .. <a href="#rubyforge_project">rubyforge_project</a>

h2. Attribute Survey


----


h3. <a name="authors">authors</a>

<em>Type: String;   <em>Optional</em></em>


h4. Description

The author of the package contained in the gem.


h4. Usage

<pre>
  spec.author = "John Jones"
</pre>

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="autorequire">autorequire</a>

<em>Type: String;   <em>Optional</em>;   default = nil</em>


h4. Description

The file that will be loaded when <tt>require_gem</tt> is called.


h4. Usage

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


h4. Notes

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

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

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="bindir">bindir</a>

<em>Type: String;   <em>Optional</em>;   default = "bin"</em>


h4. Description

The directory containing the application files, if any.


h4. Usage

<pre>
  spec.bindir = 'bin'
</pre>


h4. 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 <tt>bin</tt> directory, hence the name *bindir*.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="date">date</a>

<em>Type: Time;   <em>Required</em>;   default = "Time.now"</em>


h4. Description

The date/time that the gem was created.


h4. Usage

<pre>
  spec.date = File.utime('VERSION')
</pre>


h4. Notes

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

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="default_executable">default_executable</a>

<em>Type: String;   <em>Optional</em>;   default = (see below)</em>


h4. Description

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


h4. Usage

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


h4. 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 <tt>monopoly.gem</tt> (the board game), and run <tt>gem monopoly.gem</tt>, which would run the <tt>monopoly</tt> application. This is not an in-demand feature.

<em>XXX: Is the full path necessary?</em>

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="dependencies">dependencies</a>

<em>Type: Array;   <em>Optional</em>;   default = []</em>


h4. Description

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


h4. Usage

<pre>
  spec.add_dependency('log4r', '>= 1.0.5')
</pre>


h4. Notes

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

See also <a href="#requirements">requirements</a>.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="description">description</a>

<em>Type: String;   <em>Optional</em></em>


h4. Description

Detailed description of the gem.  See also <a href="#summary">summary</a>.


h4. Usage

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


h4. 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.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="email">email</a>

<em>Type: String;   <em>Optional</em></em>


h4. Description

The author's email address.


h4. Usage

<pre>
  spec.email = 'john.jones@example.com'
</pre>

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="executables">executables</a>

<em>Type: Array;   <em>Optional</em></em>


h4. Description

A list of files in the package that are applications.


h4. Usage

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


h4. Notes

For example, the <tt>rake</tt> gem has <tt>rake</tt> as an executable. You don't specify the full path (as in <tt>bin/rake</tt>); all application-style files are expected to be found in <a href="#bindir">bindir</a>.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="extensions">extensions</a>

<em>Type: Array;   <em>Optional</em></em>


h4. Description

The paths to <tt>extconf.rb</tt>-style files used to compile extensions.


h4. Usage

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


h4. 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.

<em>XXX: Any other comments?</em>

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="extra_rdoc_files">extra_rdoc_files</a>

<em>Type: Array;   <em>Optional</em></em>


h4. Description

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


h4. Usage

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


h4. 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.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="files">files</a>

<em>Type: Array;   <em>Optional</em></em>


h4. Description

The list of files to be contained in the gem.


h4. Usage

<pre>
  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" }
</pre>


h4. 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.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="has_rdoc">has_rdoc</a>

<em>Type: boolean;   <em>Optional</em>;   default = false</em>


h4. Description

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


h4. Usage

<pre>
  spec.has_rdoc = true
</pre>


h4. Notes

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

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="homepage">homepage</a>

<em>Type: String;   <em>Optional</em></em>


h4. Description

URL of the project or author.


h4. Usage

<pre>
  spec.hompage = 'http://rake.rubyforge.org'
</pre>

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="name">name</a>

<em>Type: String;   <em>Required</em></em>


h4. Description

The name of the gem.


h4. Usage

<pre>
  spec.name = 'rake'
</pre>


h4. Notes

The name does not include the version number; see <a href="#version">version</a>.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="platform">platform</a>

<em>Type: String;   <em>Required</em>;   default = "Gem::Platform::Ruby"</em>


h4. Description

The target platform for the gem.


h4. Usage

<pre>
  spec.platform = Gem::Platform::Win32
</pre>


h4. 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. <tt>fxruby-1.2.0-win32.gem</tt>.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="rdoc_options">rdoc_options</a>

<em>Type: Array;   <em>Optional</em>;   default = []</em>


h4. Description

Specifies the <tt>rdoc</tt> options to be used when generating API documentation.


h4. Usage

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

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="require_paths">require_paths</a>

<em>Type: Array;   <em>Required</em>;   default = ["lib"]</em>


h4. Description

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


h4. Usage

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


h4. Notes

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

The example above shows that you can use <tt>spec.require_path = '...'</tt> instead of <tt>spec.require_paths = [...]</tt>.  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 <tt>LOAD_PATH</tt>, and thus to resolve <tt>require</tt> calls.  So if code calls <tt>require 'rake/packagetask'</tt>, for example, and the <tt>require_paths</tt> is set to <tt>lib</tt>, then there had better be a file <tt>lib/rake/packagetask.rb</tt>.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="required_ruby_version">required_ruby_version</a>

<em>Type: Gem::Version::Requirement;   <em>Optional</em>;   default = "> 0.0.0"</em>


h4. Description

The version of Ruby required to use the gem.


h4. Usage

<pre>
  # 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'
</pre>


h4. Notes

See the RubyGems wiki for documentation on specifying versions.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="requirements">requirements</a>

<em>Type: Array;   <em>Optional</em>;   default = []</em>


h4. Description

Lists the external (to <nowiki>RubyGems</nowiki>) requirements that must be met for this gem to work.  It's simply information for the user.


h4. Usage

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


h4. Notes

For requirements that can be met by other gems, see <a href="#dependencies">dependencies</a>.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="rubyforge_project">rubyforge_project</a>

<em>Type: String;   <em>Optional</em></em>


h4. Description

The RubyForge project corresponding to the gem.


h4. Usage

<pre>
  spec.rubyforge_project = 'rake'
</pre>


h4. Notes

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

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="rubygems_version">rubygems_version</a>

<em>Type: String;   <em>Optional</em>;   default = "<em>current version of RubyGems</em>"</em>


h4. Description

The version of RubyGems used to create this gem.


h4. Usage

<pre>
  No usage ... it is set automatically when the gem is created.
</pre>

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="specification_version">specification_version</a>

<em>Type: Integer;   <em>Optional</em>;   default = "<em>Revision level of the RubyGems specification this gem conforms to.</em>"</em>


h4. Description

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


h4. Usage

<pre>
  No usage ... it is set automatically when the gem is created.
</pre>

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="summary">summary</a>

<em>Type: String;   <em>Required</em></em>


h4. Description

A short description of the gem.


h4. Usage

<pre>
  spec.summary = 'Ruby based make-like utility.'
</pre>


h4. Notes

The summary is used to describe the gem in lists produced by the <tt>gem</tt> tool.  See also <a href="#description">description</a>, which is less important.

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="test_files">test_files</a>

<em>Type: Array;   <em>Optional</em>;   default = []</em>


h4. Description

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


h4. Usage

<pre>
  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)
</pre>


h4. Notes

Example (1) specifies that all files matching <tt>tc_*.rb</tt> in the <tt>test</tt> 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 <tt>test_file=</tt>, and has the same effect as example (3).

<em>Goto <a href="#toc">Table of Contents</a></em>

----


h3. <a name="version">version</a>

<em>Type: String;   <em>Required</em></em>


h4. Description

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


h4. Usage

<pre>
  spec.version = '0.4.1'
</pre>


h4. Notes

The canonical way to represent versions in RubyGems is with the <tt>Gem::Version</tt> 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.

<em>Goto <a href="#toc">Table of Contents</a></em>