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: 3 days ago
JSON representation
A tool to download, compile, and install Ruby on Unix-like systems.
- Host: GitHub
- URL: https://github.com/rbenv/ruby-build
- Owner: rbenv
- License: mit
- Created: 2011-08-02T13:47:29.000Z (over 13 years ago)
- Default Branch: master
- Last Pushed: 2024-10-17T17:08:32.000Z (about 2 months ago)
- Last Synced: 2024-10-29T11:13:12.818Z (about 1 month ago)
- Topics: hacktoberfest, rbenv-plugin, ruby, version-manager
- Language: Shell
- Homepage: https://rbenv.org/man/ruby-build.1
- Size: 3.13 MB
- Stars: 3,891
- Watchers: 103
- Forks: 784
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-starred-test - rbenv/ruby-build - A tool to download, compile, and install Ruby on Unix-like systems. (Shell)
- awesome-starred - rbenv/ruby-build - A tool to download, compile, and install Ruby on Unix-like systems. (ruby)
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 latest stable releases for each Ruby
$ ruby-build --definitions # lists all definitions, including outdated ones
$ ruby-build 3.2.2 ~/.rubies/ruby-3.2.2 # installs Ruby 3.2.2
$ ruby-build -d ruby-3.2.2 ~/.rubies # alternate form for the previous example
# 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_TARBALL_OVERRIDE` | Override the URL to fetch the ruby tarball from, optionally followed by `#checksum`. |
| `RUBY_BUILD_DEFINITIONS` | Colon-separated list of paths to search for build definition files. |
| `RUBY_BUILD_ROOT` | The path prefix to search for build definitions files. *Deprecated:* use `RUBY_BUILD_DEFINITIONS`|
| `RUBY_BUILD_VENDOR_OPENSSL` | Build and vendor openssl even if the system openssl is compatible |
| `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