The Basics of RVM
Wondering why you should use RVM? For a start, not only does RVM make installing multiple ruby interpreters / runtimes easy and consistent, it provides features such as gemsets that aren't typically supported out of the box on most ruby installs.
RVM also lets you use different rubies in a manner that wont mess with your existing ruby install (unless you tell it to) as well as letting you run multiple different rubies in seperate terminals concurrently!
Getting started
First, you must ensure that you install RVM .
Post Install Configuration
The rvm installation documentation instructs you to put the following line at the very end of your bash profile:
[[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" # This loads RVM into a shell session.
NOTE: This is for a user install. If you installed as root then you substitute '$HOME/.rvm' with '/usr/local/rvm'.
For those who are not very familiar with bash scripting, I will explain in the next few paragraphs what the line above does.
[[ condition ]] evaluates the condition inside the double brackets and returns true or false. The option -s tells bash to look for the named file, and decide whether it exists and is nonempty. So the line [[ -s "$HOME/.rvm/scripts/rvm" ]] looks inside the default rvm scripts folder '~/.rvm/scripts/' for rvm, and returns true or false based on that criteria.
Next, the && operator (a logical AND with short-circuit) executes the rest of the line if and only if the previous test returns true. This means that, in our rvm example, if the file '~/.rvm/scripts/rvm' is not found (or is empty) then bash ignores the rest of the line. NOTE: I've seen the && used a lot when installing software from source in linux for make && sudo make install -- if make fails, then it doesn't try to install it to your system. This is the joy of command chaining at its finest.
Finally, the shell command '.' file is identical to the bash/zsh 'source' command. This command reads the file listed after it and executes each command listed in the currently running shell. This means that:
. "$HOME/.rvm/scripts/rvm"
This executes the rvm shell script, this script contains the master 'rvm()' function that you will be using to issue RVM commands in your shell. NOTE: Sometimes on OS X, '.' fails to source correctly. If that happens, simply change '.' for 'source'.
Note that the '#' is the shell comment character so everything after it is a comment and ignored by the shell when the line is executed.
Place the sourcing line in your startup files. Use ~/.profile if it exists, otherwise use .bashrc and .bash_profile. If these files do not exist you may create them. Since .bashrc is used for non-interactive login shells, and .bash_profile whenever you log in either via ssh or the local shell account, there is a little trick for ensuring RVM is loaded no matter what. Put the sourcing line in your $HOME/.bashrc and then load your .bashrc from .bash_profile using an 'if' statement in your .bash_profile like as follows:
if [ -f "$HOME/.bashrc" ]; then source $HOME/.bashrc fi
Then, when you login or spawn a shell this will automatically load RVM regardless of the shell type. Pretty handy, huh? Also, make sure the RVM sourcing line is the last line in your '$HOME/.bashrc' file. This stops anything else from being able to override it since it will be the last thing executed from the .bashrc file. If you are using the ZSH shell then you can place the sourcing line in your in ~/.zshrc.
You should now open a new shell and start playing with rvm.
A note about the .bashrc warning. The rvm install troubleshooting notes explain how to change your bash profile to work with rvm. In a few linux distributions, the default .bashrc contains the following line:
[ -z "$PS1" ] && return[ -z "$PS1" ] is true if the string "$PS1" has zero length (a non-interactive shell). rvm needs to load for both interactive and non-interactive shells which is why it strongly is recommended to alter this file.
First ensure that the previous step was successful and that rvm is loaded correctly *as a shell function*, run:
$ type rvm | head -1
Assuming this shows "rvm is a function", you're good to go. As an example, to install and use Ruby 1.9.2 you may do:
$ rvm install 1.9.2
Once you have installed a Ruby interpreter with RVM successfully you may then use it by executing the following command:
$ rvm use 1.9.2 $ ruby -v ruby 1.9.2p0 (2010-08-18 revision 29036) [x86_64-darwin10.4.0] $ which ruby /Users/wayne/.rvm/rubies/ruby-1.9.2-p0/bin/ruby
NOTE: There has been some confusion amongst new users as to the proper way to switch between Ruby versions. Do not include the 'ruby-' portion of whatever is listed in the output of 'rvm list' for installed rubies. This is just used to indicate the differences between, say, ree rubies, and MRI rubies, etc. However, do note, that when you are switching between an MRI or Rubinus, or REE, as an example, then you use the ree|ruby|rbx part. When you want to switch, just use the version number and any patch level. If its a -head version use the full string as it will not contain numbers. This also applies when setting a default Ruby. Below is an example of what I mean:
$ rvm use 1.9.2-p180 --default
$ rvm use ruby-head # This just changes to ruby-head but does not set it as your default Ruby.
$ rvm use ree-head --default
$ rvm use ree-1.8.7-2011.03 # You use this full form if, for example, you previously had an MRI or Rubinus ruby selected.
$ rvm use 1.9.2 --default
The last example above does not use a patch level because you are basically saying use the most currently released stable version of 1.9.2 which, as of the time of this writing, is 1.9.2-p290. Also, please take note that the keyword use above causes RVM to output the version it is switching to. Basically, it makes the change operation verbose. Note that it is not required in most operations.
RVM is 'hands off' any system ruby that you have installed. To be able to "use" your system ruby you can tell RVM to undo the environment changes that it has applied as follows.
$ rvm use system $ ruby -v ruby 1.8.7 (2009-06-12 patchlevel 174) [universal-darwin10.0] $ which ruby /usr/bin/ruby
Which tells the current shell to act as if you haven't run any "rvm use" commands yet.
Where To Now?
For further explanation, look around the rest of the site. In particular, make sure you check out the workflow examples.
Remember that switching rubies is on a per-shell basis. If you want to set which ruby is available when you open a new shell, you'll need to set a default ruby interpreter.
After you have the hang of dealing with Ruby Interpreters, next start to learn about gemsets.
If you would like to know which Ruby RVM has selected and made active at any time, if any, you can add this information to your shell prompt.
If you use tab completion in your shell also see the documentation on using shell completion.
Community Resources
- Check here for an excellent post introducting the why of RVM, written by Steve Klabnik.
