Class: Gem::Specification

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

## Gem::Specification

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 = 'rfoo'
        s.version = '1.0'
        s.summary = 'Example gem specification'
        ...
      end

There are many gemspec attributes, and the best place to learn about them in the "Gemspec Reference" linked from the RubyGems wiki.

### Methods

_load add_bindir add_dependency array_attribute array_attributes assign_defaults attribute attribute_alias_singular attribute_defaults attribute_names attributes default_value dependent_gems file_name from_yaml full_gem_path full_name has_rdoc? has_test_suite? has_unit_tests? installation_path lib_files list load loaded? mark_version new normalize normalize_yaml_input overwrite_accessor read_only required_attribute required_attribute? required_attributes satisfies_requirement? sort_obj test_suite_file test_suite_file= to_ruby to_s validate

### 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 | = | 2 |  | The specification version applied to any new Specification instances created. This should be bumped whenever something in the spec format changes.
SPECIFICATION_VERSION_HISTORY | = | { -1 => ['(RubyGems versions up to and including 0.7 did not have versioned specifications)'], 1 => [ 'Deprecated "test_suite_file" in favor of the new, but equivalent, "test_files"', '"test_file=x" is a shortcut for "test_files=[x]"' |  | An informal list of changes to the specification. The highest-valued key should be equal to the CURRENT_SPECIFICATION_VERSION.

### External Aliases

== | -> | eql?

### Attributes

loaded | [W] | true when this gemspec has been loaded from a specifications directory. This attribute is not persisted.
loaded_from | [RW] | Path this gemspec was loaded from. This attribute is not persisted.

### Public Class methods

_load(str)

Load custom marshal format, re-initializing defaults as needed

array_attribute(name)

Same as :attribute, but ensures that values assigned to the attribute are array values by applying :to_a to the value.

array_attributes()
attribute(name, default=nil)

Used to specify the name and default value of a specification attribute. The side effects are:

- the name and default value are added to the @@attributes list and @@default_value map
- a standard writer method (`attribute=`) is created
- a non-standard _reader method (`attribute`) is created

The reader method behaves like this:

      def attribute
        @attribute ||= (copy of default value)
      end

This allows lazy initialization of attributes to their default values.

attribute_alias_singular(singular, plural)

Defines a singular version of an existing plural attribute (i.e. one whose value is expected to be an array). This means just creating a helper method that takes a single value and appends it to the array. These are created for convenience, so that in a spec, one can write

      s.require_path = 'mylib'

instead of

      s.require_paths = ['mylib']

That above convenience is available courtesy of

      attribute_alias_singular :require_path, :require_paths

attribute_defaults()
attribute_names()

————————- Convenience class methods.

attributes(*args)

Shortcut for creating several attributes at once (each with a default value of `nil`).

default_value(name)
from_yaml(input)

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.

list()

A list of Specification instances that have been defined in this Ruby instance.

load(filename)
new() {|self if block_given?| ...}

Specification constructor. Assigns the default values to the attributes, adds this spec to the list of loaded specs (see Specification.list), and yields itself for further initialization.

normalize_yaml_input(input)

Make sure the yaml specification is properly formatted with dashes.

overwrite_accessor(name, &block)

Some attributes require special behaviour when they are accessed. This allows for that.

read_only(*names)

Sometimes we don‘t want the world to use a setter method for a particular attribute. `read_only` makes it private so we can still use it internally.

required_attribute(*args)

Same as attribute above, but also records this attribute as mandatory.

required_attribute?(name)
required_attributes()

### Public Instance methods

add_bindir(executables)
add_dependency(gem, *requirements)

Adds a dependency to this Gem. For example,

      spec.add_dependency('jabber4r', '> 0.1', '<= 0.5')

gem: | [String or Gem::Dependency] The Gem name/dependency.
requirements: | [default=">= 0"] The version requirements.

assign_defaults()

Each attribute has a default value (possibly nil). Here, we initialize all attributes to their default value. This is done through the accessor methods, so special behaviours will be honored. Furthermore, we take a copy of the default so each specification instance has its own empty arrays, etc.

dependent_gems()

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]]

return: | [Array] [[dependent_gem, dependency, [list_of_satisfiers]]]

file_name()

The default (generated) file name of the gem.

full_gem_path()

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

return: | [String] the full gem 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).

has_rdoc?()
has_test_suite?()

Alias for has_unit_tests?

has_unit_tests?()
installation_path()

The root directory that the gem was installed into.

return: | [String] the installation path

lib_files()

Files in the Gem under one of the require_paths

loaded?()

Predicates ——————————————————

mark_version()

Sets the rubygems_version to Gem::RubyGemsVersion.

normalize()

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.

Also, the summary and description are converted to a normal format.

satisfies_requirement?(dependency)

Checks if this Specification meets the requirement of the supplied dependency.

dependency: | [Gem::Dependency] the dependency to check
return: | [Boolean] true if dependency is met, otherwise false

sort_obj()

Comparison methods ———————————————

test_suite_file()

DEPRECATED gemspec attributes ———————————-

test_suite_file=(val)
to_ruby()

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.

to_s()
validate()

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

[Validate]