Extended maintenance of Ruby 1.9.3 ended on February 23, 2015. Read more
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.
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
The the version number of a specification that does not specify one (i.e. RubyGems 0.7 or earlier).
Autorequire was used by old RubyGems to automatically require a file.
Deprecated: It is neither supported nor functional.
Sets the default executable for this gem.
Deprecated: You must now specify the executable name to Gem.bin_path.
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.
The rubyforge project this gem lives under. i.e. RubyGems’ #rubyforge_project is “rubygems”.
Load custom marshal format, re-initializing defaults as needed
# File rubygems/specification.rb, line 649 def self._load(str) array = Marshal.load str spec = Gem::Specification.new spec.instance_variable_set :@specification_version, array[1] current_version = CURRENT_SPECIFICATION_VERSION field_count = if spec.specification_version > current_version then spec.instance_variable_set :@specification_version, current_version MARSHAL_FIELDS[current_version] else MARSHAL_FIELDS[spec.specification_version] end if array.size < field_count then raise TypeError, "invalid Gem::Specification format #{array.inspect}" end # Cleanup any YAML::PrivateType. They only show up for an old bug # where nil => null, so just convert them to nil based on the type. array.map! { |e| e.kind_of?(YAML::PrivateType) ? nil : e } spec.instance_variable_set :@rubygems_version, array[0] # spec version spec.instance_variable_set :@name, array[2] spec.instance_variable_set :@version, array[3] spec.date = array[4] spec.instance_variable_set :@summary, array[5] spec.instance_variable_set :@required_ruby_version, array[6] spec.instance_variable_set :@required_rubygems_version, array[7] spec.instance_variable_set :@original_platform, array[8] spec.instance_variable_set :@dependencies, array[9] spec.instance_variable_set :@rubyforge_project, array[10] spec.instance_variable_set :@email, array[11] spec.instance_variable_set :@authors, array[12] spec.instance_variable_set :@description, array[13] spec.instance_variable_set :@homepage, array[14] spec.instance_variable_set :@has_rdoc, array[15] spec.instance_variable_set :@new_platform, array[16] spec.instance_variable_set :@platform, array[16].to_s spec.instance_variable_set :@license, array[17] spec.instance_variable_set :@loaded, false spec.instance_variable_set :@activated, false spec end
Adds spec
to the known specifications, keeping the collection
properly sorted.
# File rubygems/specification.rb, line 295 def self.add_spec spec # TODO: find all extraneous adds # puts # p :add_spec => [spec.full_name, caller.reject { |s| s =~ /minitest/ }] # TODO: flush the rest of the crap from the tests # raise "no dupes #{spec.full_name} in #{all_names.inspect}" if # _all.include? spec raise "nil spec!" unless spec # TODO: remove once we're happy with tests return if _all.include? spec _all << spec _resort! end
Adds multiple specs to the known specifications.
# File rubygems/specification.rb, line 315 def self.add_specs *specs raise "nil spec!" if specs.any?(&:nil?) # TODO: remove once we're happy # TODO: this is much more efficient, but we need the extra checks for now # _all.concat specs # _resort! specs.each do |spec| # TODO: slow add_spec spec end end
Returns all specifications. This method is discouraged from use. You probably want to use one of the Enumerable methods instead.
# File rubygems/specification.rb, line 331 def self.all warn "NOTE: Specification.all called from #{caller.first}" unless Gem::Deprecate.skip _all end
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.
# File rubygems/specification.rb, line 349 def self.all= specs @@all = specs end
Return full names of all specs in sorted order.
# File rubygems/specification.rb, line 356 def self.all_names self._all.map(&:full_name) end
Return the list of all array-oriented instance variables.
# File rubygems/specification.rb, line 365 def self.array_attributes @@array_attributes.dup end
Return the list of all instance variables.
# File rubygems/specification.rb, line 374 def self.attribute_names @@attributes.dup end
Return the directories that Specification uses to find specs.
# File rubygems/specification.rb, line 381 def self.dirs @@dirs ||= Gem.path.collect { |dir| File.join dir, "specifications" } end
Set the directories that Specification uses to find specs. Setting this resets the list of known specs.
# File rubygems/specification.rb, line 391 def self.dirs= dirs # TODO: find extra calls to dir= # warn "NOTE: dirs= called from #{caller.first} for #{dirs.inspect}" self.reset # ugh @@dirs = Array(dirs).map { |dir| File.join dir, "specifications" } end
Enumerate every known spec. See ::dirs= and ::add_spec to set the list of specs.
# File rubygems/specification.rb, line 407 def self.each return enum_for(:each) unless block_given? self._all.each do |x| yield x end end
Returns every spec that matches name
and optional
requirements
.
# File rubygems/specification.rb, line 418 def self.find_all_by_name name, *requirements requirements = Gem::Requirement.default if requirements.empty? # TODO: maybe try: find_all { |s| spec === dep } Gem::Dependency.new(name, *requirements).matching_specs end
Find the best specification matching a name
and
requirements
. Raises if the dependency doesn’t resolve to a
valid specification.
# File rubygems/specification.rb, line 430 def self.find_by_name name, *requirements requirements = Gem::Requirement.default if requirements.empty? # TODO: maybe try: find { |s| spec === dep } Gem::Dependency.new(name, *requirements).to_spec end
Return the best specification that contains the file matching
path
.
# File rubygems/specification.rb, line 441 def self.find_by_path path self.find { |spec| spec.contains_requirable_file? path } end
Return currently unresolved specs that contain the file matching
path
.
# File rubygems/specification.rb, line 450 def self.find_in_unresolved path # TODO: do we need these?? Kill it specs = Gem.unresolved_deps.values.map { |dep| dep.to_specs }.flatten specs.find_all { |spec| spec.contains_requirable_file? path } end
Search through all unresolved deps and sub-dependencies and return specs
that contain the file matching path
.
# File rubygems/specification.rb, line 461 def self.find_in_unresolved_tree path specs = Gem.unresolved_deps.values.map { |dep| dep.to_specs }.flatten specs.reverse_each do |spec| trails = [] spec.traverse do |from_spec, dep, to_spec, trail| next unless to_spec.conflicts.empty? trails << trail if to_spec.contains_requirable_file? path end next if trails.empty? return trails.map(&:reverse).sort.first.reverse end [] end
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.
# File rubygems/specification.rb, line 487 def self.from_yaml(input) Gem.load_yaml input = normalize_yaml_input input spec = YAML.load input if spec && spec.class == FalseClass then raise Gem::EndOfYAMLException end unless Gem::Specification === spec then raise Gem::Exception, "YAML data doesn't evaluate to gem specification" end unless (spec.instance_variables.include? '@specification_version' or spec.instance_variables.include? :@specification_version) and spec.instance_variable_get :@specification_version spec.instance_variable_set :@specification_version, NONEXISTENT_SPECIFICATION_VERSION end spec end
Return the latest specs, optionally including prerelease specs if
prerelease
is true.
# File rubygems/specification.rb, line 515 def self.latest_specs prerelease = false result = Hash.new { |h,k| h[k] = {} } native = {} Gem::Specification._all.reverse_each do |spec| next if spec.version.prerelease? unless prerelease native[spec.name] = spec.version if spec.platform == Gem::Platform::RUBY result[spec.name][spec.platform] = spec end result.map(&:last).map(&:values).flatten.reject { |spec| minimum = native[spec.name] minimum && spec.version < minimum } end
Loads Ruby format gemspec from file
.
# File rubygems/specification.rb, line 535 def self.load file return unless file && File.file?(file) file = file.dup.untaint code = if defined? Encoding File.read file, :mode => 'r:UTF-8:-' else File.read file end code.untaint begin spec = eval code, binding, file if Gem::Specification === spec spec.loaded_from = file.to_s return spec end warn "[#{file}] isn't a Gem::Specification (#{spec.class} instead)." rescue SignalException, SystemExit raise rescue SyntaxError, Exception => e warn "Invalid gemspec in [#{file}]: #{e}" end nil end
Specification constructor. Assigns the
default values to the attributes and yields itself for further
initialization. Optionally takes name
and
version
.
# File rubygems/specification.rb, line 1343 def initialize name = nil, version = nil @loaded = false @activated = false @loaded_from = nil @original_platform = nil @@nil_attributes.each do |key| instance_variable_set "@#{key}", nil end @@non_nil_attributes.each do |key| default = default_value(key) value = case default when Time, Numeric, Symbol, true, false, nil then default else default.dup end instance_variable_set "@#{key}", value end @new_platform = Gem::Platform::RUBY self.name = name if name self.version = version if version yield self if block_given? end
Specification attributes that must be non-nil
# File rubygems/specification.rb, line 569 def self.non_nil_attributes @@non_nil_attributes.dup end
Make sure the YAML specification is properly formatted with dashes
# File rubygems/specification.rb, line 576 def self.normalize_yaml_input(input) result = input.respond_to?(:read) ? input.read : input result = "--- " + result unless result =~ /\A--- / result.gsub!(/ !!null \n/, " \n") # date: 2011-04-26 00:00:00.000000000Z # date: 2011-04-26 00:00:00.000000000 Z result.gsub!(/^(date: \d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\.\d+?)Z/, '\1 Z') result end
Return a list of all outdated specifications. This method is HEAVY as it must go fetch specifications from the server.
# File rubygems/specification.rb, line 590 def self.outdated outdateds = [] # TODO: maybe we should switch to rubygems' version service? fetcher = Gem::SpecFetcher.fetcher latest_specs.each do |local| dependency = Gem::Dependency.new local.name, ">= #{local.version}" remotes = fetcher.find_matching dependency remotes = remotes.map { |(_, version, _), _| version } latest = remotes.sort.last outdateds << local.name if latest and local.version < latest end outdateds end
Removes spec
from the known specs.
# File rubygems/specification.rb, line 611 def self.remove_spec spec # TODO: beat on the tests raise "wtf: #{spec.full_name} not in #{all_names.inspect}" unless _all.include? spec _all.delete spec end
Is name
a required attribute?
# File rubygems/specification.rb, line 621 def self.required_attribute?(name) @@required_attributes.include? name.to_sym end
Required specification attributes
# File rubygems/specification.rb, line 628 def self.required_attributes @@required_attributes.dup end
Reset the list of known specs, running pre and post reset hooks registered in Gem.
# File rubygems/specification.rb, line 636 def self.reset @@dirs = nil # from = caller.first(10).reject { |s| s =~ /minitest/ } # warn "" # warn "NOTE: Specification.reset from #{from.inspect}" Gem.pre_reset_hooks.each { |hook| hook.call } @@all = nil Gem.post_reset_hooks.each { |hook| hook.call } end
Dump only crucial instance variables.
# File rubygems/specification.rb, line 716 def _dump(limit) Marshal.dump [ @rubygems_version, @specification_version, @name, @version, date, @summary, @required_ruby_version, @required_rubygems_version, @original_platform, @dependencies, @rubyforge_project, @email, @authors, @description, @homepage, true, # has_rdoc @new_platform, @licenses ] end
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.
# File rubygems/specification.rb, line 745 def activate raise_if_conflicts return false if Gem.loaded_specs[self.name] activate_dependencies add_self_to_load_path Gem.loaded_specs[self.name] = self @activated = true @loaded = true return true end
Activate all unambiguously resolved runtime dependencies of this spec. Add any ambigous dependencies to the unresolved list to be resolved later, as needed.
# File rubygems/specification.rb, line 765 def activate_dependencies self.runtime_dependencies.each do |spec_dep| if loaded = Gem.loaded_specs[spec_dep.name] next if spec_dep.matches_spec? loaded msg = "can't satisfy '#{spec_dep}', already activated '#{loaded.full_name}'" e = Gem::LoadError.new msg e.name = spec_dep.name raise e end specs = spec_dep.to_specs if specs.size == 1 then specs.first.activate else name = spec_dep.name Gem.unresolved_deps[name] = Gem.unresolved_deps[name].merge spec_dep end end Gem.unresolved_deps.delete self.name end
Returns an array with bindir attached to each executable in the
executables
list
# File rubygems/specification.rb, line 794 def add_bindir(executables) return nil if executables.nil? if @bindir then Array(executables).map { |e| File.join(@bindir, e) } else executables end rescue return nil end
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.
# File rubygems/specification.rb, line 838 def add_development_dependency(gem, *requirements) add_dependency_with_type(gem, :development, *requirements) end
Adds a runtime dependency named gem
with
requirements
to this Gem. For example:
spec.add_runtime_dependency 'example', '~> 1.1', '>= 1.1.4'
# File rubygems/specification.rb, line 848 def add_runtime_dependency(gem, *requirements) add_dependency_with_type(gem, :runtime, *requirements) end
Adds this spec’s require paths to LOAD_PATH, in the proper location.
# File rubygems/specification.rb, line 857 def add_self_to_load_path paths = require_paths.map do |path| File.join full_gem_path, path end # gem directories must come after -I and ENV['RUBYLIB'] insert_index = Gem.load_path_insert_index if insert_index then # gem directories must come after -I and ENV['RUBYLIB'] $LOAD_PATH.insert(insert_index, *paths) else # we are probably testing in core, -I and RUBYLIB don't apply $LOAD_PATH.unshift(*paths) end end
Returns the full path to the base gem directory.
eg: /usr/local/lib/ruby/gems/1.8
# File rubygems/specification.rb, line 914 def base_dir return Gem.dir unless loaded_from @base_dir ||= File.dirname File.dirname loaded_from end
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.
# File rubygems/specification.rb, line 925 def bin_dir @bin_dir ||= File.join gem_dir, bindir # TODO: this is unfortunate end
Returns the full path to an executable named name
in this gem.
# File rubygems/specification.rb, line 932 def bin_file name File.join bin_dir, name end
Returns the full path to the cache directory containing this spec’s cached gem.
# File rubygems/specification.rb, line 940 def cache_dir @cache_dir ||= File.join base_dir, "cache" end
Returns the full path to the cached gem for this spec.
# File rubygems/specification.rb, line 947 def cache_file @cache_file ||= File.join cache_dir, "#{full_name}.gem" end
Return any possible conflicts against the currently loaded specs.
# File rubygems/specification.rb, line 956 def conflicts conflicts = {} Gem.loaded_specs.values.each do |spec| bad = self.runtime_dependencies.find_all { |dep| spec.name == dep.name and not spec.satisfies_requirement? dep } conflicts[spec] = bad unless bad.empty? end conflicts end
Return true if this spec can require file
.
# File rubygems/specification.rb, line 971 def contains_requirable_file? file root = full_gem_path require_paths.each do |lib| base = "#{root}/#{lib}/#{file}" Gem.suffixes.each do |suf| path = "#{base}#{suf}" return true if File.file? path end end return false end
The date this gem was created. Lazily defaults to TODAY.
# File rubygems/specification.rb, line 988 def date @date ||= TODAY end
The date this gem was created
Do not set this, it is set automatically when the gem is packaged.
# File rubygems/specification.rb, line 997 def date= date # We want to end up with a Time object with one-day resolution. # This is the cleanest, most-readable, faster-than-using-Date # way to do it. @date = case date when String then if /\A(\d{4})-(\d{2})-(\d{2})\Z/ =~ date then Time.utc($1.to_i, $2.to_i, $3.to_i) # Workaround for where the date format output from psych isn't # parsed as a Time object by syck and thus comes through as a # string. elsif /\A(\d{4})-(\d{2})-(\d{2}) \d{2}:\d{2}:\d{2}\.\d+?Z\z/ =~ date then Time.utc($1.to_i, $2.to_i, $3.to_i) else raise(Gem::InvalidSpecificationException, "invalid date format in specification: #{date.inspect}") end when Time, Date then Time.utc(date.year, date.month, date.day) else TODAY end end
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.
# File rubygems/specification.rb, line 1028 def default_executable if defined?(@default_executable) and @default_executable result = @default_executable elsif @executables and @executables.size == 1 result = Array(@executables).first else result = nil end result end
The default value for specification attribute name
# File rubygems/specification.rb, line 1042 def default_value name @@default_value[name] end
A list of Gem::Dependency objects this gem depends on.
Use add_dependency or add_development_dependency to add dependencies to a gem.
# File rubygems/specification.rb, line 1052 def dependencies @dependencies ||= [] end
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]]
# File rubygems/specification.rb, line 1062 def dependent_gems out = [] Gem::Specification.each do |spec| spec.dependencies.each do |dep| if self.satisfies_requirement?(dep) then sats = [] find_all_satisfiers(dep) do |sat| sats << sat end out << [spec, dep, sats] end end end out end
Returns all specs that matches this spec’s runtime dependencies.
# File rubygems/specification.rb, line 1081 def dependent_specs runtime_dependencies.map { |dep| dep.to_specs }.flatten end
A long description of this gem
# File rubygems/specification.rb, line 1088 def description= str @description = str.to_s end
List of dependencies that are used for development
# File rubygems/specification.rb, line 1095 def development_dependencies dependencies.select { |d| d.type == :development } end
Returns the full path to this spec’s documentation directory.
# File rubygems/specification.rb, line 1102 def doc_dir @doc_dir ||= File.join base_dir, 'doc', full_name end
Singular accessor for executables
# File rubygems/specification.rb, line 1134 def executable val = executables and val.first end
Singular accessor for executables
# File rubygems/specification.rb, line 1141 def executable=o self.executables = [o] end
Executables included in the gem.
# File rubygems/specification.rb, line 1148 def executables @executables ||= [] end
Sets executables to value
, ensuring it is an array. Don’t use
this, push onto the array instead.
# File rubygems/specification.rb, line 1156 def executables= value # TODO: warn about setting instead of pushing @executables = Array(value) end
Extensions to build when installing the gem. See Gem::Installer#build_extensions for valid values.
# File rubygems/specification.rb, line 1165 def extensions @extensions ||= [] end
Sets extensions to extensions
, ensuring it is an array. Don’t
use this, push onto the array instead.
# File rubygems/specification.rb, line 1173 def extensions= extensions # TODO: warn about setting instead of pushing @extensions = Array extensions end
Extra files to add to RDoc such as README or doc/examples.txt
# File rubygems/specification.rb, line 1181 def extra_rdoc_files @extra_rdoc_files ||= [] end
Sets #extra_rdoc_files
to files
, ensuring it is an array. Don’t use this, push onto
the array instead.
# File rubygems/specification.rb, line 1189 def extra_rdoc_files= files # TODO: warn about setting instead of pushing @extra_rdoc_files = Array files end
The default (generated) file name of the gem. See also spec_name.
spec.file_name # => "example-1.0.gem"
# File rubygems/specification.rb, line 1199 def file_name "#{full_name}.gem" 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.
# File rubygems/specification.rb, line 1212 def files # DO NOT CHANGE TO ||= ! This is not a normal accessor. (yes, it sucks) @files = [@files, @test_files, add_bindir(@executables), @extra_rdoc_files, @extensions, ].flatten.uniq.compact end
Sets files to files
, ensuring it is an array.
# File rubygems/specification.rb, line 1225 def files= files @files = Array files end
Creates a duplicate spec without large blobs that aren’t used at runtime.
# File rubygems/specification.rb, line 1243 def for_cache spec = dup spec.files = nil spec.test_files = nil spec end
The full path to the gem (install path + full name).
# File rubygems/specification.rb, line 1255 def full_gem_path # TODO: try to get rid of this... or the awkward # TODO: also, shouldn't it default to full_name if it hasn't been written? return @full_gem_path if defined?(@full_gem_path) && @full_gem_path @full_gem_path = File.expand_path File.join(gems_dir, full_name) return @full_gem_path if File.directory? @full_gem_path @full_gem_path = File.expand_path File.join(gems_dir, original_name) end
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.
# File rubygems/specification.rb, line 1272 def full_name if platform == Gem::Platform::RUBY or platform.nil? then "#{@name}-#{@version}" else "#{@name}-#{@version}-#{platform}" end end
Returns the full path to this spec’s gem directory. eg: /usr/local/lib/ruby/1.8/gems/mygem-1.0
# File rubygems/specification.rb, line 1284 def gem_dir @gem_dir ||= File.expand_path File.join(gems_dir, full_name) end
Returns the full path to the gems directory containing this spec’s gem directory. eg: /usr/local/lib/ruby/1.8/gems
# File rubygems/specification.rb, line 1292 def gems_dir # TODO: this logic seems terribly broken, but tests fail if just base_dir @gems_dir ||= File.join(loaded_from && base_dir || Gem.dir, "gems") end
Deprecated and ignored, defaults to true.
Formerly used to indicate this gem was RDoc-capable.
# File rubygems/specification.rb, line 1302 def has_rdoc true end
Deprecated and ignored.
Formerly used to indicate this gem was RDoc-capable.
# File rubygems/specification.rb, line 1311 def has_rdoc= ignored @has_rdoc = true end
True if this gem has files in #test_files
# File rubygems/specification.rb, line 1320 def has_unit_tests? not test_files.empty? end
Duplicates ::array_attributes
from other_spec
so state isn’t shared.
# File rubygems/specification.rb, line 1374 def initialize_copy other_spec other_ivars = other_spec.instance_variables other_ivars = other_ivars.map { |ivar| ivar.intern } if # for 1.9 String === other_ivars.first self.class.array_attributes.each do |name| name = :"@#{name}" next unless other_ivars.include? name begin val = other_spec.instance_variable_get(name) if val then instance_variable_set name, val.dup elsif Gem.configuration.really_verbose warn "WARNING: #{full_name} has an invalid nil value for #{name}" end rescue TypeError e = Gem::FormatException.new "#{full_name} has an invalid value for #{name}" e.file_path = loaded_from raise e end end end
The directory that this gem was installed into. TODO: rename - horrible. this is the #base_dir for a gem path
# File rubygems/specification.rb, line 1404 def installation_path loaded_from && base_dir end
Returns a string usable in Dir.glob to match all requirable paths for this spec.
# File rubygems/specification.rb, line 1412 def lib_dirs_glob dirs = if self.require_paths.size > 1 then "{#{self.require_paths.join(',')}}" else self.require_paths.first end "#{self.full_gem_path}/#{dirs}" end
Files in the Gem under one of the #require_paths
# File rubygems/specification.rb, line 1425 def lib_files @files.select do |file| require_paths.any? do |path| file.index(path) == 0 end end end
Singular accessor for licenses
# File rubygems/specification.rb, line 1436 def license val = licenses and val.first end
Singular accessor for licenses
# File rubygems/specification.rb, line 1443 def license=o self.licenses = [o] end
The license(s) for the library. Each license must be a short name, no more than 64 characters.
# File rubygems/specification.rb, line 1451 def licenses @licenses ||= [] end
Set licenses to licenses
, ensuring it is an array.
# File rubygems/specification.rb, line 1458 def licenses= licenses @licenses = Array licenses end
Set the location a Specification was
loaded from. obj
is converted to a String.
# File rubygems/specification.rb, line 1466 def loaded_from= path @loaded_from = path.to_s end
Sets the #rubygems_version to the current RubyGems version.
# File rubygems/specification.rb, line 1473 def mark_version @rubygems_version = Gem::VERSION end
Return all files in this gem that match for glob
.
# File rubygems/specification.rb, line 1480 def matches_for_glob glob # TODO: rename? # TODO: do we need these?? Kill it glob = File.join(self.lib_dirs_glob, glob) Dir[glob].map { |f| f.untaint } # FIX our tests are broken, run w/ SAFE=1 end
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.
# File rubygems/specification.rb, line 1505 def normalize if defined?(@extra_rdoc_files) and @extra_rdoc_files then @extra_rdoc_files.uniq! @files ||= [] @files.concat(@extra_rdoc_files) end @files = @files.uniq if @files @extensions = @extensions.uniq if @extensions @test_files = @test_files.uniq if @test_files @executables = @executables.uniq if @executables @extra_rdoc_files = @extra_rdoc_files.uniq if @extra_rdoc_files end
The platform this gem runs on. See Gem::Platform for details.
# File rubygems/specification.rb, line 1541 def platform @new_platform ||= Gem::Platform::RUBY end
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.
# File rubygems/specification.rb, line 1551 def platform= platform if @original_platform.nil? or @original_platform == Gem::Platform::RUBY then @original_platform = platform end case platform when Gem::Platform::CURRENT then @new_platform = Gem::Platform.local @original_platform = @new_platform.to_s when Gem::Platform then @new_platform = platform # legacy constants when nil, Gem::Platform::RUBY then @new_platform = Gem::Platform::RUBY when 'mswin32' then # was Gem::Platform::WIN32 @new_platform = Gem::Platform.new 'x86-mswin32' when 'i586-linux' then # was Gem::Platform::LINUX_586 @new_platform = Gem::Platform.new 'x86-linux' when 'powerpc-darwin' then # was Gem::Platform::DARWIN @new_platform = Gem::Platform.new 'ppc-darwin' else @new_platform = Gem::Platform.new platform end @platform = @new_platform.to_s @new_platform end
Check the spec for possible conflicts and freak out if there are any.
# File rubygems/specification.rb, line 1612 def raise_if_conflicts other = Gem.loaded_specs[self.name] if other and self.version != other.version then # This gem is already loaded. If the currently loaded gem is not in the # list of candidate gems, then we have a version conflict. msg = "can't activate #{full_name}, already activated #{other.full_name}" e = Gem::LoadError.new msg e.name = self.name # TODO: e.requirement = dep.requirement raise e end conf = self.conflicts unless conf.empty? then y = conf.map { |act,con| "#{act.full_name} conflicts with #{con.join(", ")}" }.join ", " # TODO: improve message by saying who activated `con` raise Gem::LoadError, "Unable to activate #{self.full_name}, because #{y}" end end
An ARGV style array of options to RDoc
# File rubygems/specification.rb, line 1644 def rdoc_options @rdoc_options ||= [] end
Sets #rdoc_options
to value
, ensuring it is an array. Don’t use this, push onto
the array instead.
# File rubygems/specification.rb, line 1652 def rdoc_options= options # TODO: warn about setting instead of pushing @rdoc_options = Array options end
Singular accessor for require_paths
# File rubygems/specification.rb, line 1660 def require_path val = require_paths and val.first end
Singular accessor for require_paths
# File rubygems/specification.rb, line 1667 def require_path= path self.require_paths = [path] end
The version of ruby required by this gem
# File rubygems/specification.rb, line 1674 def required_ruby_version= req @required_ruby_version = Gem::Requirement.create req end
The RubyGems version required by this gem
# File rubygems/specification.rb, line 1681 def required_rubygems_version= req @required_rubygems_version = Gem::Requirement.create req end
An array or things required by this gem. Not used by anything presently.
# File rubygems/specification.rb, line 1689 def requirements @requirements ||= [] end
Set requirements to req
, ensuring it is an array. Don’t use
this, push onto the array instead.
# File rubygems/specification.rb, line 1697 def requirements= req # TODO: warn about setting instead of pushing @requirements = Array req end
Returns the full path to this spec’s ri directory.
# File rubygems/specification.rb, line 1705 def ri_dir @ri_dir ||= File.join base_dir, 'ri', full_name end
List of dependencies that will automatically be activated at runtime.
# File rubygems/specification.rb, line 1733 def runtime_dependencies dependencies.select { |d| d.type == :runtime } end
Checks if this specification meets the requirement of
dependency
.
# File rubygems/specification.rb, line 1749 def satisfies_requirement? dependency return @name == dependency.name && dependency.requirement.satisfied_by?(@version) end
Returns an object you can use to sort specifications in sort_by.
# File rubygems/specification.rb, line 1757 def sort_obj # TODO: this is horrible. Deprecate it. [@name, @version, @new_platform == Gem::Platform::RUBY ? -1 : 1] end
Returns the full path to the directory containing this spec’s gemspec file. eg: /usr/local/lib/ruby/gems/1.8/specifications
# File rubygems/specification.rb, line 1766 def spec_dir @spec_dir ||= File.join base_dir, "specifications" end
Returns the full path to this spec’s gemspec file. eg: /usr/local/lib/ruby/gems/1.8/specifications/mygem-1.0.gemspec
# File rubygems/specification.rb, line 1774 def spec_file @spec_file ||= File.join spec_dir, "#{full_name}.gemspec" end
The default name of the gemspec. See also file_name
spec.spec_name # => "example-1.0.gemspec"
# File rubygems/specification.rb, line 1783 def spec_name "#{full_name}.gemspec" end
A short summary of this gem’s description.
# File rubygems/specification.rb, line 1790 def summary= str @summary = str.to_s.strip. gsub(/(\w-)\n[ \t]*(\w)/, '\1\2').gsub(/\n[ \t]*/, " ") # so. weird. end
Singular accessor for test_files
# File rubygems/specification.rb, line 1798 def test_file val = test_files and val.first end
Singular accessor for test_files
# File rubygems/specification.rb, line 1805 def test_file= file self.test_files = [file] end
Test files included in this gem. You cannot append to this accessor, you must assign to it.
# File rubygems/specification.rb, line 1813 def test_files # Handle the possibility that we have @test_suite_file but not # @test_files. This will happen when an old gem is loaded via # YAML. if defined? @test_suite_file then @test_files = [@test_suite_file].flatten @test_suite_file = nil end if defined?(@test_files) and @test_files then @test_files else @test_files = [] end end
Set #test_files to
files
, ensuring it is an array.
# File rubygems/specification.rb, line 1831 def test_files= files @test_files = Array files end
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.
# File rubygems/specification.rb, line 1851 def to_ruby mark_version result = [] result << "# -*- encoding: utf-8 -*-" result << nil result << "Gem::Specification.new do |s|" result << " s.name = #{ruby_code name}" result << " s.version = #{ruby_code version}" unless platform.nil? or platform == Gem::Platform::RUBY then result << " s.platform = #{ruby_code original_platform}" end result << "" result << " s.required_rubygems_version = #{ruby_code required_rubygems_version} if s.respond_to? :required_rubygems_version=" handled = [ :dependencies, :name, :platform, :required_rubygems_version, :specification_version, :version, :has_rdoc, :default_executable, ] @@attributes.each do |attr_name| next if handled.include? attr_name current_value = self.send(attr_name) if current_value != default_value(attr_name) or self.class.required_attribute? attr_name then result << " s.#{attr_name} = #{ruby_code current_value}" end end result << nil result << " if s.respond_to? :specification_version then" result << " s.specification_version = #{specification_version}" result << nil result << " if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then" dependencies.each do |dep| req = dep.requirements_list.inspect dep.instance_variable_set :@type, :runtime if dep.type.nil? # HACK result << " s.add_#{dep.type}_dependency(%q<#{dep.name}>, #{req})" end result << " else" dependencies.each do |dep| version_reqs_param = dep.requirements_list.inspect result << " s.add_dependency(%q<#{dep.name}>, #{version_reqs_param})" end result << ' end' result << " else" dependencies.each do |dep| version_reqs_param = dep.requirements_list.inspect result << " s.add_dependency(%q<#{dep.name}>, #{version_reqs_param})" end result << " end" result << "end" result << nil result.join "\n" end
Returns a Ruby lighter-weight code representation of this specification, used for indexing only.
See to_ruby.
# File rubygems/specification.rb, line 1927 def to_ruby_for_cache for_cache.to_ruby end
Recursively walk dependencies of this spec, executing the
block
for each hop.
# File rubygems/specification.rb, line 1966 def traverse trail = [], &block trail = trail + [self] runtime_dependencies.each do |dep| dep.to_specs.each do |dep_spec| block[self, dep, dep_spec, trail + [dep_spec]] dep_spec.traverse(trail, &block) unless trail.map(&:name).include? dep_spec.name end end end
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..
# File rubygems/specification.rb, line 1984 def validate packaging = true require 'rubygems/user_interaction' extend Gem::UserInteraction normalize nil_attributes = self.class.non_nil_attributes.find_all do |name| instance_variable_get("@#{name}").nil? end unless nil_attributes.empty? then raise Gem::InvalidSpecificationException, "#{nil_attributes.join ', '} must not be nil" end if packaging and rubygems_version != Gem::VERSION then raise Gem::InvalidSpecificationException, "expected RubyGems version #{Gem::VERSION}, was #{rubygems_version}" end @@required_attributes.each do |symbol| unless self.send symbol then raise Gem::InvalidSpecificationException, "missing value for attribute #{symbol}" end end unless String === name then raise Gem::InvalidSpecificationException, "invalid value for attribute name: \"#{name.inspect}\"" end if require_paths.empty? then raise Gem::InvalidSpecificationException, 'specification must have at least one require_path' end @files.delete_if { |x| File.directory?(x) } @test_files.delete_if { |x| File.directory?(x) } @executables.delete_if { |x| File.directory?(File.join(@bindir, x)) } @extra_rdoc_files.delete_if { |x| File.directory?(x) } @extensions.delete_if { |x| File.directory?(x) } non_files = files.reject { |x| File.file?(x) } unless not packaging or non_files.empty? then raise Gem::InvalidSpecificationException, "[\"#{non_files.join "\", \""}\"] are not files" end unless specification_version.is_a?(Fixnum) raise Gem::InvalidSpecificationException, 'specification_version must be a Fixnum (did you mean version?)' end case platform when Gem::Platform, Gem::Platform::RUBY then # ok else raise Gem::InvalidSpecificationException, "invalid platform #{platform.inspect}, see Gem::Platform" end self.class.array_attributes.each do |field| val = self.send field klass = case field when :dependencies Gem::Dependency else String end unless Array === val and val.all? { |x| x.kind_of?(klass) } then raise(Gem::InvalidSpecificationException, "#{field} must be an Array of #{klass}") end end [:authors].each do |field| val = self.send field raise Gem::InvalidSpecificationException, "#{field} may not be empty" if val.empty? end licenses.each { |license| if license.length > 64 raise Gem::InvalidSpecificationException, "each license must be 64 characters or less" end } # reject lazy developers: lazy = '"FIxxxXME" or "TOxxxDO"'.gsub(/xxx/, '') unless authors.grep(/FI XME|TO DO/x).empty? then raise Gem::InvalidSpecificationException, "#{lazy} is not an author" end unless Array(email).grep(/FI XME|TO DO/x).empty? then raise Gem::InvalidSpecificationException, "#{lazy} is not an email" end if description =~ /FI XME|TO DO/x then raise Gem::InvalidSpecificationException, "#{lazy} is not a description" end if summary =~ /FI XME|TO DO/x then raise Gem::InvalidSpecificationException, "#{lazy} is not a summary" end if homepage and not homepage.empty? and homepage !~ /\A[a-z][a-z\d+.-]*:/i then raise Gem::InvalidSpecificationException, "\"#{homepage}\" is not a URI" end # Warnings %w[author description email homepage summary].each do |attribute| value = self.send attribute alert_warning "no #{attribute} specified" if value.nil? or value.empty? end if description == summary then alert_warning 'description and summary are identical' end # TODO: raise at some given date alert_warning "deprecated autorequire specified" if autorequire executables.each do |executable| executable_path = File.join(bindir, executable) shebang = File.read(executable_path, 2) == '#!' alert_warning "#{executable_path} is missing #! line" unless shebang end true end
Set the version to version
, potentially also setting #required_rubygems_version
if version
indicates it is a prerelease.
# File rubygems/specification.rb, line 2128 def version= version @version = Gem::Version.create(version) self.required_rubygems_version = '> 1.3.1' if @version.prerelease? return @version end
Paths in the gem to add to $LOAD_PATH when this gem is activated.
The default [‘lib’] is typically sufficient.
The version of RubyGems used to create this gem.
Do not set this, it is set automatically when the gem is packaged.
The Gem::Specification version of this gemspec.
Do not set this, it is set automatically when the gem is packaged.
Commenting is here to help enhance the documentation. For example, code samples, or clarification of the documentation.
If you have questions about Ruby or the documentation, please post to one of the Ruby mailing lists. You will get better, faster, help that way.
If you wish to post a correction of the docs, please do so, but also file bug report so that it can be corrected for the next release. Thank you.
If you want to help improve the Ruby documentation, please visit Documenting-ruby.org.