Merge branch 'readme-update'

# 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 is a command-line utility that makes it easy to install virtually any

version of Ruby, from source.

It is available as a plugin for [rbenv][] that

provides the `rbenv install` command, 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.

    git clone https://github.com/rbenv/ruby-build.git ~/.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.

### Installing as a standalone program (advanced)

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.

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

    cd ruby-build

    ./install.sh

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.

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.

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

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.

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

Homebrew.*

```sh

# Using Homebrew on macOS

$ brew install ruby-build

    brew install ruby-build

# As an rbenv plugin

$ mkdir -p "$(rbenv root)"/plugins

$ git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build

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

# As a standalone program

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

$ PREFIX=/usr/local ./ruby-build/install.sh

```

    brew install --HEAD ruby-build

### Upgrading

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

```sh

# Via Homebrew

$ brew update && brew upgrade ruby-build

    brew upgrade --fetch-HEAD ruby-build

# As an rbenv plugin

$ cd "$(rbenv root)"/plugins/ruby-build && git pull

```

## Usage

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)).

### Using `rbenv install` with rbenv

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,

    rbenv install 2.2.0

### Basic Usage

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

`~/.rbenv/versions`.

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.

```sh

# As an rbenv plugin

$ rbenv install --list                 # lists all available versions of Ruby

$ rbenv install 2.2.0                  # installs Ruby 2.2.0 to ~/.rbenv/versions

### Using `ruby-build` standalone

# As a standalone program

$ ruby-build --definitions             # lists all available versions of Ruby

$ ruby-build 2.2.0 ~/local/ruby-2.2.0  # installs Ruby 2.2.0 to ~/local/ruby-2.2.0

```

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.

ruby-build does not check for system dependencies before downloading and

attempting to compile the Ruby source. Please ensure that [all requisite

libraries][build-env] are available on your system.

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,

### Advanced Usage

    ruby-build 2.2.0 ~/local/ruby-2.2.0

#### Custom Build Definitions

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

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.

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

what's happening under the hood.

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

definitions.

### 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.

| Variable                 | Function                                                                                         |

| ------------------------ | ------------------------------------------------------------------------------------------------ |

| `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: `~/.rbenv/cache` if invoked as rbenv plugin)  |

| `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 only to Ruby source).                                  |

| `RUBY_MAKE_OPTS`         | Additional `make` options (applies only to Ruby source).                                         |

| `RUBY_MAKE_INSTALL_OPTS` | Additional `make install` options (applies only to Ruby source).                                 |

[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

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

files will be kept in this directory after the first successful download and

reused by subsequent invocations of `ruby-build` and `rbenv install`.

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.

[wiki]: https://github.com/rbenv/ruby-build/wiki

If you can't find an answer on the wiki, open an issue on the [issue tracker][].

Be sure to include the full build log for build failures.

If you can't find an answer on the wiki, open an issue on the [issue

tracker](https://github.com/rbenv/ruby-build/issues). Be sure to include

the full build log for build failures.

  [rbenv]: https://github.com/rbenv/rbenv

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

  [wiki]: https://github.com/rbenv/ruby-build/wiki

  [build-env]: https://github.com/rbenv/ruby-build/wiki#suggested-build-environment

  [issue tracker]: https://github.com/rbenv/ruby-build/issues