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)
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:
name .. version .. platform .. summary .. require_paths .. files .. dependencies
Type: String; Optional
The author of the package contained in the gem.
spec.author = "John Jones"
Goto Table of Contents
Type: String; Optional; default = nil
The file that will be loaded when require_gem is called.
spec.files = ['lib/rake.rb", "lib/rake/**/*.rb", ...] spec.autorequire = 'rake'
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
Type: String; Optional; default = “bin”
The directory containing the application files, if any.
spec.bindir = 'bin'
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
Type: Time; Required; default = “Time.now”
The date/time that the gem was created.
spec.date = File.utime('VERSION')
It’s generally sufficient to leave it to the default.
Goto Table of Contents
Type: String; Optional; default = (see below)
Of all the application files in the package, the default executable is the one that can be run directly through the gem.
spec.executables = ['bin/foo', 'bin/bar'] spec.default_executable = 'bin/bar'
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
Type: Array; Optional; default = []
Lists the gems that must be installed for this gem to work.
spec.add_dependency('log4r', '>= 1.0.5')
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
Type: String; Optional
Detailed description of the gem. See also summary.
spec.description = <<-EOF
Rake is a Make-like program implemented in Ruby. Tasks and
dependencies are specified in standard Ruby syntax.
EOF
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
Type: String; Optional
The author’s email address.
spec.email = 'john.jones@example.com'
Goto Table of Contents
Type: Array; Optional
A list of files in the package that are applications.
# XXX: is this correct? spec.executables << 'rake'
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
Type: Array; Optional
The paths to extconf.rb-style files used to compile extensions.
spec.extensions << 'ext/rmagic/extconf.rb'
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
Type: Array; Optional
A list of extra files that will be used by RDoc to generate the documentation.
spec.extra_rdoc_files = ['README', 'doc/user-guide.txt']
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
Type: Array; Optional
The list of files to be contained in the gem.
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" }
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
Type: boolean; Optional; default = false
Indicates whether the code in the gem has been commented with RDoc in mind.
spec.has_rdoc = true
This attribute has an advisory role only. Any gem can be submitted for RDoc processing.
Goto Table of Contents
Type: String; Optional
URL of the project or author.
spec.hompage = 'http://rake.rubyforge.org'
Goto Table of Contents
Type: String; Required
The name of the gem.
spec.name = 'rake'
The name does not include the version number; see version.
Goto Table of Contents
Type: String; Required; default = “Gem::Platform::Ruby”
The target platform for the gem.
spec.platform = Gem::Platform::Win32
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
Type: Array; Optional; default = []
Specifies the rdoc options to be used when generating API documentation.
spec.rdoc_options << '--title' << 'Rake -- Ruby Make' <<
'--main' << 'README' <<
'--line-numbers'
Goto Table of Contents
Type: Array; Required; default = [“lib”]
List of ’’require’’ paths from the root of the gem.
# If all library files are in the root directory... spec.require_path = '.' # If you have 'lib' and 'ext' directories... spec.require_paths << 'ext'
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
Type: Gem::Version::Requirement; Optional; default = ”> 0.0.0”
The version of Ruby required to use the gem.
# 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'
See the RubyGems wiki for documentation on specifying versions.
Goto Table of Contents
Type: Array; Optional; default = []
Lists the external (to
spec.requirements << 'libmagick, v6.0 or greater' spec.requirements << 'A powerful graphics card'
For requirements that can be met by other gems, see dependencies.
Goto Table of Contents
Type: String; Optional
The RubyForge project corresponding to the gem.
spec.rubyforge_project = 'rake'
Obviously, if your gem doesn’t have a Rubyforge project, leave this setting alone.
Goto Table of Contents
Type: String; Optional; default = “current version of RubyGems“
The version of RubyGems used to create this gem.
No usage ... it is set automatically when the gem is created.
Goto Table of Contents
Type: Integer; Optional; default = “Revision level of the RubyGems specification this gem conforms to.“
The revision level of the GemSpec specification that this gem conforms to.
No usage ... it is set automatically when the gem is created.
Goto Table of Contents
Type: String; Required
A short description of the gem.
spec.summary = 'Ruby based make-like utility.'
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
Type: Array; Optional; default = []
A collection of unit test files. They will be loaded as unit tests when the user requests a gem to be unit tested.
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)
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
Type: String; Required
The version of the gem. See RationalVersioningPolicy for some advice on specifying the version number for your gem.
spec.version = '0.4.1'
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