ruby-build

# ruby-build

ruby-build is a command-line tool that simplifies installation of any Ruby version from source on Unix-like systems.

It is available as a plugin for [rbenv][] as the `rbenv install` command, or as a standalone program as the `ruby-build` command.

## Installation

### Homebrew package manager
```sh
brew install ruby-build
```

Upgrade with:
```sh
brew upgrade ruby-build
```

### Clone as rbenv plugin using git
```sh
git clone https://github.com/rbenv/ruby-build.git "$(rbenv root)"/plugins/ruby-build
```

Upgrade with:
```sh
git -C "$(rbenv root)"/plugins/ruby-build pull
```

### Install manually as a standalone program

First, download a tarball from https://github.com/rbenv/ruby-build/releases/latest. Then:
```sh
tar -xzf ruby-build-*.tar.gz
PREFIX=/usr/local ./ruby-build-*/install.sh
```

## Usage

### Basic Usage

```sh
# As a standalone program
$ ruby-build --list                        # lists latest stable releases for each Ruby
$ ruby-build --definitions                 # lists all definitions, including outdated ones
$ ruby-build 3.4.9 ~/.rubies/ruby-3.4.9    # installs Ruby 3.4.9
$ ruby-build -d ruby-3.4.9 ~/.rubies       # alternate form for the previous example
$ ruby-build -d ruby-3.4 ~/.rubies         # installs latest Ruby 3.4.x

# As an rbenv plugin
$ rbenv install 3.4.9  # installs Ruby 3.4.9 to ~/.rbenv/versions/3.4.9
$ rbenv install 3      # installs latest Ruby 3.x
```

> [!WARNING]
> ruby-build mostly does not verify that system dependencies are present before downloading and attempting to compile Ruby from source. Please ensure that [all requisite libraries][build-env] such as build tools and development headers are already present on your system.

Basically, what ruby-build does when installing a Ruby version is this:
- Downloads an official tarball of Ruby source code;
- Extracts the archive into a temporary directory on your system;
- Executes `./configure --prefix=/path/to/destination` in the source code;
- Runs `make install` to compile Ruby;
- Verifies that the installed Ruby is functional.

Depending on the context, ruby-build does a little bit more than the above: for example, it will try to link Ruby to the appropriate OpenSSL version, even if that means downloading and compiling OpenSSL itself; it will discover and link to Homebrew-installed instances of some libraries like libyaml and readline, etc.

### Ruby versions

When listing "latest" Ruby versions, such as in `ruby-build --list` output, ruby-build only knows of Ruby versions that are bundled with this project. That means that when a new Ruby version comes out, ruby-build will not know about it immediately— you will have to upgrade ruby-build before you can use it to install the new Ruby version. This is because ruby-build bundles [definition files](#custom-build-definitions) for each individual Ruby version.

If it's important to you that your installer tool always consults remote resources to download the list of latest Ruby versions (without