Module: Gem

Defined in:
lib/rubygems.rb,
lib/rubygems.rb,
lib/gemconfigure.rb,
lib/rubygems/builder.rb,
lib/rubygems/command.rb,
lib/rubygems/version.rb,
lib/rubygems/security.rb,
lib/rubygems/security.rb,
lib/rubygems/installer.rb,
lib/rubygems/validator.rb,
lib/rubygems/gem_runner.rb,
lib/rubygems/old_format.rb,
lib/rubygems/cmd_manager.rb,
lib/rubygems/config_file.rb,
lib/rubygems/doc_manager.rb,
lib/rubygems/gem_openssl.rb,
lib/rubygems/gem_commands.rb,
lib/rubygems/gem_commands.rb,
lib/rubygems/source_index.rb,
lib/rubygems/specification.rb,
lib/rubygems/custom_require.rb,
lib/rubygems/dependency_list.rb,
lib/rubygems/remote_installer.rb,
lib/rubygems/rubygems_version.rb,
lib/rubygems/user_interaction.rb

Overview

– Copyright 2006 by Chad Fowler, Rich Kilmer, Jim Weirich and others. All rights reserved. See LICENSE.txt for permissions. ++

Defined Under Namespace

Modules: CommandAids, DefaultUserInteraction, InstallUpdateOptions, LocalRemoteOptions, Platform, SSL, Security, UserInteraction, VersionOption Classes: BuildCommand, Builder, CertCommand, CheckCommand, CleanupCommand, Command, CommandLineError, CommandManager, ConfigFile, ConsoleUI, ContentsCommand, Dependency, DependencyCommand, DependencyError, DependencyList, DependencyRemovalException, DocManager, DocumentError, EndOfYAMLException, EnvironmentCommand, Exception, ExtBuilder, ExtConfigureBuilder, ExtExtConfBuilder, ExtRakeBuilder, FilePermissionError, FormatException, GemNotFoundException, GemPathSearcher, GemRunner, HelpCommand, InstallCommand, InstallError, Installer, InvalidSpecificationException, ListCommand, LoadError, LocalInstallationError, OldFormat, OperationNotSupportedError, OutdatedCommand, PristineCommand, QueryCommand, RDocCommand, RemoteError, RemoteFetcher, RemoteInstallationCancelled, RemoteInstallationSkipped, RemoteInstaller, RemoteSourceException, Requirement, SearchCommand, Server, SilentUI, SourceIndex, SourceInfoCache, SourceInfoCacheEntry, SourcesCommand, Specification, SpecificationCommand, StreamUI, UninstallCommand, Uninstaller, UnpackCommand, UpdateCommand, Validator, VerificationError, Version

Constant Summary collapse

MUTEX = 
Mutex.new
RubyGemsPackageVersion = 
RubyGemsVersion
DIRECTORIES = 
['cache', 'doc', 'gems', 'specifications']
HELP = 
%{
RubyGems is a sophisticated package manager for Ruby.  This is a
basic help message containing pointers to more information.

  Usage:
    gem -h/--help
    gem -v/--version
    gem command [arguments...] [options...]

  Examples:
    gem install rake
    gem list --local
    gem build package.gemspec
    gem help install

  Further help:
    gem help commands            list all 'gem' commands
    gem help examples            show some examples of usage
    gem help <COMMAND>           show help on COMMAND
                                   (e.g. 'gem help install')
  Further information:
    http://rubygems.rubyforge.org
}.gsub(/^    /, "")
EXAMPLES = 
%{
Some examples of 'gem' usage.

* Install 'rake', either from local directory or remote server:

    gem install rake

* Install 'rake', only from remote server:

    gem install rake --remote

* Install 'rake' from remote server, and run unit tests,
  and generate RDocs:

    gem install --remote rake --test --rdoc --ri

* Install 'rake', but only version 0.3.1, even if dependencies
  are not met, and into a specific directory:

    gem install rake --version 0.3.1 --force --install-dir $HOME/.gems

* List local gems whose name begins with 'D':

    gem list D

* List local and remote gems whose name contains 'log':

    gem search log --both

* List only remote gems whose name contains 'log':

    gem search log --remote

* Uninstall 'rake':

    gem uninstall rake

* Create a gem:

    See http://rubygems.rubyforge.org/wiki/wiki.pl?CreateAGemInTenMinutes

* See information about RubyGems:

    gem environment

}.gsub(/^    /, "")
Cache =

Cache is an alias for SourceIndex to allow older YAMLized source index objects to load properly.

SourceIndex
RubyGemsVersion = 
'0.9.2'
@@source_index = 
nil

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.loaded_specs ⇒ Object (readonly)

Returns the value of attribute loaded_specs.



106
107
108
 
# File 'lib/rubygems.rb', line 106

def loaded_specs
  @loaded_specs
end

.ssl_available=(value) ⇒ Object (writeonly)

Set the value of the ssl_avilable flag.



22
23
24
 
# File 'lib/rubygems/gem_openssl.rb', line 22

def ssl_available=(value)
  @ssl_available = value
end

Class Method Details

.activate(gem, autorequire, *version_requirements) ⇒ Object

Activate a gem (i.e. add it to the Ruby load path). The gem must satisfy all the specified version constraints. If autorequire is true, then automatically require the specified autorequire file in the gem spec.

Returns true if the gem is loaded by this call, false if it is already loaded, or an exception otherwise.



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/rubygems.rb', line 229

def activate(gem, autorequire, *version_requirements)
  unless version_requirements.size > 0
    version_requirements = [">= 0.0.0"]
  end
  unless gem.respond_to?(:name) && gem.respond_to?(:version_requirements)
    gem = Gem::Dependency.new(gem, version_requirements)
  end

  matches = Gem.source_index.find_name(gem.name, gem.version_requirements)
  report_activate_error(gem) if matches.empty?

  if @loaded_specs[gem.name]
    # This gem is already loaded.  If the currently loaded gem is
    # not in the list of candidate gems, then we have a version
    # conflict.
    existing_spec = @loaded_specs[gem.name]
    if ! matches.any? { |spec| spec.version == existing_spec.version }
      fail Gem::Exception, "can't activate #{gem}, already activated #{existing_spec.full_name}]"
    end
    return false
  end

  # new load
  spec = matches.last
  if spec.loaded?
    return false unless autorequire
    result = spec.autorequire ? require(spec.autorequire) : false
    return result || false 
  end

  spec.loaded = true
  @loaded_specs[spec.name] = spec
  
  # Load dependent gems first
  spec.dependencies.each do |dep_gem|
    activate(dep_gem, autorequire)
  end
  
  # add bin dir to require_path
  if(spec.bindir) then
    spec.require_paths << spec.bindir
  end
  
  # Now add the require_paths to the LOAD_PATH
  spec.require_paths.each do |path|
    $:.unshift File.join(spec.full_gem_path, path)
  end
  
  if autorequire && spec.autorequire then
    Array(spec.autorequire).each do |a_lib|
      require a_lib
    end
  end

  return true
end

.all_load_paths ⇒ Object

Return a list of all possible load paths for all versions for all gems in the Gem installation.



327
328
329
330
331
332
333
334
335
 
# File 'lib/rubygems.rb', line 327

def all_load_paths
  result = []
  Gem.path.each do |gemdir|
    each_load_path(all_partials(gemdir)) do |load_path|
      result << load_path
    end
  end
  result
end

.bindir(install_dir = Gem.dir) ⇒ Object

The directory path where executables are to be installed.



144
145
146
147
148
149
150
151
152
153
 
# File 'lib/rubygems.rb', line 144

def bindir(install_dir=Gem.dir)
  return File.join(install_dir, 'bin') unless install_dir == Gem.default_dir

  if defined? RUBY_FRAMEWORK_VERSION then # mac framework support
    File.join(File.dirname(Config::CONFIG["sitedir"]),
              File.basename(Config::CONFIG["bindir"]))
  else # generic install
    Config::CONFIG['bindir']
  end
end

.clear_paths ⇒ Object

Reset the dir and path values. The next time dir or path is requested, the values will be calculated from scratch. This is mainly used by the unit tests to provide test isolation.



309
310
311
312
313
 
# File 'lib/rubygems.rb', line 309

def clear_paths
  @gem_home = nil
  @gem_path = nil
  @@source_index = nil  
end

.config_file ⇒ Object

Return the path to standard location of the users .gemrc file.



171
172
173
 
# File 'lib/rubygems.rb', line 171

def config_file
  File.join(Gem.user_home, '.gemrc')
end

.configuration ⇒ Object

The standard configuration object for gems.



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/rubygems.rb', line 176

def configuration
  return @configuration if @configuration

  @configuration = {}
  class << @configuration
    undef_method :verbose # HACK RakeFileUtils pollution
  end if @configuration.respond_to? :verbose

  def @configuration.method_missing(sym, *args, &block)
    if args.empty?
      self[sym]
    else
      super
    end
  end

  @configuration
end

.configuration=(config) ⇒ Object

Use the given configuration object (which implements the ConfigFile protocol) as the standard configuration object.



197
198
199
 
# File 'lib/rubygems.rb', line 197

def configuration=(config)
  @configuration = config
end

.configure(gem_pairs, options = {}) ⇒ Object

Activate the gems specfied by the gem_pairs list.

gem_pairs

List of gem/version pairs. Eg. [[‘rake’, ‘= 0.8.15’], [‘RedCloth’, ‘~> 3.0’]]

options

options => print gems as they are required.



17
18
19
20
21
22
23
 
# File 'lib/gemconfigure.rb', line 17

def self.configure(gem_pairs, options={})
  gem_pairs.each do |name, version|
    require 'rubygems' 
    puts "Activating gem #{name} (version #{version})" if options[:verbose]
    gem name, version
  end
end

.datadir(gem_name) ⇒ Object

Return the path the the data directory specified by the gem name. If the package is not available as a gem, return nil.



203
204
205
206
207
 
# File 'lib/rubygems.rb', line 203

def datadir(gem_name)
  spec = @loaded_specs[gem_name]
  return nil if spec.nil?
  File.join(spec.full_gem_path, 'data', gem_name)
end

.default_dir ⇒ Object

Default home directory path to be used if an alternate value is not specified in the environment.



457
458
459
460
461
462
463
 
# File 'lib/rubygems.rb', line 457

def default_dir
  if defined? RUBY_FRAMEWORK_VERSION
    return File.join(File.dirname(Config::CONFIG["sitedir"]), "Gems")
  else
    File.join(Config::CONFIG['libdir'], 'ruby', 'gems', Config::CONFIG['ruby_version'])
  end
end

.dir ⇒ Object

The directory path where Gems are to be installed.

return
String

The directory path



136
137
138
139
140
 
# File 'lib/rubygems.rb', line 136

def dir
  @gem_home ||= nil
  set_home(ENV['GEM_HOME'] || default_dir) unless @gem_home
  @gem_home
end

.ensure_ssl_available ⇒ Object

Ensure that SSL is available. Throw an exception if it is not.



25
26
27
28
29
 
# File 'lib/rubygems/gem_openssl.rb', line 25

def ensure_ssl_available
  unless ssl_available?
    fail Gem::Exception, "SSL is not installed on this system"
  end
end

.latest_load_paths ⇒ Object

Return a list of all possible load paths for the latest version for all gems in the Gem installation.



339
340
341
342
343
344
345
346
347
 
# File 'lib/rubygems.rb', line 339

def latest_load_paths
  result = []
  Gem.path.each do |gemdir|
    each_load_path(latest_partials(gemdir)) do |load_path|
      result << load_path
    end
  end
  result
end

.manage_gems ⇒ Object 



108
109
110
111
112
113
114
115
116
117
118
119
 
# File 'lib/rubygems.rb', line 108

def manage_gems
  require 'rubygems/user_interaction'
  require 'rubygems/builder'
  require 'rubygems/format'
  require 'rubygems/remote_installer'
  require 'rubygems/installer'
  require 'rubygems/validator'
  require 'rubygems/doc_manager'
  require 'rubygems/cmd_manager'
  require 'rubygems/gem_runner'
  require 'rubygems/config_file'
end

.method_missing(sym, *args, &block) ⇒ Object 



184
185
186
187
188
189
190
 
# File 'lib/rubygems.rb', line 184

def @configuration.method_missing(sym, *args, &block)
  if args.empty?
    self[sym]
  else
    super
  end
end

.path ⇒ Object

List of directory paths to search for Gems.

return
List<String>

List of directory paths.



159
160
161
162
163
 
# File 'lib/rubygems.rb', line 159

def path
  @gem_path ||= nil
  set_paths(ENV['GEM_PATH']) unless @gem_path
  @gem_path
end

.report_activate_error(gem) ⇒ Object

Report a load error during activation. The message of load error depends on whether it was a version mismatch or if there are not gems of any version by the requested name.



289
290
291
292
293
294
295
296
297
298
299
300
301
302
 
# File 'lib/rubygems.rb', line 289

def report_activate_error(gem)
  matches = Gem.source_index.find_name(gem.name)
  if matches.size==0
    error = Gem::LoadError.new(
      "Could not find RubyGem #{gem.name} (#{gem.version_requirements})\n")
  else
    error = Gem::LoadError.new(
      "RubyGem version error: " +
      "#{gem.name}(#{matches.first.version} not #{gem.version_requirements})\n")
  end
  error.name = gem.name
  error.version_requirement = gem.version_requirements
  raise error
end

.required_location(gemname, libfile, *version_constraints) ⇒ Object 



349
350
351
352
353
354
355
356
357
358
359
 
# File 'lib/rubygems.rb', line 349

def required_location(gemname, libfile, *version_constraints)
  version_constraints = [">0"] if version_constraints.empty?
  matches = Gem.source_index.find_name(gemname, version_constraints)
  return nil if matches.empty?
  spec = matches.last
  spec.require_paths.each do |path|
    result = File.join(spec.full_gem_path, path, libfile)
    return result if File.exists?(result)
  end
  nil
end

.ruby ⇒ Object

Return the Ruby command to use to execute the Ruby interpreter.



217
218
219
 
# File 'lib/rubygems.rb', line 217

def ruby
  "ruby"
end

.searcher ⇒ Object

Return the searcher object to search for matching gems.



210
211
212
213
214
 
# File 'lib/rubygems.rb', line 210

def searcher
  MUTEX.synchronize do
    @searcher ||= Gem::GemPathSearcher.new
  end
end

.source_index ⇒ Object Also known as: cache

Returns an Cache of specifications that are in the Gem.path

return
Gem::SourceIndex

Index of installed Gem::Specifications



125
126
127
 
# File 'lib/rubygems.rb', line 125

def source_index
  @@source_index ||= SourceIndex.from_installed_gems
end

.ssl_available? ⇒ Boolean

Is SSL (used by the signing commands) available on this platform?

Returns:

  • (Boolean) 


16
17
18
19
 
# File 'lib/rubygems/gem_openssl.rb', line 16

def ssl_available?
  require 'rubygems/gem_openssl'
  @ssl_available
end

.suffix_pattern ⇒ Object 



365
366
367
 
# File 'lib/rubygems.rb', line 365

def suffix_pattern
  @suffix_pattern ||= "{#{suffixes.join(',')}}"
end

.suffixes ⇒ Object 



361
362
363
 
# File 'lib/rubygems.rb', line 361

def suffixes
  ['', '.rb', '.rbw', '.so', '.bundle', '.dll', '.sl', '.jar']
end

.use_paths(home, paths = []) ⇒ Object

Use the home and (optional) paths values for dir and path. Used mainly by the unit tests to provide environment isolation.



318
319
320
321
322
 
# File 'lib/rubygems.rb', line 318

def use_paths(home, paths=[])
  clear_paths
  set_home(home) if home
  set_paths(paths.join(File::PATH_SEPARATOR)) if paths
end

.user_home ⇒ Object

The home directory for the user.



166
167
168
 
# File 'lib/rubygems.rb', line 166

def user_home
  @user_home ||= find_home
end