mirrors/rbenv-ruby-build
1
0
Fork 0
mirror of https://github.com/rbenv/ruby-build.git synced 2024-12-28 20:55:31 +01:00
Code Issues Projects Releases Packages Wiki Activity

Overhaul README

Browse source
This commit is contained in:
Ryan Lue 2017-07-10 14:49:08 +08:00
parent 476d09b66a
commit af2df4e74a
1 changed files with 79 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

198
README.md
View file

@ -1,149 +1,110 @@
# 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)
**If you installed rbenv via Homebrew, you already have ruby-build.**
Installing ruby-build as an rbenv plugin will give you access to the `rbenv
install` command.
# As an rbenv plugin (Recommended)
$ git clone https://github.com/rbenv/ruby-build ~/.rbenv/plugins/ruby-build
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
# As a standalone program (Advanced)
$ git clone https://github.com/rbenv/ruby-build && $ ruby-build/install.sh
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.
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 as a standalone program (advanced)
### Upgrading
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.
# From source
$ cd ~/.rbenv/plugins/ruby-build
$ git pull
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.*
brew install ruby-build
Or, if you would like to install the latest development release:
brew install --HEAD ruby-build
To upgrade the HEAD package use `--fetch-HEAD` option:
brew upgrade --fetch-HEAD ruby-build
# 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
## 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)).
#### DEPENDENCY WARNING
### Using `rbenv install` with rbenv
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.
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,
### Basic Usage
rbenv install 2.2.0
#### With rbenv
Ruby versions will be installed into a directory of the same name under
`~/.rbenv/versions`.
ruby-build extends rbenv with the subcommand `rbenv install`. To see which versions of Ruby it knows about, run:
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.
$ rbenv install --list
To install one, call it again with the exact version name:
### Using `ruby-build` standalone
$ rbenv install 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.
`rbenv install` supports tab completion (if rbenv is properly configured). Each Ruby version built in this way is installed to `~/.rbenv/versions`.
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,
See `rbenv help install` for more.
ruby-build 2.2.0 ~/local/ruby-2.2.0
#### As a standalone
To see a list of all available Ruby versions, run `ruby-build --definitions`.
To see which versions of Ruby ruby-build knows about, run:
Pass the `-v` or `--verbose` flag to `ruby-build` as the first argument to see
what's happening under the hood.
$ ruby-build --definitions
To install one, specify both the exact version name and the destination directory:
### Custom definitions
$ ruby-build 2.2.0 ~/local/ruby-2.2.0
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.
### Advanced Usage
See the [ruby-build built-in definitions][definitions] as a starting point for
custom definition files.
#### Custom 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.
Use the [default build definitions][definitions] as a template for your custom
definitions.
[definitions]: https://github.com/rbenv/ruby-build/tree/master/share/ruby-build
### Special environment variables
#### Custom Build Configuration
You can set certain environment variables to control the build process.
The build process may be configured through the following environment variables:
* `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).
| `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) |
### Applying patches to Ruby before compiling
#### Applying Patches
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
@ -156,7 +117,7 @@ $ rbenv install --patch 1.9.3-p429 < <(curl -sSL http://git.io/ruby.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
@ -165,12 +126,12 @@ installing it.
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
@ -184,7 +145,7 @@ mirror by setting the `RUBY_BUILD_SKIP_MIRROR` environment variable.
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
@ -194,7 +155,7 @@ 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
@ -205,7 +166,6 @@ 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.