rubygems.rb

Path: lib/rubygems.rb
Last Update: Thu Sep 06 23:29:51 +0000 2012

Required files

rubygems/defaults   rbconfig   thread   zlib   fileutils   stringio   zlib   stringio   zlib   zlib   psych   yaml   sources   rubygems/user_interaction  

Methods

Constants

DIRECTORIES = %w[cache doc gems specifications] unless defined?(DIRECTORIES)   Default directories in a gem repository
RubyGemsPackageVersion = VERSION
WIN_PATTERNS = [ /bccwin/i, /cygwin/i, /djgpp/i, /mingw/i, /mswin/i, /wince/i, ]   An Array of Regexps that match windows ruby platforms.
MARSHAL_SPEC_DIR = "quick/Marshal.#{Gem.marshal_version}/"   Location of Marshal quick gemspecs on remote repositories

Public Class methods

Activates an installed gem matching gem. The gem must satisfy requirements.

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

Gem#activate adds the library paths in gem to $LOAD_PATH. Before a Gem is activated its required Gems are activated. If the version information is omitted, the highest version Gem of the supplied name is loaded. If a Gem is not found that meets the version requirements or a required Gem is not found, a Gem::LoadError is raised.

More information on version requirements can be found in the Gem::Requirement and Gem::Version documentation.

[Source]

     # File lib/rubygems.rb, line 236
236:   def self.activate(gem, *requirements)
237:     if requirements.last.is_a?(Hash)
238:       options = requirements.pop
239:     else
240:       options = {}
241:     end
242: 
243:     sources = options[:sources] || []
244: 
245:     if requirements.empty? then
246:       requirements = Gem::Requirement.default
247:     end
248: 
249:     unless gem.respond_to?(:name) and
250:            gem.respond_to?(:requirement) then
251:       gem = Gem::Dependency.new(gem, requirements)
252:     end
253: 
254:     matches = Gem.source_index.find_name(gem.name, gem.requirement)
255:     report_activate_error(gem) if matches.empty?
256: 
257:     if @loaded_specs[gem.name] then
258:       # This gem is already loaded.  If the currently loaded gem is not in the
259:       # list of candidate gems, then we have a version conflict.
260:       existing_spec = @loaded_specs[gem.name]
261: 
262:       unless matches.any? { |spec| spec.version == existing_spec.version } then
263:          sources_message = sources.map { |spec| spec.full_name }
264:          stack_message = @loaded_stacks[gem.name].map { |spec| spec.full_name }
265: 
266:          msg = "can't activate #{gem} for #{sources_message.inspect}, "
267:          msg << "already activated #{existing_spec.full_name} for "
268:          msg << "#{stack_message.inspect}"
269: 
270:          e = Gem::LoadError.new msg
271:          e.name = gem.name
272:          e.requirement = gem.requirement
273: 
274:          raise e
275:       end
276: 
277:       return false
278:     end
279: 
280:     # new load
281:     spec = matches.last
282:     return false if spec.loaded?
283: 
284:     spec.loaded = true
285:     @loaded_specs[spec.name] = spec
286:     @loaded_stacks[spec.name] = sources.dup
287: 
288:     # Load dependent gems first
289:     spec.runtime_dependencies.each do |dep_gem|
290:       activate dep_gem, :sources => [spec, *sources]
291:     end
292: 
293:     require_paths = spec.require_paths.map do |path|
294:       File.join spec.full_gem_path, path
295:     end
296: 
297:     # gem directories must come after -I and ENV['RUBYLIB']
298:     insert_index = load_path_insert_index
299: 
300:     if insert_index then
301:       # gem directories must come after -I and ENV['RUBYLIB']
302:       $LOAD_PATH.insert(insert_index, *require_paths)
303:     else
304:       # we are probably testing in core, -I and RUBYLIB don't apply
305:       $LOAD_PATH.unshift(*require_paths)
306:     end
307: 
308:     return true
309:   end

An Array of all possible load paths for all versions of all gems in the Gem installation.

[Source]

     # File lib/rubygems.rb, line 315
315:   def self.all_load_paths
316:     result = []
317: 
318:     Gem.path.each do |gemdir|
319:       each_load_path all_partials(gemdir) do |load_path|
320:         result << load_path
321:       end
322:     end
323: 
324:     result
325:   end

See if a given gem is available.

[Source]

     # File lib/rubygems.rb, line 339
339:   def self.available?(gem, *requirements)
340:     requirements = Gem::Requirement.default if requirements.empty?
341: 
342:     unless gem.respond_to?(:name) and
343:            gem.respond_to?(:requirement) then
344:       gem = Gem::Dependency.new gem, requirements
345:     end
346: 
347:     !Gem.source_index.search(gem).empty?
348:   end

Find the full path to the executable for gem name. If the exec_name is not given, the gem‘s default_executable is chosen, otherwise the specified executable‘s path is returned. requirements allows you to specify specific gem versions.

[Source]

     # File lib/rubygems.rb, line 356
356:   def self.bin_path(name, exec_name = nil, *requirements)
357:     requirements = Gem::Requirement.default if
358:       requirements.empty?
359:     specs = Gem.source_index.find_name(name, requirements)
360: 
361:     raise Gem::GemNotFoundException,
362:           "can't find gem #{name} (#{requirements})" if specs.empty?
363: 
364:     specs = specs.find_all do |spec|
365:       spec.executables.include?(exec_name)
366:     end if exec_name
367: 
368:     unless spec = specs.last
369:       msg = "can't find gem #{name} (#{requirements}) with executable #{exec_name}"
370:       raise Gem::GemNotFoundException, msg
371:     end
372: 
373:     exec_name ||= spec.default_executable
374: 
375:     unless exec_name
376:       msg = "no default executable for #{spec.full_name} and none given"
377:       raise Gem::Exception, msg
378:     end
379: 
380:     File.join(spec.full_gem_path, spec.bindir, exec_name)
381:   end

The mode needed to read a file as straight binary.

[Source]

     # File lib/rubygems.rb, line 386
386:   def self.binary_mode
387:     'rb'
388:   end

The path where gem executables are to be installed.

[Source]

     # File lib/rubygems.rb, line 393
393:   def self.bindir(install_dir=Gem.dir)
394:     return File.join(install_dir, 'bin') unless
395:       install_dir.to_s == Gem.default_dir
396:     Gem.default_bindir
397:   end

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.

[Source]

     # File lib/rubygems.rb, line 404
404:   def self.clear_paths
405:     @gem_home = nil
406:     @gem_path = nil
407:     @user_home = nil
408: 
409:     @@source_index = nil
410: 
411:     @searcher = nil
412:   end

The path to standard location of the user‘s .gemrc file.

[Source]

     # File lib/rubygems.rb, line 417
417:   def self.config_file
418:     File.join Gem.user_home, '.gemrc'
419:   end

The standard configuration object for gems.

[Source]

     # File lib/rubygems.rb, line 424
424:   def self.configuration
425:     @configuration ||= Gem::ConfigFile.new []
426:   end

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

[Source]

     # File lib/rubygems.rb, line 432
432:   def self.configuration=(config)
433:     @configuration = config
434:   end

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

[Source]

     # File lib/rubygems.rb, line 440
440:   def self.datadir(gem_name)
441:     spec = @loaded_specs[gem_name]
442:     return nil if spec.nil?
443:     File.join(spec.full_gem_path, 'data', gem_name)
444:   end

A Zlib::Deflate.deflate wrapper

[Source]

     # File lib/rubygems.rb, line 449
449:   def self.deflate(data)
450:     require 'zlib'
451:     Zlib::Deflate.deflate data
452:   end

The path where gems are to be installed.

[Source]

     # File lib/rubygems.rb, line 457
457:   def self.dir
458:     @gem_home ||= nil
459:     set_home(ENV['GEM_HOME'] || default_dir) unless @gem_home
460:     @gem_home
461:   end

Quietly ensure the named Gem directory contains all the proper subdirectories. If we can‘t create a directory due to a permission problem, then we will silently continue.

[Source]

     # File lib/rubygems.rb, line 490
490:   def self.ensure_gem_subdirectories(gemdir)
491:     require 'fileutils'
492: 
493:     Gem::DIRECTORIES.each do |filename|
494:       fn = File.join gemdir, filename
495:       FileUtils.mkdir_p fn rescue nil unless File.exist? fn
496:     end
497:   end

Returns a list of paths matching glob that can be used by a gem to pick up features from other gems. For example:

  Gem.find_files('rdoc/discover').each do |path| load path end

if check_load_path is true (the default), then find_files also searches $LOAD_PATH for files as well as gems.

Note that find_files will return all files even if they are from different versions of the same gem.

[Source]

     # File lib/rubygems.rb, line 511
511:   def self.find_files(glob, check_load_path=true)
512:     files = []
513: 
514:     if check_load_path
515:       files = $LOAD_PATH.map { |load_path|
516:         Dir["#{File.expand_path glob, load_path}#{Gem.suffix_pattern}"]
517:       }.flatten.select { |file| File.file? file.untaint }
518:     end
519: 
520:     specs = searcher.find_all glob
521: 
522:     specs.each do |spec|
523:       files.concat searcher.matching_files(spec, glob)
524:     end
525: 
526:     # $LOAD_PATH might contain duplicate entries or reference
527:     # the spec dirs directly, so we prune.
528:     files.uniq! if check_load_path
529: 
530:     return files
531:   end

Zlib::GzipReader wrapper that unzips data.

[Source]

     # File lib/rubygems.rb, line 570
570:   def self.gunzip(data)
571:     require 'stringio'
572:     require 'zlib'
573:     data = StringIO.new data
574: 
575:     Zlib::GzipReader.new(data).read
576:   end

Zlib::GzipWriter wrapper that zips data.

[Source]

     # File lib/rubygems.rb, line 581
581:   def self.gzip(data)
582:     require 'stringio'
583:     require 'zlib'
584:     zipped = StringIO.new
585: 
586:     Zlib::GzipWriter.wrap zipped do |io| io.write data end
587: 
588:     zipped.string
589:   end

Get the default RubyGems API host. This is normally rubygems.org.

[Source]

     # File lib/rubygems.rb, line 603
603:   def self.host
604:     @host ||= "https://rubygems.org"
605:   end

Set the default RubyGems API host.

[Source]

     # File lib/rubygems.rb, line 609
609:   def self.host= host
610:     @host = host
611:   end

A Zlib::Inflate#inflate wrapper

[Source]

     # File lib/rubygems.rb, line 594
594:   def self.inflate(data)
595:     require 'zlib'
596:     Zlib::Inflate.inflate data
597:   end

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

[Source]

     # File lib/rubygems.rb, line 617
617:   def self.latest_load_paths
618:     result = []
619: 
620:     Gem.path.each do |gemdir|
621:       each_load_path(latest_partials(gemdir)) do |load_path|
622:         result << load_path
623:       end
624:     end
625: 
626:     result
627:   end

Find all ‘rubygems_plugin’ files in $LOAD_PATH and load them

[Source]

      # File lib/rubygems.rb, line 1096
1096:   def self.load_env_plugins
1097:     path = "rubygems_plugin"
1098: 
1099:     files = []
1100:     $LOAD_PATH.each do |load_path|
1101:       globbed = Dir["#{File.expand_path path, load_path}#{Gem.suffix_pattern}"]
1102: 
1103:       globbed.each do |load_path_file|
1104:         files << load_path_file if File.file?(load_path_file.untaint)
1105:       end
1106:     end
1107: 
1108:     load_plugin_files files
1109:   end

The index to insert activated gem paths into the $LOAD_PATH.

Defaults to the site lib directory unless gem_prelude.rb has loaded paths, then it inserts the activated gem‘s paths before the gem_prelude.rb paths so you can override the gem_prelude.rb default $LOAD_PATH paths.

[Source]

     # File lib/rubygems.rb, line 656
656:   def self.load_path_insert_index
657:     index = $LOAD_PATH.index ConfigMap[:sitelibdir]
658: 
659:     if QUICKLOADER_SUCKAGE then
660:       $LOAD_PATH.each_with_index do |path, i|
661:         if path.instance_variables.include?(:@gem_prelude_index) or
662:             path.instance_variables.include?('@gem_prelude_index') then
663:           index = i
664:           break
665:         end
666:       end
667:     end
668: 
669:     index
670:   end

Load plugins as ruby files

[Source]

      # File lib/rubygems.rb, line 1069
1069:   def self.load_plugin_files(plugins)
1070:     plugins.each do |plugin|
1071: 
1072:       # Skip older versions of the GemCutter plugin: Its commands are in
1073:       # RubyGems proper now.
1074: 
1075:       next if plugin =~ /gemcutter-0\.[0-3]/
1076: 
1077:       begin
1078:         load plugin
1079:       rescue ::Exception => e
1080:         details = "#{plugin.inspect}: #{e.message} (#{e.class})"
1081:         warn "Error loading RubyGems plugin #{details}"
1082:       end
1083:     end
1084:   end

Find all ‘rubygems_plugin’ files in installed gems and load them

[Source]

      # File lib/rubygems.rb, line 1089
1089:   def self.load_plugins
1090:     load_plugin_files find_files('rubygems_plugin', false)
1091:   end

Loads YAML, preferring Psych

[Source]

     # File lib/rubygems.rb, line 675
675:   def self.load_yaml
676:     require 'psych'
677:   rescue ::LoadError
678:   ensure
679:     require 'yaml'
680:   end

The file name and line number of the caller of the caller of this method.

[Source]

     # File lib/rubygems.rb, line 685
685:   def self.location_of_caller
686:     caller[1] =~ /(.*?):(\d+).*?$/i
687:     file = $1
688:     lineno = $2.to_i
689: 
690:     [file, lineno]
691:   end

The version of the Marshal format for your Ruby.

[Source]

     # File lib/rubygems.rb, line 696
696:   def self.marshal_version
697:     "#{Marshal::MAJOR_VERSION}.#{Marshal::MINOR_VERSION}"
698:   end

Array of paths to search for Gems.

[Source]

     # File lib/rubygems.rb, line 703
703:   def self.path
704:     @gem_path ||= nil
705: 
706:     unless @gem_path then
707:       paths = [ENV['GEM_PATH'] || default_path]
708: 
709:       if defined?(APPLE_GEM_HOME) and not ENV['GEM_PATH'] then
710:         paths << APPLE_GEM_HOME
711:       end
712: 
713:       set_paths paths.compact.join(File::PATH_SEPARATOR)
714:     end
715: 
716:     @gem_path
717:   end

Array of platforms this RubyGems supports.

[Source]

     # File lib/rubygems.rb, line 729
729:   def self.platforms
730:     @platforms ||= []
731:     if @platforms.empty?
732:       @platforms = [Gem::Platform::RUBY, Gem::Platform.local]
733:     end
734:     @platforms
735:   end

Set array of platforms this RubyGems supports (primarily for testing).

[Source]

     # File lib/rubygems.rb, line 722
722:   def self.platforms=(platforms)
723:     @platforms = platforms
724:   end

Adds a post-build hook that will be passed an Gem::Installer instance when Gem::Installer#install is called. The hook is called after the gem has been extracted and extensions have been built but before the executables or gemspec has been written. If the hook returns false then the gem‘s files will be removed and the install will be aborted.

[Source]

     # File lib/rubygems.rb, line 744
744:   def self.post_build(&hook)
745:     @post_build_hooks << hook
746:   end

Adds a post-install hook that will be passed an Gem::Installer instance when Gem::Installer#install is called

[Source]

     # File lib/rubygems.rb, line 752
752:   def self.post_install(&hook)
753:     @post_install_hooks << hook
754:   end

Adds a post-uninstall hook that will be passed a Gem::Uninstaller instance and the spec that was uninstalled when Gem::Uninstaller#uninstall is called

[Source]

     # File lib/rubygems.rb, line 761
761:   def self.post_uninstall(&hook)
762:     @post_uninstall_hooks << hook
763:   end

Adds a pre-install hook that will be passed an Gem::Installer instance when Gem::Installer#install is called. If the hook returns false then the install will be aborted.

[Source]

     # File lib/rubygems.rb, line 770
770:   def self.pre_install(&hook)
771:     @pre_install_hooks << hook
772:   end

Adds a pre-uninstall hook that will be passed an Gem::Uninstaller instance and the spec that will be uninstalled when Gem::Uninstaller#uninstall is called

[Source]

     # File lib/rubygems.rb, line 779
779:   def self.pre_uninstall(&hook)
780:     @pre_uninstall_hooks << hook
781:   end

The directory prefix this RubyGems was installed at.

[Source]

     # File lib/rubygems.rb, line 786
786:   def self.prefix
787:     dir = File.dirname File.expand_path(__FILE__)
788:     prefix = File.dirname dir
789: 
790:     if prefix == File.expand_path(ConfigMap[:sitelibdir]) or
791:        prefix == File.expand_path(ConfigMap[:libdir]) or
792:        'lib' != File.basename(dir) then
793:       nil
794:     else
795:       prefix
796:     end
797:   end

Promotes the load paths of the gem_name over the load paths of over_name. Useful for allowing one gem to override features in another using find_files.

[Source]

     # File lib/rubygems.rb, line 804
804:   def self.promote_load_path(gem_name, over_name)
805:     gem = Gem.loaded_specs[gem_name]
806:     over = Gem.loaded_specs[over_name]
807: 
808:     raise ArgumentError, "gem #{gem_name} is not activated" if gem.nil?
809:     raise ArgumentError, "gem #{over_name} is not activated" if over.nil?
810: 
811:     last_gem_path = File.join gem.full_gem_path, gem.require_paths.last
812: 
813:     over_paths = over.require_paths.map do |path|
814:       File.join over.full_gem_path, path
815:     end
816: 
817:     over_paths.each do |path|
818:       $LOAD_PATH.delete path
819:     end
820: 
821:     gem = $LOAD_PATH.index(last_gem_path) + 1
822: 
823:     $LOAD_PATH.insert(gem, *over_paths)
824:   end

Safely read a file in binary mode on all platforms.

[Source]

     # File lib/rubygems.rb, line 838
838:   def self.read_binary(path)
839:     File.open path, binary_mode do |f| f.read end
840:   end

Refresh source_index from disk and clear searcher.

[Source]

     # File lib/rubygems.rb, line 829
829:   def self.refresh
830:     source_index.refresh!
831: 
832:     @searcher = nil
833:   end

Full path to libfile in gemname. Searches for the latest gem unless requirements is given.

[Source]

     # File lib/rubygems.rb, line 870
870:   def self.required_location(gemname, libfile, *requirements)
871:     requirements = Gem::Requirement.default if requirements.empty?
872: 
873:     matches = Gem.source_index.find_name gemname, requirements
874: 
875:     return nil if matches.empty?
876: 
877:     spec = matches.last
878:     spec.require_paths.each do |path|
879:       result = File.join spec.full_gem_path, path, libfile
880:       return result if File.exist? result
881:     end
882: 
883:     nil
884:   end

The path to the running Ruby interpreter.

[Source]

     # File lib/rubygems.rb, line 889
889:   def self.ruby
890:     if @ruby.nil? then
891:       @ruby = File.join(ConfigMap[:bindir],
892:                         ConfigMap[:ruby_install_name])
893:       @ruby << ConfigMap[:EXEEXT]
894: 
895:       # escape string in case path to ruby executable contain spaces.
896:       @ruby.sub!(/.*\s.*/m, '"\&"')
897:     end
898: 
899:     @ruby
900:   end

A Gem::Version for the currently running ruby.

[Source]

     # File lib/rubygems.rb, line 905
905:   def self.ruby_version
906:     return @ruby_version if defined? @ruby_version
907:     version = RUBY_VERSION.dup
908: 
909:     if defined?(RUBY_PATCHLEVEL) && RUBY_PATCHLEVEL != -1 then
910:       version << ".#{RUBY_PATCHLEVEL}"
911:     elsif defined?(RUBY_REVISION) then
912:       version << ".dev.#{RUBY_REVISION}"
913:     end
914: 
915:     @ruby_version = Gem::Version.new version
916:   end

The GemPathSearcher object used to search for matching installed gems.

[Source]

     # File lib/rubygems.rb, line 921
921:   def self.searcher
922:     @searcher ||= Gem::GemPathSearcher.new
923:   end

Returns the Gem::SourceIndex of specifications that are in the Gem.path

[Source]

     # File lib/rubygems.rb, line 962
962:   def self.source_index
963:     @@source_index ||= SourceIndex.from_installed_gems
964:   end

Returns an Array of sources to fetch remote gems from. If the sources list is empty, attempts to load the "sources" gem, then uses default_sources if it is not installed.

[Source]

     # File lib/rubygems.rb, line 971
971:   def self.sources
972:     if @sources.empty? then
973:       begin
974:         gem 'sources', '> 0.0.1'
975:         require 'sources'
976:       rescue LoadError
977:         @sources = default_sources
978:       end
979:     end
980: 
981:     @sources
982:   end

Need to be able to set the sources without calling Gem.sources.replace since that would cause an infinite loop.

[Source]

     # File lib/rubygems.rb, line 988
988:   def self.sources=(new_sources)
989:     @sources = new_sources
990:   end

Glob pattern for require-able path suffixes.

[Source]

     # File lib/rubygems.rb, line 995
995:   def self.suffix_pattern
996:     @suffix_pattern ||= "{#{suffixes.join(',')}}"
997:   end

Suffixes for require-able paths.

[Source]

      # File lib/rubygems.rb, line 1002
1002:   def self.suffixes
1003:     @suffixes ||= ['',
1004:                    '.rb',
1005:                    *%w(DLEXT DLEXT2).map { |key|
1006:                      val = RbConfig::CONFIG[key]
1007:                      next unless val and not val.empty?
1008:                      ".#{val}"
1009:                    }
1010:                   ].compact.uniq
1011:   end

Prints the amount of time the supplied block takes to run using the debug UI output.

[Source]

      # File lib/rubygems.rb, line 1017
1017:   def self.time(msg, width = 0, display = Gem.configuration.verbose)
1018:     now = Time.now
1019: 
1020:     value = yield
1021: 
1022:     elapsed = Time.now - now
1023: 
1024:     ui.say "%2$*1$s: %3$3.3fs" % [-width, msg, elapsed] if display
1025: 
1026:     value
1027:   end

Try to activate a gem containing path. Returns true if activation succeeded or wasn‘t needed because it was already activated. Returns false if it can‘t find the path in a gem.

[Source]

     # File lib/rubygems.rb, line 212
212:   def self.try_activate path
213:     spec = Gem.searcher.find path
214:     return false unless spec
215: 
216:     Gem.activate spec.name, "= #{spec.version}"
217:     return true
218:   end

Lazily loads DefaultUserInteraction and returns the default UI.

[Source]

      # File lib/rubygems.rb, line 1032
1032:   def self.ui
1033:     require 'rubygems/user_interaction'
1034: 
1035:     Gem::DefaultUserInteraction.ui
1036:   end

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

[Source]

      # File lib/rubygems.rb, line 1042
1042:   def self.use_paths(home, paths=[])
1043:     clear_paths
1044:     set_home(home) if home
1045:     set_paths(paths.join(File::PATH_SEPARATOR)) if paths
1046:   end

The home directory for the user.

[Source]

      # File lib/rubygems.rb, line 1051
1051:   def self.user_home
1052:     @user_home ||= find_home
1053:   end

Is this a windows platform?

[Source]

      # File lib/rubygems.rb, line 1058
1058:   def self.win_platform?
1059:     if @@win_platform.nil? then
1060:       @@win_platform = !!WIN_PATTERNS.find { |r| RUBY_PLATFORM =~ r }
1061:     end
1062: 
1063:     @@win_platform
1064:   end

[Validate]