mirror of
https://github.com/pyenv/pyenv.git
synced 2024-11-21 20:47:00 -05:00
274 lines
9 KiB
Text
274 lines
9 KiB
Text
# Simple Ruby Version Management: rbenv
|
|
|
|
<img src="http://i.sstephenson.us/rbenv.png" width="894" height="464">
|
|
|
|
rbenv lets you easily switch between multiple versions of Ruby. It's
|
|
simple, unobtrusive, and follows the UNIX tradition of single-purpose
|
|
tools that do one thing well.
|
|
|
|
### rbenv _does…_
|
|
|
|
* Let you **change the global Ruby version** on a per-user basis.
|
|
* Provide support for **per-project Ruby versions**.
|
|
* 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`.** 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](https://github.com/sstephenson/ruby-build) to
|
|
automate the process.
|
|
* **Manage gemsets.** [Bundler](http://gembundler.com/) is a better
|
|
way to manage application dependencies. If you have projects that
|
|
are not yet using Bundler you can install the
|
|
[rbenv-gemset](https://github.com/jamis/rbenv-gemset) plugin.
|
|
* **Require changes to Ruby libraries for compatibility.** The
|
|
simplicity of rbenv means as long as it's in your `$PATH`,
|
|
[nothing](https://rvm.beginrescueend.com/integration/bundler/)
|
|
[else](https://rvm.beginrescueend.com/integration/capistrano/)
|
|
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."
|
|
|
|
## Table of Contents
|
|
|
|
## How It Works ##
|
|
|
|
rbenv operates on the per-user directory `~/.rbenv`. Version names in
|
|
rbenv correspond to subdirectories of `~/.rbenv/versions`. For
|
|
example, you might have `~/.rbenv/versions/1.8.7-p354` and
|
|
`~/.rbenv/versions/1.9.3-rc1`.
|
|
|
|
Each version is a working tree with its own binaries, like
|
|
`~/.rbenv/versions/1.8.7-p354/bin/ruby` and
|
|
`~/.rbenv/versions/1.9.3-rc1/bin/irb`. rbenv makes _shim binaries_
|
|
for every such binary across all installed versions of Ruby.
|
|
|
|
These shims are simple wrapper scripts that live in `~/.rbenv/shims`
|
|
and detect which Ruby version you want to use. They insert the
|
|
directory for the selected version at the beginning of your `$PATH`
|
|
and then execute the corresponding binary.
|
|
|
|
Because of the simplicity of the shim approach, all you need to use
|
|
rbenv is `~/.rbenv/shims` in your `$PATH`.
|
|
|
|
## Installation ##
|
|
|
|
rbenv is a young project, so for now you must install it from source.
|
|
|
|
**Compatibility note**: rbenv is _incompatible_ with rvm. Things will
|
|
appear to work until you try to install a gem. The problem is that
|
|
rvm actually overrides the `gem` command with a shell function!
|
|
Please remove any references to rvm before using rbenv.
|
|
|
|
1. Check out rbenv into `~/.rbenv`.
|
|
|
|
$ cd
|
|
$ git clone git://github.com/sstephenson/rbenv.git .rbenv
|
|
|
|
2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv`
|
|
command-line utility.
|
|
|
|
$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bash_profile
|
|
|
|
zsh users should add this line to `.zshrc` instead:
|
|
|
|
$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .zshrc
|
|
|
|
3. Add rbenv's shims directory to your `$PATH` and set up Bash
|
|
autocompletion. (If you prefer not to load rbenv in your shell, you
|
|
can manually add `$HOME/.rbenv/shims` to your path in step 2.)
|
|
|
|
$ echo 'eval "$(rbenv init -)"' >> .bash_profile
|
|
|
|
zsh users should add this line to `.zshrc` instead:
|
|
|
|
$ echo 'eval "$(rbenv init -)"' >> .zshrc
|
|
|
|
4. Restart your shell so the path changes take effect. You can now
|
|
begin using rbenv.
|
|
|
|
$ exec $SHELL
|
|
|
|
5. Install Ruby versions into `~/.rbenv/versions`. For example, to
|
|
install Ruby 1.9.2-p290, download and unpack the source, then run:
|
|
|
|
$ ./configure --prefix=$HOME/.rbenv/versions/1.9.2-p290
|
|
$ make
|
|
$ make install
|
|
|
|
The [ruby-build](https://github.com/sstephenson/ruby-build)
|
|
provides an `rbenv install` command that simplifies the process of
|
|
installing new Ruby versions to:
|
|
|
|
$ rbenv install 1.9.2-p290
|
|
|
|
6. Rebuild the shim binaries. You should do this any time you install
|
|
a new Ruby binary (for example, when installing a new Ruby version, or
|
|
when installing a gem that provides a binary).
|
|
|
|
$ rbenv rehash
|
|
|
|
### Upgrading an existing installation ###
|
|
|
|
If you've installed rbenv using the instructions above, you can
|
|
upgrade your installation at any time using git.
|
|
|
|
To upgrade to the latest development version of rbenv, use `git pull`:
|
|
|
|
$ cd ~/.rbenv
|
|
$ git pull
|
|
|
|
To upgrade to a specific release of rbenv, check out the corresponding
|
|
tag:
|
|
|
|
$ cd ~/.rbenv
|
|
$ git fetch
|
|
$ git tag
|
|
v0.1.0
|
|
v0.1.1
|
|
v0.1.2
|
|
v0.2.0
|
|
$ git checkout v0.2.0
|
|
|
|
## Usage ##
|
|
|
|
Like `git`, the `rbenv` command delegates to subcommands based on its
|
|
first argument. The most common subcommands are:
|
|
|
|
### rbenv global ###
|
|
|
|
Sets the global version of Ruby to be used in all shells by writing
|
|
the version name to the `~/.rbenv/version` file. This version can be
|
|
overridden by a per-project `.rbenv-version` file, or by setting the
|
|
`RBENV_VERSION` environment variable.
|
|
|
|
$ rbenv global 1.9.2-p290
|
|
|
|
The special version name `system` tells rbenv to use the system Ruby
|
|
(detected by searching your `$PATH`).
|
|
|
|
When run without a version number, `rbenv global` reports the
|
|
currently configured global version.
|
|
|
|
### rbenv local ###
|
|
|
|
Sets a local per-project Ruby version by writing the version name to
|
|
an `.rbenv-version` file in the current directory. This version
|
|
overrides the global, and can be overridden itself by setting the
|
|
`RBENV_VERSION` environment variable or with the `rbenv shell`
|
|
command.
|
|
|
|
$ rbenv local rbx-1.2.4
|
|
|
|
When run without a version number, `rbenv local` reports the currently
|
|
configured local version. You can also unset the local version:
|
|
|
|
$ rbenv local --unset
|
|
|
|
### rbenv shell ###
|
|
|
|
Sets a shell-specific Ruby version by setting the `RBENV_VERSION`
|
|
environment variable in your shell. This version overrides both
|
|
project-specific versions and the global version.
|
|
|
|
$ rbenv shell jruby-1.6.4
|
|
|
|
When run without a version number, `rbenv shell` reports the current
|
|
value of `RBENV_VERSION`. You can also unset the shell version:
|
|
|
|
$ rbenv shell --unset
|
|
|
|
Note that you'll need rbenv's shell integration enabled (step 3 of
|
|
the installation instructions) in order to use this command. If you
|
|
prefer not to use shell integration, you may simply set the
|
|
`RBENV_VERSION` variable yourself:
|
|
|
|
$ export RBENV_VERSION=jruby-1.6.4
|
|
|
|
### rbenv versions ###
|
|
|
|
Lists all Ruby versions known to rbenv, and shows an asterisk next to
|
|
the currently active version.
|
|
|
|
$ rbenv versions
|
|
1.8.7-p352
|
|
1.9.2-p290
|
|
* 1.9.3-rc1 (set by /Users/sam/.rbenv/global)
|
|
jruby-1.6.4
|
|
rbx-1.2.4
|
|
ree-1.8.7-2011.03
|
|
|
|
### rbenv version ###
|
|
|
|
Displays the currently active Ruby version, along with information on
|
|
how it was set.
|
|
|
|
$ rbenv version
|
|
1.8.7-p352 (set by /Volumes/37signals/basecamp/.rbenv-version)
|
|
|
|
### rbenv rehash ###
|
|
|
|
Installs shims for all Ruby binaries 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 binaries.
|
|
|
|
$ rbenv rehash
|
|
|
|
### rbenv which ###
|
|
|
|
Displays the full path to the binary that rbenv will execute when you
|
|
run the given command.
|
|
|
|
$ rbenv which irb
|
|
/Users/sam/.rbenv/versions/1.9.2-p290/bin/irb
|
|
|
|
### rbenv whence ###
|
|
|
|
Lists all Ruby versions with the given command installed.
|
|
|
|
$ rbenv whence rackup
|
|
1.9.3-rc1
|
|
jruby-1.6.4
|
|
ree-1.8.7-2011.03
|
|
|
|
## Contributing ##
|
|
|
|
The rbenv source code is [hosted on
|
|
GitHub](https://github.com/sstephenson/rbenv). It's clean, modular,
|
|
and easy to understand, even if you're not a shell hacker.
|
|
|
|
Please feel free to submit pull requests and file bugs on the [issue
|
|
tracker](https://github.com/sstephenson/rbenv/issues).
|
|
|
|
### License ###
|
|
|
|
(The MIT license)
|
|
|
|
Copyright (c) 2011 Sam Stephenson
|
|
|
|
Permission is hereby granted, free of charge, to any person obtaining
|
|
a copy of this software and associated documentation files (the
|
|
"Software"), to deal in the Software without restriction, including
|
|
without limitation the rights to use, copy, modify, merge, publish,
|
|
distribute, sublicense, and/or sell copies of the Software, and to
|
|
permit persons to whom the Software is furnished to do so, subject to
|
|
the following conditions:
|
|
|
|
The above copyright notice and this permission notice shall be
|
|
included in all copies or substantial portions of the Software.
|
|
|
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
|
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
|
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
|
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
|
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
|
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|