From af2df4e74a305e4018331531e43e5d9276bb6875 Mon Sep 17 00:00:00 2001 From: Ryan Lue Date: Mon, 10 Jul 2017 14:49:08 +0800 Subject: [PATCH] Overhaul README --- README.md | 198 ++++++++++++++++++++++-------------------------------- 1 file changed, 79 insertions(+), 119 deletions(-) diff --git a/README.md b/README.md index f01eaee0..c08869ec 100644 --- a/README.md +++ b/README.md @@ -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.