Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

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

A tool to download, compile, and install Ruby on Unix-like systems.
https://github.com/rbenv/ruby-build

hacktoberfest rbenv-plugin ruby version-manager

Last synced: about 1 month ago
JSON representation

A tool to download, compile, and install Ruby on Unix-like systems.

Lists

README 

        
# 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 available versions of Ruby

$ ruby-build 3.2.2 /opt/rubies/ruby-3.2.2  # installs Ruby 3.2.2



# As an rbenv plugin

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

```



> [!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.



### Advanced Usage



#### Custom Build Definitions



To install a version of Ruby that is not recognized by ruby-build, you can specify the path to a custom build definition file in place of a Ruby version number.



Check out [default build definitions][definitions] as examples on how to write definition files.



#### Custom Build Configuration



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



| 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_HTTP_CLIENT`        | One of `aria2c`, `curl`, or `wget` to use for downloading. (Default: first one found in PATH)    |

| `RUBY_BUILD_ARIA2_OPTS`         | Additional options to pass to `aria2c` for downloading.                                          |

| `RUBY_BUILD_CURL_OPTS`          | Additional options to pass to `curl` for downloading.                                            |

| `RUBY_BUILD_WGET_OPTS`          | Additional options to pass to `wget` for downloading.                                            |

| `RUBY_BUILD_MIRROR_URL`         | Custom mirror URL root.                                                                          |

| `RUBY_BUILD_MIRROR_PACKAGE_URL` | Custom complete mirror URL (e.g. http://mirror.example.com/package-1.0.0.tar.gz).                |

| `RUBY_BUILD_SKIP_MIRROR`        | Bypass the download mirror and fetch all package files from their original URLs.                 |

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

| `RUBY_BUILD_TARBALL_OVERRIDE`   | Override the URL to fetch the ruby tarball from, optionally followed by `#checksum`.             |

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

| `NO_COLOR`                      | Disable ANSI colors in output. The default is to use colors for output connected to a terminal.  |

| `CLICOLOR_FORCE`                | Use ANSI colors in output even when not connected to a terminal.                                 |



#### Applying Patches



Both `rbenv install` and `ruby-build` commands support the `-p/--patch` flag to apply a patch to the Ruby source code before building. Patches are read from standard input:



```sh

# applying a single patch

$ rbenv install --patch 1.9.3-p429 < /path/to/ruby.patch



# applying a patch from HTTP

$ rbenv install --patch 1.9.3-p429 < <(curl -sSL http://git.io/ruby.patch)



# applying multiple patches

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

```



#### Checksum Verification



All Ruby definition files bundled with ruby-build include checksums for packages, meaning that all externally downloaded packages are automatically checked for integrity after fetching.



See the next section for more information on how to author checksums.



#### Package Mirrors



To speed up downloads, ruby-build fetches package files from a mirror hosted on

Amazon CloudFront. To benefit from this, the packages must specify their checksum:



```sh

# example:

install_package "ruby-2.6.5" "https://ruby-lang.org/ruby-2.6.5.tgz#"

```



ruby-build will first try to fetch this package from `$RUBY_BUILD_MIRROR_URL/`

(note: this is the complete URL), where `` is the checksum for the file. It

will fall back to downloading the package from the original location if:

- the package was not found on the mirror;

- the mirror is down;

- the download is corrupt, i.e. the file's checksum doesn't match;

- no tool is available to calculate the checksum; or

- `RUBY_BUILD_SKIP_MIRROR` is enabled.



You may specify a custom mirror by setting `RUBY_BUILD_MIRROR_URL`.



If a mirror site doesn't conform to the above URL format, you can specify the

complete URL by setting `RUBY_BUILD_MIRROR_PACKAGE_URL`. It behaves the same as

`RUBY_BUILD_MIRROR_URL` except being a complete URL.



The default ruby-build download mirror is sponsored by

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



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

useful if you need to use `gdb` and `memprof` with Ruby.



Source code will be kept in a parallel directory tree `~/.rbenv/sources` when

using `--keep` with the `rbenv install` command. You should specify the

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.



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.



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

  [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