Overhaul README

# ruby-build

ruby-build is an [rbenv](https://github.com/rbenv/rbenv) plugin that

provides an `rbenv install` command to compile and install different versions

of Ruby on UNIX-like systems.

You can also use ruby-build without rbenv in environments where you need

precise control over Ruby version installation.

See the [list of releases](https://github.com/rbenv/ruby-build/releases)

for changes in each version.

ruby-build (a.k.a. `rbenv install`) is a \*NIX utility that makes it easy to

install virtually any version of Ruby, from source.

It is available as a plugin for [rbenv](https://github.com/rbenv/rbenv), or as

a standalone program.

## Installation

### Installing as an rbenv plugin (recommended)

Installing ruby-build as an rbenv plugin will give you access to the `rbenv

install` command.

**If you installed rbenv via Homebrew, you already have ruby-build.**

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

    # As an rbenv plugin (Recommended)

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

This will install the latest development version of ruby-build into the

`~/.rbenv/plugins/ruby-build` directory. From that directory, you can check out

a specific release tag. To update ruby-build, run `git pull` to download the

latest changes.

    # As a standalone program (Advanced)

    $ git clone https://github.com/rbenv/ruby-build && $ ruby-build/install.sh

### Installing as a standalone program (advanced)

For more details on installing as a standalone program, see the [install

script source](https://github.com/rbenv/ruby-build/blob/master/install.sh).

Installing ruby-build as a standalone program will give you access to the

`ruby-build` command for precise control over Ruby version installation. If you

have rbenv installed, you will also be able to use the `rbenv install` command.

### Upgrading

    git clone https://github.com/rbenv/ruby-build.git

    cd ruby-build

    ./install.sh

    # From source

    $ cd ~/.rbenv/plugins/ruby-build

    $ git pull

This will install ruby-build into `/usr/local`. If you do not have write

permission to `/usr/local`, you will need to run `sudo ./install.sh` instead.

You can install to a different prefix by setting the `PREFIX` environment

variable.

    # via Homebrew

    $ brew update && brew upgrade ruby-build # simple upgrade

    $ brew install --HEAD ruby-build         # installs the latest development release

    $ brew upgrade --fetch-HEAD ruby-build   # upgrades the HEAD package

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.

## Usage

### Installing with Homebrew (for OS X users)

#### DEPENDENCY WARNING

Mac OS X users can install ruby-build with the [Homebrew](http://brew.sh)

package manager. This will give you access to the `ruby-build` command. If you

have rbenv installed, you will also be able to use the `rbenv install` command.

Due to the considerable variation between different systems, ruby-build does

not check for dependencies before downloading and attempting to compile the

Ruby source. Before using ruby-build, please [consult the

wiki](https://github.com/rbenv/ruby-build/wiki#suggested-build-environment) to

ensure that all the requisite libraries are available on your system.

Otherwise, you may encounter segmentation faults or other critical errors.

*This is the recommended method of installation if you installed rbenv with

Homebrew.*

### Basic Usage

    brew install ruby-build

#### With rbenv

Or, if you would like to install the latest development release:

ruby-build extends rbenv with the subcommand `rbenv install`. To see which versions of Ruby it knows about, run:

    brew install --HEAD ruby-build

    $ rbenv install --list

To upgrade the HEAD package use `--fetch-HEAD` option:

To install one, call it again with the exact version name:

    brew upgrade --fetch-HEAD ruby-build

    $ rbenv install 2.2.0

## Usage

`rbenv install` supports tab completion (if rbenv is properly configured). Each Ruby version built in this way is installed to `~/.rbenv/versions`.

Before you begin, you should ensure that your build environment has the proper

system dependencies for compiling the wanted Ruby version (see our [recommendations](https://github.com/rbenv/ruby-build/wiki#suggested-build-environment)).

See `rbenv help install` for more.

### Using `rbenv install` with rbenv

#### As a standalone

To install a Ruby version for use with rbenv, run `rbenv install` with the

exact name of the version you want to install. For example,

To see which versions of Ruby ruby-build knows about, run:

    rbenv install 2.2.0

    $ ruby-build --definitions

Ruby versions will be installed into a directory of the same name under

`~/.rbenv/versions`.

To install one, specify both the exact version name and the destination directory:

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.

    $ ruby-build 2.2.0 ~/local/ruby-2.2.0

### Using `ruby-build` standalone

### Advanced Usage

If you have installed ruby-build as a standalone program, you can use the

`ruby-build` command to compile and install Ruby versions into specific

locations.

#### Custom Build Definitions

Run the `ruby-build` command with the exact name of the version you want to

install and the full path where you want to install it. For example,

If you wish to develop and install a version of Ruby that is not yet supported

by ruby-build, you may specify the path to a custom “build definition file” in

place of a Ruby version number.

    ruby-build 2.2.0 ~/local/ruby-2.2.0

Use the [default build definitions][definitions] as a template for your custom

definitions.

To see a list of all available Ruby versions, run `ruby-build --definitions`.

Pass the `-v` or `--verbose` flag to `ruby-build` as the first argument to see

what's happening under the hood.

[definitions]: https://github.com/rbenv/ruby-build/tree/master/share/ruby-build

### Custom definitions

#### Custom Build Configuration

Both `rbenv install` and `ruby-build` accept a path to a custom definition file

in place of a version name. Custom definitions let you develop and install

versions of Ruby that are not yet supported by ruby-build.

The build process may be configured through the following environment variables:

See the [ruby-build built-in definitions][definitions] as a starting point for

custom definition files.

| `TMPDIR`                 | Where temporary files are stored.                                                                |

| `RUBY_BUILD_BUILD_PATH`  | Where sources are downloaded and built. (Default: a timestamped subdirectory of `TMPDIR`)        |

| `RUBY_BUILD_CACHE_PATH`  | Where to cache downloaded package files. (Default: unset)                                        |

| `RUBY_BUILD_MIRROR_URL`  | Custom mirror URL root.                                                                          |

| `RUBY_BUILD_SKIP_MIRROR` | Always download from official sources, not mirrors. (Default: unset)                             |

| `RUBY_BUILD_ROOT`        | Custom build definition directory. (Default: `share/ruby-build`)                                 |

| `RUBY_BUILD_DEFINITIONS` | Additional paths to search for build definitions. (Colon-separated list)                         |

| `CC`                     | Path to the C compiler.                                                                          |

| `RUBY_CFLAGS`            | Additional `CFLAGS` options (_e.g.,_ to override `-O3`).                                         |

| `CONFIGURE_OPTS`         | Additional `./configure` options.                                                                |

| `MAKE`                   | Custom `make` command (_e.g.,_ `gmake`).                                                         |

| `MAKE_OPTS` / `MAKEOPTS` | Additional `make` options.                                                                       |

| `MAKE_INSTALL_OPTS`      | Additional `make install` options.                                                               |

| `RUBY_CONFIGURE_OPTS`    | Additional `./configure` options (applies to MRI only, not dependent packages; _e.g.,_ libyaml). |

| `RUBY_MAKE_OPTS`         | Additional `make` options (applies to MRI only, not dependent packages; _e.g.,_ libyaml)         |

| `RUBY_MAKE_INSTALL_OPTS` | Additional `make install` options (applies to MRI only, not dependent packages; _e.g.,_ libyaml) |

[definitions]: https://github.com/rbenv/ruby-build/tree/master/share/ruby-build

#### Applying Patches

### Special environment variables

You can set certain environment variables to control the build process.

* `TMPDIR` sets the location where ruby-build stores temporary files.

* `RUBY_BUILD_BUILD_PATH` sets the location in which sources are downloaded and

  built. By default, this is a subdirectory of `TMPDIR`.

* `RUBY_BUILD_CACHE_PATH`, if set, specifies a directory to use for caching

  downloaded package files.

* `RUBY_BUILD_MIRROR_URL` overrides the default mirror URL root to one of your

  choosing.

* `RUBY_BUILD_SKIP_MIRROR`, if set, forces ruby-build to download packages from

  their original source URLs instead of using a mirror.

* `RUBY_BUILD_ROOT` overrides the default location from where build definitions

  in `share/ruby-build/` are looked up.

* `RUBY_BUILD_DEFINITIONS` can be a list of colon-separated paths that get

  additionally searched when looking up build definitions.

* `CC` sets the path to the C compiler.

* `RUBY_CFLAGS` lets you pass additional options to the default `CFLAGS`. Use

  this to override, for instance, the `-O3` option.

* `CONFIGURE_OPTS` lets you pass additional options to `./configure`.

* `MAKE` lets you override the command to use for `make`. Useful for specifying

  GNU make (`gmake`) on some systems.

* `MAKE_OPTS` (or `MAKEOPTS`) lets you pass additional options to `make`.

* `MAKE_INSTALL_OPTS` lets you pass additional options to `make install`.

* `RUBY_CONFIGURE_OPTS`, `RUBY_MAKE_OPTS` and `RUBY_MAKE_INSTALL_OPTS` allow

  you to specify configure and make options for buildling MRI. These variables

  will be passed to Ruby only, not any dependent packages (e.g. libyaml).

### Applying patches to Ruby before compiling

Both `rbenv install` and `ruby-build` support the `--patch` (`-p`) flag that

signals that a patch from stdin should be applied to Ruby, JRuby, or Rubinius

source code before the `./configure` and compilation steps.

Example usage:

Both `rbenv install` and `ruby-build` support the `--patch` (`-p`) flag to apply a patch to the Ruby (/JRuby/Rubinius)

source code before building. Patches are read from `STDIN`:

```sh

# applying a single patch

$ cat fix1.patch fix2.patch | rbenv install --patch 1.9.3-p429

```

### Checksum verification

#### Checksum Verification

If you have the `shasum`, `openssl`, or `sha256sum` tool installed, ruby-build will

automatically verify the SHA2 checksum of each downloaded package before

Checksums are optional and specified as anchors on the package URL in each

definition. (All bundled definitions include checksums.)

### Package download mirrors

#### Package Mirrors

ruby-build will first attempt to download package files from a mirror hosted on

Amazon CloudFront. If a package is not available on the mirror, if the mirror

is down, or if the download is corrupt, ruby-build will fall back to the

official URL specified in the definition file.

By default, ruby-build downloads package files from a mirror hosted on Amazon

CloudFront. If a package is not available on the mirror, if the mirror is

down, or if the download is corrupt, ruby-build will fall back to the official

URL specified in the definition file.

You can point ruby-build to another mirror by specifying the

`RUBY_BUILD_MIRROR_URL` environment variable--useful if you'd like to run your

The official ruby-build download mirror is sponsored by

[Basecamp](https://basecamp.com/).

### Package download caching

#### Package Caching

You can instruct ruby-build to keep a local cache of downloaded package files

by setting the `RUBY_BUILD_CACHE_PATH` environment variable. When set, package

The `rbenv install` command defaults this path to `~/.rbenv/cache`, so in most

cases you can enable download caching simply by creating that directory.

### Keeping the build directory after installation

#### Keeping the build directory after installation

Both `ruby-build` and `rbenv install` accept the `-k` or `--keep` flag, which

tells ruby-build to keep the downloaded source after installation. This can be

location of the source code with the `RUBY_BUILD_BUILD_PATH` environment

variable when using `--keep` with `ruby-build`.

## Getting Help

Please see the [ruby-build wiki][wiki] for solutions to common problems.