123456789_123456789_123456789_123456789_123456789_

Class: Gem::Commands::InstallCommand

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
Instance Chain:
Inherits: Gem::Command
Defined in: lib/rubygems/commands/install_command.rb

Overview

::Gem installer command line tool

See gem help install

Constant Summary

::Gem::Command - Inherited

HELP

Class Attribute Summary

::Gem::Command - Inherited

.build_args

Arguments used when building gems.

.build_args=, .extra_args, .extra_args=

Class Method Summary

::Gem::Command - Inherited

.add_common_option,
.add_specific_extra_args

Add a list of extra arguments for the given command.

.common_options,
.new

Initializes a generic gem command named command.

.specific_extra_args

Return an array of extra arguments for the command.

.specific_extra_args_hash

Accessor for the specific extra args hash (self initializing).

Instance Attribute Summary

::Gem::LocalRemoteOptions - Included

#both?

Is fetching of local and remote information enabled?

#local?

Is local fetching enabled?

#remote?

Is remote fetching enabled?

::Gem::Command - Inherited

#command

The name of the command.

#defaults

The default options for the command.

#deprecated?,
#options

The options for the command.

#program_name

The name of the command for command-line invocation.

#summary

A short description of the command.

::Gem::DefaultUserInteraction - Included

Instance Method Summary

::Gem::InstallUpdateOptions - Included

#add_install_update_options

Add the install/update options to the option parser.

#install_update_defaults_str

Default options for the gem install command.

::Gem::SecurityOption - Included

::Gem::LocalRemoteOptions - Included

#accept_uri_http

Allows ::Gem::OptionParser to handle HTTP URIs.

#add_bulk_threshold_option

Add the –bulk-threshold option.

#add_clear_sources_option

Add the –clear-sources option.

#add_local_remote_options

Add local/remote options to the command line parser.

#add_proxy_option

Add the –http-proxy option.

#add_source_option

Add the –source option.

#add_update_sources_option

Add the –update-sources option.

::Gem::VersionOption - Included

#add_platform_option

Add the –platform option to the option parser.

#add_prerelease_option

Add the –prerelease option to the option parser.

#add_version_option

Add the –version option to the option parser.

#get_platform_from_requirements

Extract platform given on the command line.

::Gem::Command - Inherited

#add_extra_args

Adds extra args from ~/.gemrc.

#add_option

Add a command-line option and handler to the command.

#arguments

Override to provide details of the arguments a command takes.

#begins?

True if long begins with the characters from short.

#check_deprecated_options,
#defaults_str

Override to display the default values of the command options.

#deprecate_option

Mark a command-line option as deprecated, and optionally specify a deprecation horizon.

#description

Override to display a longer description of what this command does.

#execute

Override to provide command handling.

#get_all_gem_names

Get all gem names from the command line.

#get_all_gem_names_and_versions

Get all [gem, version] from the command line.

#get_one_gem_name

Get a single gem name from the command line.

#get_one_optional_argument

Get a single optional argument from the command line.

#handle_options

Handle the given list of arguments by parsing them and recording the results.

#handles?

True if the command handles the given argument list.

#invoke

Invoke the command with the given list of arguments.

#invoke_with_build_args

Invoke the command with the given list of normal arguments and additional build arguments.

#merge_options

Merge a set of command options with the set of default options (without modifying the default option hash).

#remove_option

Remove previously defined command-line argument name.

#show_help

Display the help message for the command.

#show_lookup_failure

Display to the user that a gem couldn’t be found and reasons why –.

#usage

Override to display the usage for an individual gem command.

#when_invoked

Call the given block when invoked.

#add_parser_run_info

Adds a section with title and content to the parser help view.

#configure_options,
#create_option_parser

Creates an option parser and fills it in with the help info for the command.

#option_is_deprecated?,
#parser

Create on demand parser.

#wrap

Wraps text to width

#add_parser_description, #add_parser_options, #add_parser_summary

::Gem::UserInteraction - Included

#alert

Displays an alert statement.

#alert_error

Displays an error statement to the error output location.

#alert_warning

Displays a warning statement to the warning output location.

#ask

Asks a question and returns the answer.

#ask_for_password

Asks for a password with a prompt

#ask_yes_no

Asks a yes or no question.

#choose_from_list

Asks the user to answer question with an answer from the given list.

#say

Displays the given statement on the standard output (or equivalent).

#terminate_interaction

Terminates the RubyGems process with the given exit_code

#verbose

Calls say with msg or the results of the block if really_verbose is true.

::Gem::DefaultUserInteraction - Included

::Gem::Text - Included

#clean_text

Remove any non-printable characters and make the text suitable for printing.

#format_text

Wraps text to wrap characters and optionally indents by indent characters.

#levenshtein_distance

This code is based directly on the ::Gem::Text gem implementation Returns a value representing the “cost” of transforming str1 into str2.

#truncate_text, #min3

Constructor Details

.newInstallCommand

[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 21

def initialize
  defaults = Gem::DependencyInstaller::DEFAULT_OPTIONS.merge({
    :format_executable => false,
    :lock              => true,
    :suggest_alternate => true,
    :version           => Gem::Requirement.default,
    :without_groups    => [],
  })

  super 'install', 'Install a gem into the local repository', defaults

  add_install_update_options
  add_local_remote_options
  add_platform_option
  add_version_option
  add_prerelease_option "to be installed. (Only for listed gems)"

  @installed_specs = []
end

Instance Attribute Details

#installed_specs (readonly)

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 15

attr_reader :installed_specs # :nodoc:

Instance Method Details

#arguments

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 41

def arguments # :nodoc:
  "GEMNAME       name of gem to install"
end

#check_install_dir

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 133

def check_install_dir # :nodoc:
  if options[:install_dir] and options[:user_install]
    alert_error "Use --install-dir or --user-install but not both"
    terminate_interaction 1
  end
end

#check_version

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 140

def check_version # :nodoc:
  if options[:version] != Gem::Requirement.default and
       get_all_gem_names.size > 1
    alert_error "Can't use --version with multiple gems. You can specify multiple gems with" \
                " version requirements using `gem install 'my_gem:1.0.0' 'my_other_gem:~>2.0.0'`"
    terminate_interaction 1
  end
end

#defaults_str

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 45

def defaults_str # :nodoc:
  "--both --version '#{Gem::Requirement.default}' --document --no-force\n" +
  "--install-dir #{Gem.dir} --lock"
end

#description

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 50

def description # :nodoc:
  <<-EOF
The install command installs local or remote gem into a gem repository.

For gems with executables ruby installs a wrapper file into the executable
directory by default.  This can be overridden with the --no-wrappers option.
The wrapper allows you to choose among alternate gem versions using _version_.

For example `rake _0.7.3_ --version` will run rake version 0.7.3 if a newer
version is also installed.

Gem Dependency Files
====================

RubyGems can install a consistent set of gems across multiple environments
using `gem install -g` when a gem dependencies file (gem.deps.rb, Gemfile or
Isolate) is present.  If no explicit file is given RubyGems attempts to find
one in the current directory.

When the RUBYGEMS_GEMDEPS environment variable is set to a gem dependencies
file the gems from that file will be activated at startup time.  Set it to a
specific filename or to "-" to have RubyGems automatically discover the gem
dependencies file by walking up from the current directory.

NOTE: Enabling automatic discovery on multiuser systems can lead to
execution of arbitrary code when used from directories outside your control.

Extension Install Failures
==========================

If an extension fails to compile during gem installation the gem
specification is not written out, but the gem remains unpacked in the
repository.  You may need to specify the path to the library's headers and
libraries to continue.  You can do this by adding a -- between RubyGems'
options and the extension's build options:

$ gem install some_extension_gem
[build fails]
Gem files will remain installed in \\
/path/to/gems/some_extension_gem-1.0 for inspection.
Results logged to /path/to/gems/some_extension_gem-1.0/gem_make.out
$ gem install some_extension_gem -- --with-extension-lib=/path/to/lib
[build succeeds]
$ gem list some_extension_gem

*** LOCAL GEMS ***

some_extension_gem (1.0)
$

If you correct the compilation errors by editing the gem files you will need
to write the specification by hand.  For example:

$ gem install some_extension_gem
[build fails]
Gem files will remain installed in \\
/path/to/gems/some_extension_gem-1.0 for inspection.
Results logged to /path/to/gems/some_extension_gem-1.0/gem_make.out
$ [cd /path/to/gems/some_extension_gem-1.0]
$ [edit files or what-have-you and run make]
$ gem spec ../../cache/some_extension_gem-1.0.gem --ruby > \\
           #../../specifications/some_extension_gem-1.0.gemspec
$ gem list some_extension_gem

*** LOCAL GEMS ***

some_extension_gem (1.0)
$

Command Alias
==========================

You can use `i` command instead of `install`.

$ gem i GEMNAME

  EOF
end

#execute

[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 149

def execute
  if options.include? :gemdeps
    install_from_gemdeps
    return # not reached
  end

  @installed_specs = []

  ENV.delete 'GEM_PATH' if options[:install_dir].nil?

  check_install_dir
  check_version

  load_hooks

  exit_code = install_gems

  show_installed

  terminate_interaction exit_code
end

#install_from_gemdeps

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 171

def install_from_gemdeps # :nodoc:
  require_relative '../request_set'
  rs = Gem::RequestSet.new

  specs = rs.install_from_gemdeps options do |req, inst|
    s = req.full_spec

    if inst
      say "Installing #{s.name} (#{s.version})"
    else
      say "Using #{s.name} (#{s.version})"
    end
  end

  @installed_specs = specs

  terminate_interaction
end

#install_gem(name, version)

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 190

def install_gem(name, version) # :nodoc:
  return if options[:conservative] and
    not Gem::Dependency.new(name, version).matching_specs.empty?

  req = Gem::Requirement.create(version)

  dinst = Gem::DependencyInstaller.new options

  request_set = dinst.resolve_dependencies name, req

  if options[:explain]
    say "Gems to install:"

    request_set.sorted_requests.each do |activation_request|
      say "  #{activation_request.full_name}"
    end
  else
    @installed_specs.concat request_set.install options
  end

  show_install_errors dinst.errors
end

#install_gems

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 213

def install_gems # :nodoc:
  exit_code = 0

  get_all_gem_names_and_versions.each do |gem_name, gem_version|
    gem_version ||= options[:version]
    domain = options[:domain]
    domain = :local unless options[:suggest_alternate]
    suppress_suggestions = (domain == :local)

    begin
      install_gem gem_name, gem_version
    rescue Gem::InstallError => e
      alert_error "Error installing #{gem_name}:\n\t#{e.message}"
      exit_code |= 1
    rescue Gem::GemNotFoundException => e
      show_lookup_failure e.name, e.version, e.errors, suppress_suggestions

      exit_code |= 2
    rescue Gem::UnsatisfiableDependencyError => e
      show_lookup_failure e.name, e.version, e.errors, suppress_suggestions,
                          "'#{gem_name}' (#{gem_version})"

      exit_code |= 2
    end
  end

  exit_code
end

#load_hooks

This method is for internal use only.

Loads post-install hooks

[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 245

def load_hooks # :nodoc:
  if options[:install_as_default]
    require_relative '../install_default_message'
  else
    require_relative '../install_message'
  end
  require_relative '../rdoc'
end

#show_install_errors(errors)

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 254

def show_install_errors(errors) # :nodoc:
  return unless errors

  errors.each do |x|
    return unless Gem::SourceFetchProblem === x

    require_relative "../uri"
    msg = "Unable to pull data from '#{Gem::Uri.new(x.source.uri).redacted}': #{x.error.message}"

    alert_warning msg
  end
end

#show_installed

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 267

def show_installed # :nodoc:
  return if @installed_specs.empty?

  gems = @installed_specs.length == 1 ? 'gem' : 'gems'
  say "#{@installed_specs.length} #{gems} installed"
end

#usage

This method is for internal use only.
[ GitHub ]

  
# File 'lib/rubygems/commands/install_command.rb', line 129

def usage # :nodoc:
  "#{program_name} [options] GEMNAME [GEMNAME ...] -- --build-flags"
end