Class Gem::Specification
In: lib/rubygems/specification.rb
Parent: Object

The Specification class contains the metadata for a Gem. Typically defined in a .gemspec file or a Rakefile, and looks like this:

  spec = Gem::Specification.new do |s|
    s.name = 'example'
    s.version = '1.0'
    s.summary = 'Example gem specification'
    ...
  end

For a great way to package gems, use Hoe.

Methods

_dump   _load   activate   activate_dependencies   add_bindir   add_dependency   add_development_dependency   add_runtime_dependency   add_self_to_load_path   add_spec   add_specs   all   all=   all_names   array_attributes   attribute_names   author   author=   authors   authors=   base_dir   bin_dir   bin_file   cache_dir   cache_file   cache_gem   conflicts   contains_requirable_file?   date   date=   default_executable   default_value   dependencies   dependent_gems   dependent_specs   description=   development_dependencies   dirs   dirs=   doc_dir   each   executable   executable=   executables   executables=   extensions   extensions=   extra_rdoc_files   extra_rdoc_files=   file_name   files   files=   find_all_by_name   find_by_name   find_by_path   find_in_unresolved   find_in_unresolved_tree   for_cache   from_yaml   full_gem_path   full_name   gem_dir   gems_dir   has_rdoc   has_rdoc=   has_rdoc?   has_unit_tests?   initialize_copy   installation_path   latest_specs   lib_dirs_glob   lib_files   license   license=   licenses   licenses=   load   loaded_from=   mark_version   matches_for_glob   new   non_nil_attributes   normalize   normalize_yaml_input   outdated   platform   platform=   raise_if_conflicts   rdoc_options   rdoc_options=   remove_spec   require_path   require_path=   required_attribute?   required_attributes   required_ruby_version=   required_rubygems_version=   requirements   requirements=   reset   ri_dir   runtime_dependencies   satisfies_requirement?   sort_obj   spec_dir   spec_file   spec_name   summary=   test_file   test_file=   test_files   test_files=   to_ruby   to_ruby_for_cache   traverse   validate   version=  

Constants

NONEXISTENT_SPECIFICATION_VERSION = -1   The the version number of a specification that does not specify one (i.e. RubyGems 0.7 or earlier).
CURRENT_SPECIFICATION_VERSION = 3   The specification version applied to any new Specification instances created. This should be bumped whenever something in the spec format changes.

Specification Version History:

  spec   ruby
   ver    ver yyyy-mm-dd description
    -1 <0.8.0            pre-spec-version-history
     1  0.8.0 2004-08-01 Deprecated "test_suite_file" for "test_files"
                         "test_file=x" is a shortcut for "test_files=[x]"
     2  0.9.5 2007-10-01 Added "required_rubygems_version"
                         Now forward-compatible with future versions
     3  1.3.2 2009-01-03 Added Fixnum validation to specification_version

Required gemspec attributes

Attributes

name  [RW]  This gem‘s name
require_paths  [RW]  Paths in the gem to add to $LOAD_PATH when this gem is activated.

The default [‘lib’] is typically sufficient.

rubygems_version  [RW]  The version of RubyGems used to create this gem.

Do not set this, it is set automatically when the gem is packaged.

specification_version  [RW]  The Gem::Specification version of this gemspec.

Do not set this, it is set automatically when the gem is packaged.

summary  [R]  A short summary of this gem‘s description. Displayed in `gem list -d`.

The description should be more detailed than the summary. For example, you might wish to copy the entire README into the description.

version  [R]  This gem‘s version

Optional gemspec attributes

External Aliases

loaded -> loaded?
activated -> activated?

Attributes

activated  [RW]  True when this gemspec has been activated. This attribute is not persisted.
autorequire  [RW]  Autorequire was used by old RubyGems to automatically require a file.

Deprecated: It is neither supported nor functional.

bindir  [RW]  The path in the gem for executable scripts. Usually ‘bin‘
cert_chain  [RW]  The certificate chain used to sign this gem. See Gem::Security for details.
default_executable  [W]  Sets the default executable for this gem.

Deprecated: You must now specify the executable name to Gem.bin_path.

description  [R]  A long description of this gem
email  [RW]  A contact email for this gem

If you are providing multiple authors and multiple emails they should be in the same order such that:

  Hash[*spec.authors.zip(spec.emails).flatten]

Gives a hash of author name to email address.

homepage  [RW]  The URL of this gem‘s home page
loaded_from  [R]  Path this gemspec was loaded from. This attribute is not persisted.
post_install_message  [RW]  A message that gets displayed after the gem is installed
required_ruby_version  [R]  The version of ruby required by this gem
required_rubygems_version  [R]  The RubyGems version required by this gem
rubyforge_project  [RW]  The rubyforge project this gem lives under. i.e. RubyGems’ rubyforge_project is "rubygems".
signing_key  [RW]  The key used to sign this gem. See Gem::Security for details.

Public Class methods

Load custom marshal format, re-initializing defaults as needed

Adds spec to the known specifications, keeping the collection properly sorted.

Adds multiple specs to the known specifications.

Returns all specifications. This method is discouraged from use. You probably want to use one of the Enumerable methods instead.

Sets the known specs to specs. Not guaranteed to work for you in the future. Use at your own risk. Caveat emptor. Doomy doom doom. Etc etc.

Return full names of all specs in sorted order.

Return the list of all array-oriented instance variables.

Return the list of all instance variables.

Return the directories that Specification uses to find specs.

Set the directories that Specification uses to find specs. Setting this resets the list of known specs.

Enumerate every known spec. See ::dirs= and ::add_spec to set the list of specs.

Returns every spec that matches name and optional requirements.

Find the best specification matching a name and requirements. Raises if the dependency doesn‘t resolve to a valid specification.

Return the best specification that contains the file matching path.

Return currently unresolved specs that contain the file matching path.

Search through all unresolved deps and sub-dependencies and return specs that contain the file matching path.

Special loader for YAML files. When a Specification object is loaded from a YAML file, it bypasses the normal Ruby object initialization routine (initialize). This method makes up for that and deals with gems of different ages.

input can be anything that YAML.load() accepts: String or IO.

Return the latest specs, optionally including prerelease specs if prerelease is true.

Loads Ruby format gemspec from file.

Specification constructor. Assigns the default values to the attributes and yields itself for further initialization. Optionally takes name and version.

Specification attributes that must be non-nil

Make sure the YAML specification is properly formatted with dashes

Return a list of all outdated specifications. This method is HEAVY as it must go fetch specifications from the server.

Removes spec from the known specs.

Is name a required attribute?

Required specification attributes

Reset the list of known specs, running pre and post reset hooks registered in Gem.

Public Instance methods

Dump only crucial instance variables.

Activate this spec, registering it as a loaded spec and adding it‘s lib paths to $LOAD_PATH. Returns true if the spec was activated, false if it was previously activated. Freaks out if there are conflicts upon activation.

Activate all unambiguously resolved runtime dependencies of this spec. Add any ambigous dependencies to the unresolved list to be resolved later, as needed.

Returns an array with bindir attached to each executable in the executables list

add_dependency(gem, *requirements)

Adds a development dependency named gem with requirements to this Gem. For example:

  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. For example:

  spec.add_runtime_dependency 'example', '~> 1.1', '>= 1.1.4'

Adds this spec‘s require paths to LOAD_PATH, in the proper location.

Singular reader for authors

Singular writer for authors

The list of author names who wrote this gem.

If you are providing multiple authors and multiple emails they should be in the same order such that:

  Hash[*spec.authors.zip(spec.emails).flatten]

Gives a hash of author name to email address.

Sets the list of authors, ensuring it is an array.

Returns the full path to the base gem directory.

eg: /usr/local/lib/ruby/gems/1.8

Returns the full path to installed gem‘s bin directory.

NOTE: do not confuse this with bindir, which is just ‘bin’, not a full path.

Returns the full path to an executable named name in this gem.

Returns the full path to the cache directory containing this spec‘s cached gem.

Returns the full path to the cached gem for this spec.

cache_gem()

Alias for cache_file

Return any possible conflicts against the currently loaded specs.

Return true if this spec can require file.

The date this gem was created. Lazily defaults to TODAY.

The date this gem was created

Do not set this, it is set automatically when the gem is packaged.

The default executable for this gem.

Deprecated: The name of the gem is assumed to be the name of the executable now. See Gem.bin_path.

The default value for specification attribute name

A list of Gem::Dependency objects this gem depends on.

Use add_dependency or add_development_dependency to add dependencies to a gem.

Return a list of all gems that have a dependency on this gemspec. The list is structured with entries that conform to:

  [depending_gem, dependency, [list_of_gems_that_satisfy_dependency]]

Returns all specs that matches this spec‘s runtime dependencies.

A long description of this gem

List of dependencies that are used for development

Returns the full path to this spec‘s documentation directory.

Singular accessor for executables

Singular accessor for executables

Executables included in the gem.

Sets executables to value, ensuring it is an array. Don‘t use this, push onto the array instead.

Extensions to build when installing the gem. See Gem::Installer#build_extensions for valid values.

Sets extensions to extensions, ensuring it is an array. Don‘t use this, push onto the array instead.

Extra files to add to RDoc such as README or doc/examples.txt

Sets extra_rdoc_files to files, ensuring it is an array. Don‘t use this, push onto the array instead.

The default (generated) file name of the gem. See also spec_name.

  spec.file_name # => "example-1.0.gem"

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.

Sets files to files, ensuring it is an array.

Creates a duplicate spec without large blobs that aren‘t used at runtime.

The full path to the gem (install path + full name).

Returns the full name (name-version) of this Gem. Platform information is included (name-version-platform) if it is specified and not the default Ruby platform.

Returns the full path to this spec‘s gem directory. eg: /usr/local/lib/ruby/1.8/gems/mygem-1.0

Returns the full path to the gems directory containing this spec‘s gem directory. eg: /usr/local/lib/ruby/1.8/gems

Deprecated and ignored, defaults to true.

Formerly used to indicate this gem was RDoc-capable.

Deprecated and ignored.

Formerly used to indicate this gem was RDoc-capable.

has_rdoc?()

Alias for has_rdoc

True if this gem has files in test_files

Duplicates array_attributes from other_spec so state isn‘t shared.

The directory that this gem was installed into. TODO: rename - horrible. this is the base_dir for a gem path

Returns a string usable in Dir.glob to match all requirable paths for this spec.

Files in the Gem under one of the require_paths

Singular accessor for licenses

Singular accessor for licenses

The license(s) for the library. Each license must be a short name, no more than 64 characters.

Set licenses to licenses, ensuring it is an array.

Set the location a Specification was loaded from. obj is converted to a String.

Sets the rubygems_version to the current RubyGems version.

Return all files in this gem that match for glob.

Normalize the list of files so that:

  • All file lists have redundancies removed.
  • Files referenced in the extra_rdoc_files are included in the package file list.

The platform this gem runs on. See Gem::Platform for details.

The platform this gem runs on. See Gem::Platform for details.

Setting this to any value other than Gem::Platform::RUBY or Gem::Platform::CURRENT is probably wrong.

Check the spec for possible conflicts and freak out if there are any.

An ARGV style array of options to RDoc

Sets rdoc_options to value, ensuring it is an array. Don‘t use this, push onto the array instead.

Singular accessor for require_paths

Singular accessor for require_paths

The version of ruby required by this gem

The RubyGems version required by this gem

An array or things required by this gem. Not used by anything presently.

Set requirements to req, ensuring it is an array. Don‘t use this, push onto the array instead.

Returns the full path to this spec‘s ri directory.

List of dependencies that will automatically be activated at runtime.

Checks if this specification meets the requirement of dependency.

Returns an object you can use to sort specifications in sort_by.

Returns the full path to the directory containing this spec‘s gemspec file. eg: /usr/local/lib/ruby/gems/1.8/specifications

Returns the full path to this spec‘s gemspec file. eg: /usr/local/lib/ruby/gems/1.8/specifications/mygem-1.0.gemspec

The default name of the gemspec. See also file_name

  spec.spec_name # => "example-1.0.gemspec"

A short summary of this gem‘s description.

Singular accessor for test_files

Singular accessor for test_files

Test files included in this gem. You cannot append to this accessor, you must assign to it.

Set test_files to files, ensuring it is an array.

Returns a Ruby code representation of this specification, such that it can be eval‘ed and reconstruct the same specification later. Attributes that still have their default values are omitted.

Returns a Ruby lighter-weight code representation of this specification, used for indexing only.

See to_ruby.

Recursively walk dependencies of this spec, executing the block for each hop.

Checks that the specification contains all required fields, and does a very basic sanity check.

Raises InvalidSpecificationException if the spec does not pass the checks..

Set the version to version, potentially also setting required_rubygems_version if version indicates it is a prerelease.