module RVM

Ruby Version Manager - Ruby API

Provides a wrapper around the command line api implemented as part of the api. If you're not familiar with rvm, please read rvm.beginrescueend.com/ first.

Usage

When using the rvm ruby api, you gain access to most of the commands, including the set functionality. As a side node, the RVM module provides access to most of the api both via direct api wrappers (of the form <tool>_<action> - e.g. alias_create, gemset_use and wrapper).

The Environment Model

The RVM ruby api is implemented using an environment model. Each environment maps directly to some ruby string interpretable by rvm (e.g. ree, ruby-1.8.7-p174, system, +rbx@rails+ and so on) and is considered a sandboxed environment (for commands like use etc) in which you can deal with rvm. it's worth noting that a single environment can have multiple environment instances and for the most part creating of these instances is best handled by the ::environment and ::environments methods.

Each Environment (and instance of RVM::Environment) provides access to the rvm ruby api (in some cases, the api may not directly be related to the current ruby - but for simplicity / consistency purposes, they are still implemented as methods of RVM::Environment).

When you perform an action with side effects (e.g. RVM::Environment#gemset_use or RVM::Environment#use) this will mutate the ruby string of the given environment (hence, an environment is considered mutable).

Lastly, for the actual command line work, RVM::Environment works with an instance of RVM::Shell::AbstractWrapper. This performs logic (such as correctly escaping strings, calling the environment and such) in a way that is both reusable and simplified.

By default, ::method_missing is used on the RVM module to proxy method calls to ::current (itself calling RVM::Environment.current), meaning things like RVM.gemset_name, RVM.alias_create and the like work. This is considered the 'global' instance and should be avoided unless needed directly.

RVM::Environment.current will first attempt to use the current ruby string (determined by +ENV+ but will fall back to using the rubies load path if that isn't available).

In many cases, (e.g. alias, list and the like) there is a more ruby-like wrapper class, typically available via RVM::Environment#<action>.

Side Notes

In the cases this api differs, see the RVM::Environment class for more information.

You can check the name of a given environment in two ways - RVM::Environment#environment_name for the short version / the version set by RVM::Environment#use, RVM::Environment#gemset_use or ::environment. If you wish to get the full, expanded string (which has things such as the actual version of the selected ruby), you instead with to use RVM::Environment#expanded_name.

Lastly, If you do need to pass environment variables to a specific environment, please use RVM::Environment.new, versus ::environment

Constants

Version

Public Class Methods

current() click to toggle source

Returns the current global environment.

# File lib/rvm.rb, line 65
def current
  Environment.current
end
environment(name) { |env| ... } click to toggle source

Returns the environment with the given name. If passed a block, will yield with that as the single argument.

RVM.environment("ree@rails3") do |env|
  puts "Gemset is #{env.gemset.name}"
end
# File lib/rvm.rb, line 104
def environment(name)
  # TODO: Maintain an Environment cache.
  # The cache needs to track changes via use etc though.
  env = Environment.new(name)
  yield env if block_given?
  env
end
environments(*names, &blk) click to toggle source

Returns an array of multiple environments. If given a block, will yield each time with the given environment.

RVM.environments("ree@rails3,rbx@rails3") do |env|
  puts "Full environment: #{env.expanded_name}"
end
# => "ree-1.8.7@rails3"
# => "rbx-1.1.0@rails3" # Suppose that you are installed rbx 1.1.0

Alternatively, you can use the more ruby-like fashion:

RVM.environments("ree@rails3", "rbx@rails3") do |env|
  puts "Full environment: #{env.expanded_name}"
end
# File lib/rvm.rb, line 90
def environments(*names, &blk)
  # Normalize the names before using them on for the environment.
  names.flatten.join(",").split(",").uniq.map do |n|
    environment(n, &blk)
  end
end
merge_config!(config = {}) click to toggle source

Merges items into the default config, essentially setting environment variables passed to child processes:

RVM.merge_config!({
  :some_shell_variable => "me",
})
# File lib/rvm.rb, line 119
def merge_config!(config = {})
  Environment.merge_config!(config)
end
path() click to toggle source

Returns the current 'best guess' value for rvm_path.

# File lib/rvm.rb, line 124
def path
  Environment.rvm_path
end
path=(value) click to toggle source

Shortcut to set rvm_path. Will set it on all new instances but wont affect currently running environments.

# File lib/rvm.rb, line 130
def path=(value)
  Environment.rvm_path = value
end
reset_current!() click to toggle source

Reset the current global environment to the default / what it was when the process first started.

# File lib/rvm.rb, line 71
def reset_current!
  Environment.reset_current!
end

Private Class Methods

cache_method_call(name) click to toggle source
# File lib/rvm.rb, line 136
    def cache_method_call(name)
      class_eval "        def #{name}(*args, &blk)
          current.__send__(:#{name}, *args, &blk)
        end
", __FILE__, __LINE__
    end
method_missing(name, *args, &blk) click to toggle source

Proxies methods to the current environment, creating a method before dispatching to speed up future calls.

Calls superclass method
# File lib/rvm.rb, line 146
def method_missing(name, *args, &blk)
  if current.respond_to?(name)
    cache_method_call name
    current.__send__ name, *args, &blk
  else
    super
  end
end