rbenv

What is rbenv?

rbenv is a tool for simple Ruby version management.

Use rbenv to pick a Ruby version for your application and guarantee that your development environment matches production. Put rbenv to work with Bundler for painless Ruby upgrades and bulletproof deployments.

Powerful in development. Specify your app's Ruby version once, in a single file. Keep all your teammates on the same page. No headaches running apps on different versions of Ruby. Just Works™ from the command line and with app servers like Pow. Override the Ruby version anytime: just set an environment variable.

Rock-solid in production. Your application's executables are its interface with ops. With rbenv and Bundler binstubs you'll never again need to cd in a cron job or Chef recipe to ensure you've selected the right runtime. The Ruby version dependency lives in one place—your app—so upgrades and rollbacks are atomic, even when you switch versions.

One thing well. rbenv is concerned solely with switching Ruby versions. It's simple and predictable. A rich plugin ecosystem lets you tailor it to suit your needs. Compile your own Ruby versions, or use the ruby-build plugin to automate the process. Specify per-application environment variables with rbenv-vars. See more plugins on the wiki.

rbenv does…

• Provide support for specifying application-specific Ruby versions.
• Let you change the global Ruby version on a per-user basis.
• Allow you to override the Ruby version with an environment variable.

In contrast with RVM, rbenv does not…

• Need to be loaded into your shell. Instead, rbenv's shim approach works by adding a directory to your $PATH.
• Override shell commands like cd or require prompt hacks. That's dangerous and error-prone.
• Have a configuration file. There's nothing to configure except which version of Ruby you want to use.
• Install Ruby. You can build and install Ruby yourself, or use ruby-build to automate the process.
• Manage gemsets. Bundler is a better way to manage application dependencies. If you have projects that are not yet using Bundler you can install the rbenv-gemset plugin.
• Require changes to Ruby libraries for compatibility. The simplicity of rbenv means as long as it's in your $PATH, nothing else needs to know about it.
• Prompt you with warnings when you switch to a project. Instead of executing arbitrary code, rbenv reads just the version name from each project. There's nothing to "trust."

Installation

GitHub Checkout

This will get you going with the latest version of rbenv and make it easy to fork and contribute any changes back upstream.

Check out rbenv into ~/.rbenv

$ git clone git://github.com/sstephenson/rbenv.git ~/.rbenv

Add ~/.rbenv/bin to your $PATH for access to the rbenv command-line utility

$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile

Ubuntu note: Modify your ~/.profile instead of ~/.bash_profile.

Zsh note: Modify your ~/.zshrc file instead of ~/.bash_profile.

Add rbenv init to your shell to enable shims and auto-completion

$ echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

Same as in previous step, use ~/.profile on Ubuntu, ~/.zshrc for Zsh.

# set PATH to include rbenv if it exists
if [ -d "$HOME/.rbenv" ]; then
    export PATH="$HOME/.rbenv/bin:$PATH"
    eval "$(rbenv init -)"
fi

NOTE: Personally I prefer to use a separate script to set up environment variables rather than modifying ~/bash_profile or ~/.profile. It's more flexible.

#!/bin/bash
# Initialize rbenv environment variables
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

Restart your shell as a login shell so the path changes take effect

You can now begin using rbenv.

$ exec $SHELL -l

Install ruby-build plugin

ruby-build plugin provides an rbenv install command that simplifies the process of installing new Ruby versions

git clone git://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build

rbenv usage

rbenv 0.4.0-7-gda80bce
Usage: rbenv <command> [<args>]
Some useful rbenv commands are:
   commands    List all available rbenv commands
   local       Set or show the local application-specific Ruby version
   global      Set or show the global Ruby version
   shell       Set or show the shell-specific Ruby version
   install     Install a Ruby version using the ruby-build plugin
   uninstall   Uninstall a specific Ruby version
   rehash      Rehash rbenv shims (run this after installing executables)
   version     Show the current Ruby version and its origin
   versions    List all Ruby versions available to rbenv
   which       Display the full path to an executable
   whence      List all Ruby versions that contain the given executable
See `rbenv help <command>' for information on a specific command.
For full documentation, see: https://github.com/sstephenson/rbenv#readme

Update ruby-build plugin

To update ruby-build after it has been installed, run git pull in your cloned copy of the repository, then re-run the install script.

terry@tux:~/.rbenv/plugins/ruby-build$ git pull
remote: Counting objects: 9, done.
remote: Compressing objects: 100% (4/4), done.
remote: Total 6 (delta 2), reused 5 (delta 1)
Unpacking objects: 100% (6/6), done.
From https://github.com/sstephenson/ruby-build
   4f45814..29d65e0  master     -> origin/master
Updating 4f45814..29d65e0
Fast-forward
 share/ruby-build/1.9.3-p374 |    2 ++
 1 file changed, 2 insertions(+)
 create mode 100644 share/ruby-build/1.9.3-p374

Install a Ruby version using ruby-build plugin

Prerequisites

To compile Ruby from source code, you need to following packages installed on Ubuntu/Debian (amd64/x86_64)

sudo apt-get install -y make build-essential libc6-dev libssl-dev libreadline6-dev zlib1g-dev libyaml-dev

OPTIONAL: libmysql++-dev libsqlite3-dev

Install a Ruby version using ruby-build

$ rbenv install 1.9.3-p327

NOTE: Ruby versions will be installed into a directory of the same name under ~/.rbenv/versions. To see more when compiling Ruby, use the -v option.

To see a list of all available Ruby versions, run rbenv install --list. You may also tab-complete available Ruby versions if your rbenv installation is properly configured. As an alternative, you can download and compile Ruby yourself into ~/.rbenv/versions/.

Uninstall a specific Ruby version

Uninstall

$ rbenv uninstall 1.9.3-p327

Rebuild the shim executables

IMPORTANT: You should do this any time you install a new Ruby executable (for example, when installing a new Ruby version, or when installing a gem that provides a command).

rbenv rehash

Installs shims for all Ruby executables known to rbenv (i.e., ~/.rbenv/versions/*/bin/*). Run this command after you install a new version of Ruby, or install a gem that provides commands.

Recommended: Alternatively, you can install gem rbenv-rehash to avoid rehashing all the time.

rubygems

zlib is required for gem to work, you'll get the error below when update or install gems if you don't have zlib installed on the system.

ERROR:  Loading command: install (LoadError)
    cannot load such file -- zlib
ERROR:  While executing gem ... (NameError)
    uninitialized constant Gem::Commands::InstallCommand

For Ubuntu

apt-get install zlib1g-dev

IMPORTANT: After installing zlib, rbenv uninstall and rbenv install (re-compile) Ruby versions again to make gem work.

NOTE: libssl-dev will install zlib1g-dev as dependency.

rbenv-gemset plugin

rbenv-gemset is an extension for the rbenv ruby version manager that allows you to use "gemsets", sandboxed collections of gems. This lets you have multiple collections of gems installed in different sandboxes, and specify (on a per-application basis) which sets of gems should be used.

Installation

clone rbenv-gemset from GitHub Repository into $HOME/.rbenv/plugins directory

git clone git://github.com/jamis/rbenv-gemset.git ~/.rbenv/plugins/rbenv-gemset

Usage

Usage

$ rbenv gemset 
version 0.3.0
rbenv-gemset [command] [options]

possible commands are:
  active
  create [version] [gemset]
  delete [version] [gemset]
  file
  list
  version

For full documentation, see: https://github.com/jamis/rbenv-gemset#readme

In application directory, create a file named .rbenv-gemsets and put the names of the gemsets wanted in it, separated by whitespace. The first gemset in the list will be the primary gemset, where new gems will be installed.

$ echo my-gemset > .rbenv-gemsets

Now, all commands involving gems will use the gemsets you specified.

The gemset plugin will cause rbenv to search for the .rbenv-gemsets file in the current directory, as well as in all ancestor directories, so as long as there is an .rbenv-gemsets file at or above the current directory.

Alternatively, you can set the RBENV_GEMSET_FILE environment variable to the absolute path of the gemset file.

Update rbenv

If you've installed rbenv manually using git, you can upgrade your installation to the cutting-edge version at any time

$ cd ~/.rbenv
$ git pull

To use a specific release of rbenv, check out the corresponding tag:

$ cd ~/.rbenv
$ git fetch
$ git checkout v0.3.0

Update ruby-build

cd ~/.rbenv/plugins/ruby-build && git pull

Update rbenv-gemset

cd ~/.rbenv/plugins/rbenv-gemset && git pull 

DO NOT Install Ruby RDoc and Ruby Index for gems

If you prefer NOT to install RDoc (Ruby Documentation) and ri (Ruby Index), create $HOME/.gemrc or add in /etc/gemrc with the following contents

# ~/.gemrc
gem: --no-rdoc --no-ri

This is recommended on server deployment.

Troubleshooting

Install vagrant or vmc via RubyGems and rbenv rehash, the following error will occur when running vagrant:

terry@ubuntu:~/.rbenv$ vagrant
/home/terry/.rbenv/versions/1.9.3-p327/lib/ruby/1.9.1/rubygems/custom_require.rb:36:in `require': cannot load such file -- openssl (LoadError)
	from /home/terry/.rbenv/versions/1.9.3-p327/lib/ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
	from /home/terry/.rbenv/versions/1.9.3-p327/lib/ruby/gems/1.9.1/gems/vagrant-1.0.5/lib/vagrant.rb:52:in `<top (required)>'
	from /home/terry/.rbenv/versions/1.9.3-p327/lib/ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
	from /home/terry/.rbenv/versions/1.9.3-p327/lib/ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
	from /home/terry/.rbenv/versions/1.9.3-p327/lib/ruby/gems/1.9.1/gems/vagrant-1.0.5/bin/vagrant:3:in `<top (required)>'
	from /home/terry/.rbenv/versions/1.9.3-p327/bin/vagrant:23:in `load'
	from /home/terry/.rbenv/versions/1.9.3-p327/bin/vagrant:23:in `<main>'

libssl-dev is required when installing (compiling Ruby)

For Ubuntu (amd64/x86_64)

apt-get install libssl-dev

then uninstall and install Ruby versions again will fix the issue.

Reference

https://github.com/sstephenson/rbenv

RVM and rbenv