From 308aa42b676a314bed44cca72e3309b51c0e607f Mon Sep 17 00:00:00 2001 From: Sam Stephenson Date: Thu, 3 Jan 2013 21:18:05 -0600 Subject: [PATCH] Rewrite "How It Works" with @trevorturk --- README.md | 138 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 101 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index a3655835..2e9de59d 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,10 @@ bulletproof deployments. ## Table of Contents * [How It Works](#how-it-works) + * [Understanding PATH](#understanding-path) + * [Understanding Shims](#understanding-shims) + * [Choosing the Ruby Version](#choosing-the-ruby-version) + * [Locating the Ruby Installation](#locating-the-ruby-installation) * [Installation](#installation) * [Basic GitHub Checkout](#basic-github-checkout) * [Upgrading](#upgrading) @@ -50,24 +54,89 @@ bulletproof deployments. * [Version History](#version-history) * [License](#license) -## How It Works ## +## 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-p327`. +At at high level, rbenv intercepts Ruby commands using shim +executables injected into your `PATH`, determines which Ruby version +has been specified by your application, and passes your commands along +to the correct Ruby installation. -Each version is a working tree with its own executables, like -`~/.rbenv/versions/1.8.7-p354/bin/ruby` and -`~/.rbenv/versions/1.9.3-p327/bin/irb`. rbenv makes _shim executables_ -for every such executable across all installed versions of Ruby. +### Understanding PATH -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 invoke the corresponding executable. +When you run a command like `ruby` or `rake`, your operating system +searches through a list of directories to find an executable file with +that name. This list of directories lives in an environment variable +called `PATH`, with each directory in the list separated by a colon: -## Installation ## + /usr/local/bin:/usr/bin:/bin + +Directories in `PATH` are searched from left to right, so a matching +executable in a directory at the beginning of the list takes +precedence over another one at the end. In this example, the +`/usr/local/bin` directory will be searched first, then `/usr/bin`, +then `/bin`. + +### Understanding Shims + +rbenv works by inserting a directory of _shims_ at the front of your +`PATH`: + + ~/.rbenv/shims:/usr/local/bin:/usr/bin:/bin + +Through a process called _rehashing_, rbenv maintains shims in that +directory to match every Ruby command across every installed version +of Ruby—`irb`, `gem`, `rake`, `rails`, `ruby`, and so on. + +Shims are lightweight executables that simply pass your command along +to rbenv. So with rbenv installed, when you run, say, `rake`, your +operating system will do the following: + +* Search your `PATH` for an executable file named `rake` +* Find the rbenv shim named `rake` at the beginning of your `PATH` +* Run the shim named `rake`, which in turn passes the command along to + rbenv + +### Choosing the Ruby Version + +When you execute a shim, rbenv determines which Ruby version to use by +reading it from the following sources, in this order: + +1. The `RBENV_VERSION` environment variable, if specified. You can use + the [`rbenv shell`](#rbenv-shell) command to set this environment + variable in your current shell session. + +2. The application-specific `.ruby-version` file in the current + directory, if present. You can modify the current directory's + `.ruby-version` file with the [`rbenv local`](#rbenv-local) + command. + +3. The first `.ruby-version` file found by searching each parent + directory until reaching the root of your filesystem, if any. + +4. The global `~/.rbenv/version` file. You can modify this file using + the [`rbenv global`](#rbenv-global) command. If the global version + file is not present, rbenv assumes you want to use the "system" + Ruby—i.e. whatever version would be run if rbenv weren't in your + path. + +### Locating the Ruby Installation + +Once rbenv has determined which version of Ruby your application has +specified, it passes the command along to the corresponding Ruby +installation. + +Each Ruby version is installed into its own directory under +`~/.rbenv/versions`. For example, you might have these versions +installed: + +* `~/.rbenv/versions/1.8.7-p371/` +* `~/.rbenv/versions/1.9.3-p327/` +* `~/.rbenv/versions/jruby-1.7.1/` + +Version names to rbenv are simply the names of the directories in +`~/.rbenv/versions`. + +## Installation **Compatibility note**: rbenv is _incompatible_ with RVM. Please make sure to fully uninstall RVM and remove any references to it from @@ -76,7 +145,7 @@ and then invoke the corresponding executable. If you're on Mac OS X, consider [installing with Homebrew](#homebrew-on-mac-os-x). -### Basic GitHub Checkout ### +### Basic 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. @@ -138,7 +207,7 @@ easy to fork and contribute any changes back upstream. $ rbenv rehash ~~~ -#### Upgrading #### +#### Upgrading If you've installed rbenv manually using git, you can upgrade your installation to the cutting-edge version at any time. @@ -153,15 +222,10 @@ To use a specific release of rbenv, check out the corresponding tag: ~~~ sh $ cd ~/.rbenv $ git fetch -$ git tag -v0.1.0 -v0.1.1 -v0.1.2 -v0.2.0 -$ git checkout v0.2.0 +$ git checkout v0.3.0 ~~~ -### Homebrew on Mac OS X ### +### Homebrew on Mac OS X You can also install rbenv using the [Homebrew](http://mxcl.github.com/homebrew/) package manager on Mac OS @@ -179,7 +243,7 @@ Afterwards you'll still need to add `eval "$(rbenv init -)"` to your profile as stated in the caveats. You'll only ever have to do this once. -### Neckbeard Configuration ### +### Neckbeard Configuration Skip this section unless you must know what every line in your shell profile is doing. @@ -211,7 +275,7 @@ opposed to this idea. Here's what `rbenv init` actually does: Run `rbenv init -` for yourself to see exactly what happens under the hood. -### Uninstalling Ruby Versions ### +### Uninstalling Ruby Versions As time goes on, Ruby versions you install will accumulate in your `~/.rbenv/versions` directory. @@ -225,12 +289,12 @@ The [ruby-build](https://github.com/sstephenson/ruby-build) plugin provides an `rbenv uninstall` command to automate the removal process. -## Command Reference ## +## Command Reference Like `git`, the `rbenv` command delegates to subcommands based on its first argument. The most common subcommands are: -### rbenv local ### +### rbenv local Sets a local application-specific Ruby version by writing the version name to a `.ruby-version` file in the current directory. This version @@ -250,7 +314,7 @@ file named `.rbenv-version`. For backwards compatibility, rbenv will read a local version specified in an `.rbenv-version` file, but a `.ruby-version` file in the same directory will take precedence. -### rbenv global ### +### 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 @@ -265,7 +329,7 @@ The special version name `system` tells rbenv to use the system Ruby When run without a version number, `rbenv global` reports the currently configured global version. -### rbenv shell ### +### rbenv shell Sets a shell-specific Ruby version by setting the `RBENV_VERSION` environment variable in your shell. This version overrides @@ -285,7 +349,7 @@ prefer not to use shell integration, you may simply set the $ export RBENV_VERSION=jruby-1.7.1 -### rbenv versions ### +### rbenv versions Lists all Ruby versions known to rbenv, and shows an asterisk next to the currently active version. @@ -298,7 +362,7 @@ the currently active version. rbx-1.2.4 ree-1.8.7-2011.03 -### rbenv version ### +### rbenv version Displays the currently active Ruby version, along with information on how it was set. @@ -306,7 +370,7 @@ how it was set. $ rbenv version 1.8.7-p352 (set by /Volumes/37signals/basecamp/.ruby-version) -### rbenv rehash ### +### rbenv rehash Installs shims for all Ruby executables known to rbenv (i.e., `~/.rbenv/versions/*/bin/*`). Run this command after you install a new @@ -314,7 +378,7 @@ version of Ruby, or install a gem that provides commands. $ rbenv rehash -### rbenv which ### +### rbenv which Displays the full path to the executable that rbenv will invoke when you run the given command. @@ -322,7 +386,7 @@ you run the given command. $ rbenv which irb /Users/sam/.rbenv/versions/1.9.3-p327/bin/irb -### rbenv whence ### +### rbenv whence Lists all Ruby versions with the given command installed. @@ -331,7 +395,7 @@ Lists all Ruby versions with the given command installed. jruby-1.7.1 ree-1.8.7-2011.03 -## Development ## +## Development The rbenv source code is [hosted on GitHub](https://github.com/sstephenson/rbenv). It's clean, modular, @@ -340,7 +404,7 @@ 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). -### Version History ### +### Version History **0.3.0** (December 25, 2011) @@ -416,7 +480,7 @@ tracker](https://github.com/sstephenson/rbenv/issues). * Initial public release. -### License ### +### License (The MIT license)