| layout | title | previous | next |
|---|---|---|---|
default |
Specification Reference |
/command-reference |
/rubygems-org-api |
{% include big.html %}
The Specification class contains the metadata for a Gem. Typically defined in a .gemspec file or a Rakefile, and looks like this:
Gem::Specification.new do |s| s.name = 'example' s.version = '0.1.0' s.summary = "This is an example!" s.description = "Much longer explanation of the example!" s.authors = ["Ruby Coder"] s.email = 'rubycoder@example.com' s.files = ["lib/example.rb"] s.homepage = 'http://rubygems.org/gems/example' end
Files included in this gem. You cannot append to this accessor, you must assign to it.
Only add files you can require to this list, not directories, etc.
Directories are automatically stripped from this list when building a gem, other non-files cause an error.
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" }
This gem’s name.
Usage:
spec.name = 'rake'
The platform this gem runs on.
This is usually Gem::Platform::RUBY or Gem::Platform::CURRENT.
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.
Usage:
spec.platform = Gem::Platform::Win32
Paths in the gem to add to $LOAD_PATH when this gem is activated.
Usage:
# If all library files are in the root directory... spec.require_path = '.' # If you have 'lib' and 'ext' directories... spec.require_paths << 'ext'
The version of RubyGems used to create this gem.
Do not set this, it is set automatically when the gem is packaged.
A short summary of this gem’s description. Displayed in `gem list -d`.
The description should be more detailed than the summary.
Usage:
spec.summary = "This is a small summary of my gem"
This gem’s version.
The version string can contain numbers and periods, such as 1.0.0. A gem is a ‘prerelease’ gem if the version has a letter in it, such as 1.0.0.pre.
Usage:
spec.version = '0.4.1'
Adds a development dependency named gem with requirements to this gem.
Usage:
spec.add_development_dependency 'example', '~> 1.1', '>= 1.1.4'
Development dependencies aren’t installed by default and aren’t activated when a gem is required.
Adds a runtime dependency named gem with requirements to this gem.
Usage:
spec.add_runtime_dependency 'example', '~> 1.1', '>= 1.1.4'
Singular writer for authors
Usage:
spec.author = 'John Jones'
Sets the list of authors, ensuring it is an array.
Usage:
spec.authors = ['John Jones', 'Mary Smith']
The path in the gem for executable scripts. Usually ‘bin’
Usage:
spec.bindir = 'bin'
The certificate chain used to sign this gem. See Gem::Security for details.
A long description of this gem
The description should be more detailed than the summary.
Usage:
spec.description = <<-EOF Rake is a Make-like program implemented in Ruby. Tasks and dependencies are specified in standard Ruby syntax. EOF
A contact email for this gem
Usage:
spec.email = 'john.jones@example.com' spec.email = ['jack@example.com', 'jill@example.com']
Executables included in the gem.
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.
Usage:
spec.executables << 'rake'
Extensions to build when installing the gem, specifically the paths to extconf.rb-style files used to compile extensions.
These files will be run when the gem is installed, causing the C (or whatever) code to be compiled on the user’s machine.
Usage:
spec.extensions << 'ext/rmagic/extconf.rb'
Extra files to add to RDoc such as README or doc/examples.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.
Usage:
spec.extra_rdoc_files = ['README', 'doc/user-guide.txt']
The URL of this gem’s home page
Usage:
spec.homepage = 'http://rake.rubyforge.org'
The license for this gem.
The license must be a short name, no more than 64 characters.
This should just be the name of your license, make to include the full text of the license inside of the gem when you build it.
Usage:
spec.license = 'MIT'
The license(s) for the library.
Each license must be a short name, no more than 64 characters.
This should just be the name of your license, make to include the full text of the license inside of the gem when you build it.
Usage:
spec.licenses = ['MIT', 'GPL-2']
A message that gets displayed after the gem is installed.
Usage:
spec.post_install_message = "Thanks for installing!"
Specifies the rdoc options to be used when generating API documentation.
Usage:
spec.rdoc_options << '--title' << 'Rake -- Ruby Make' << '--main' << 'README' << '--line-numbers'
The version of ruby required by this gem
Usage:
# If it will work with 1.8.6 or greater... spec.required_ruby_version = '>= 1.8.6' # Hopefully by now: spec.required_ruby_version = '>= 1.9.2'
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' spec.requirements << 'A good graphics card'
The key used to sign this gem. See Gem::Security for details.
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')
spec.test_files = ['tests/test-suite.rb']