Skip to content

Commit af2df4e

Browse files
committed
Overhaul README
1 parent 476d09b commit af2df4e

File tree

1 file changed

+79
-119
lines changed

1 file changed

+79
-119
lines changed

README.md

Lines changed: 79 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -1,149 +1,110 @@
11
# ruby-build
22

3-
ruby-build is an [rbenv](https://github.com/rbenv/rbenv) plugin that
4-
provides an `rbenv install` command to compile and install different versions
5-
of Ruby on UNIX-like systems.
6-
7-
You can also use ruby-build without rbenv in environments where you need
8-
precise control over Ruby version installation.
9-
10-
See the [list of releases](https://github.com/rbenv/ruby-build/releases)
11-
for changes in each version.
3+
ruby-build (a.k.a. `rbenv install`) is a \*NIX utility that makes it easy to
4+
install virtually any version of Ruby, from source.
125

6+
It is available as a plugin for [rbenv](https://github.com/rbenv/rbenv), or as
7+
a standalone program.
138

149
## Installation
1510

16-
### Installing as an rbenv plugin (recommended)
17-
18-
Installing ruby-build as an rbenv plugin will give you access to the `rbenv
19-
install` command.
20-
21-
git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
22-
23-
This will install the latest development version of ruby-build into the
24-
`~/.rbenv/plugins/ruby-build` directory. From that directory, you can check out
25-
a specific release tag. To update ruby-build, run `git pull` to download the
26-
latest changes.
27-
28-
### Installing as a standalone program (advanced)
11+
**If you installed rbenv via Homebrew, you already have ruby-build.**
2912

30-
Installing ruby-build as a standalone program will give you access to the
31-
`ruby-build` command for precise control over Ruby version installation. If you
32-
have rbenv installed, you will also be able to use the `rbenv install` command.
13+
# As an rbenv plugin (Recommended)
14+
$ git clone https://github.com/rbenv/ruby-build ~/.rbenv/plugins/ruby-build
3315

34-
git clone https://github.com/rbenv/ruby-build.git
35-
cd ruby-build
36-
./install.sh
16+
# As a standalone program (Advanced)
17+
$ git clone https://github.com/rbenv/ruby-build && $ ruby-build/install.sh
3718

38-
This will install ruby-build into `/usr/local`. If you do not have write
39-
permission to `/usr/local`, you will need to run `sudo ./install.sh` instead.
40-
You can install to a different prefix by setting the `PREFIX` environment
41-
variable.
19+
For more details on installing as a standalone program, see the [install
20+
script source](https://github.com/rbenv/ruby-build/blob/master/install.sh).
4221

43-
To update ruby-build after it has been installed, run `git pull` in your cloned
44-
copy of the repository, then re-run the install script.
22+
### Upgrading
4523

46-
### Installing with Homebrew (for OS X users)
24+
# From source
25+
$ cd ~/.rbenv/plugins/ruby-build
26+
$ git pull
4727

48-
Mac OS X users can install ruby-build with the [Homebrew](http://brew.sh)
49-
package manager. This will give you access to the `ruby-build` command. If you
50-
have rbenv installed, you will also be able to use the `rbenv install` command.
28+
# via Homebrew
29+
$ brew update && brew upgrade ruby-build # simple upgrade
30+
$ brew install --HEAD ruby-build # installs the latest development release
31+
$ brew upgrade --fetch-HEAD ruby-build # upgrades the HEAD package
5132

52-
*This is the recommended method of installation if you installed rbenv with
53-
Homebrew.*
33+
## Usage
5434

55-
brew install ruby-build
35+
#### DEPENDENCY WARNING
5636

57-
Or, if you would like to install the latest development release:
37+
Due to the considerable variation between different systems, ruby-build does
38+
not check for dependencies before downloading and attempting to compile the
39+
Ruby source. Before using ruby-build, please [consult the
40+
wiki](https://github.com/rbenv/ruby-build/wiki#suggested-build-environment) to
41+
ensure that all the requisite libraries are available on your system.
42+
Otherwise, you may encounter segmentation faults or other critical errors.
5843

59-
brew install --HEAD ruby-build
44+
### Basic Usage
6045

61-
To upgrade the HEAD package use `--fetch-HEAD` option:
46+
#### With rbenv
6247

63-
brew upgrade --fetch-HEAD ruby-build
48+
ruby-build extends rbenv with the subcommand `rbenv install`. To see which versions of Ruby it knows about, run:
6449

65-
## Usage
50+
$ rbenv install --list
51+
52+
To install one, call it again with the exact version name:
6653

67-
Before you begin, you should ensure that your build environment has the proper
68-
system dependencies for compiling the wanted Ruby version (see our [recommendations](https://github.com/rbenv/ruby-build/wiki#suggested-build-environment)).
54+
$ rbenv install 2.2.0
6955

70-
### Using `rbenv install` with rbenv
56+
`rbenv install` supports tab completion (if rbenv is properly configured). Each Ruby version built in this way is installed to `~/.rbenv/versions`.
7157

72-
To install a Ruby version for use with rbenv, run `rbenv install` with the
73-
exact name of the version you want to install. For example,
58+
See `rbenv help install` for more.
7459

75-
rbenv install 2.2.0
60+
#### As a standalone
7661

77-
Ruby versions will be installed into a directory of the same name under
78-
`~/.rbenv/versions`.
62+
To see which versions of Ruby ruby-build knows about, run:
7963

80-
To see a list of all available Ruby versions, run `rbenv install --list`. You
81-
may also tab-complete available Ruby versions if your rbenv installation is
82-
properly configured.
64+
$ ruby-build --definitions
65+
66+
To install one, specify both the exact version name and the destination directory:
8367

84-
### Using `ruby-build` standalone
68+
$ ruby-build 2.2.0 ~/local/ruby-2.2.0
8569

86-
If you have installed ruby-build as a standalone program, you can use the
87-
`ruby-build` command to compile and install Ruby versions into specific
88-
locations.
70+
### Advanced Usage
8971

90-
Run the `ruby-build` command with the exact name of the version you want to
91-
install and the full path where you want to install it. For example,
72+
#### Custom Build Definitions
9273

93-
ruby-build 2.2.0 ~/local/ruby-2.2.0
74+
If you wish to develop and install a version of Ruby that is not yet supported
75+
by ruby-build, you may specify the path to a custom “build definition file” in
76+
place of a Ruby version number.
9477

95-
To see a list of all available Ruby versions, run `ruby-build --definitions`.
78+
Use the [default build definitions][definitions] as a template for your custom
79+
definitions.
9680

97-
Pass the `-v` or `--verbose` flag to `ruby-build` as the first argument to see
98-
what's happening under the hood.
81+
[definitions]: https://github.com/rbenv/ruby-build/tree/master/share/ruby-build
9982

100-
### Custom definitions
83+
#### Custom Build Configuration
10184

102-
Both `rbenv install` and `ruby-build` accept a path to a custom definition file
103-
in place of a version name. Custom definitions let you develop and install
104-
versions of Ruby that are not yet supported by ruby-build.
85+
The build process may be configured through the following environment variables:
10586

106-
See the [ruby-build built-in definitions][definitions] as a starting point for
107-
custom definition files.
87+
| `TMPDIR` | Where temporary files are stored. |
88+
| `RUBY_BUILD_BUILD_PATH` | Where sources are downloaded and built. (Default: a timestamped subdirectory of `TMPDIR`) |
89+
| `RUBY_BUILD_CACHE_PATH` | Where to cache downloaded package files. (Default: unset) |
90+
| `RUBY_BUILD_MIRROR_URL` | Custom mirror URL root. |
91+
| `RUBY_BUILD_SKIP_MIRROR` | Always download from official sources, not mirrors. (Default: unset) |
92+
| `RUBY_BUILD_ROOT` | Custom build definition directory. (Default: `share/ruby-build`) |
93+
| `RUBY_BUILD_DEFINITIONS` | Additional paths to search for build definitions. (Colon-separated list) |
94+
| `CC` | Path to the C compiler. |
95+
| `RUBY_CFLAGS` | Additional `CFLAGS` options (_e.g.,_ to override `-O3`). |
96+
| `CONFIGURE_OPTS` | Additional `./configure` options. |
97+
| `MAKE` | Custom `make` command (_e.g.,_ `gmake`). |
98+
| `MAKE_OPTS` / `MAKEOPTS` | Additional `make` options. |
99+
| `MAKE_INSTALL_OPTS` | Additional `make install` options. |
100+
| `RUBY_CONFIGURE_OPTS` | Additional `./configure` options (applies to MRI only, not dependent packages; _e.g.,_ libyaml). |
101+
| `RUBY_MAKE_OPTS` | Additional `make` options (applies to MRI only, not dependent packages; _e.g.,_ libyaml) |
102+
| `RUBY_MAKE_INSTALL_OPTS` | Additional `make install` options (applies to MRI only, not dependent packages; _e.g.,_ libyaml) |
108103

109-
[definitions]: https://github.com/rbenv/ruby-build/tree/master/share/ruby-build
104+
#### Applying Patches
110105

111-
### Special environment variables
112-
113-
You can set certain environment variables to control the build process.
114-
115-
* `TMPDIR` sets the location where ruby-build stores temporary files.
116-
* `RUBY_BUILD_BUILD_PATH` sets the location in which sources are downloaded and
117-
built. By default, this is a subdirectory of `TMPDIR`.
118-
* `RUBY_BUILD_CACHE_PATH`, if set, specifies a directory to use for caching
119-
downloaded package files.
120-
* `RUBY_BUILD_MIRROR_URL` overrides the default mirror URL root to one of your
121-
choosing.
122-
* `RUBY_BUILD_SKIP_MIRROR`, if set, forces ruby-build to download packages from
123-
their original source URLs instead of using a mirror.
124-
* `RUBY_BUILD_ROOT` overrides the default location from where build definitions
125-
in `share/ruby-build/` are looked up.
126-
* `RUBY_BUILD_DEFINITIONS` can be a list of colon-separated paths that get
127-
additionally searched when looking up build definitions.
128-
* `CC` sets the path to the C compiler.
129-
* `RUBY_CFLAGS` lets you pass additional options to the default `CFLAGS`. Use
130-
this to override, for instance, the `-O3` option.
131-
* `CONFIGURE_OPTS` lets you pass additional options to `./configure`.
132-
* `MAKE` lets you override the command to use for `make`. Useful for specifying
133-
GNU make (`gmake`) on some systems.
134-
* `MAKE_OPTS` (or `MAKEOPTS`) lets you pass additional options to `make`.
135-
* `MAKE_INSTALL_OPTS` lets you pass additional options to `make install`.
136-
* `RUBY_CONFIGURE_OPTS`, `RUBY_MAKE_OPTS` and `RUBY_MAKE_INSTALL_OPTS` allow
137-
you to specify configure and make options for buildling MRI. These variables
138-
will be passed to Ruby only, not any dependent packages (e.g. libyaml).
139-
140-
### Applying patches to Ruby before compiling
141-
142-
Both `rbenv install` and `ruby-build` support the `--patch` (`-p`) flag that
143-
signals that a patch from stdin should be applied to Ruby, JRuby, or Rubinius
144-
source code before the `./configure` and compilation steps.
145-
146-
Example usage:
106+
Both `rbenv install` and `ruby-build` support the `--patch` (`-p`) flag to apply a patch to the Ruby (/JRuby/Rubinius)
107+
source code before building. Patches are read from `STDIN`:
147108

148109
```sh
149110
# applying a single patch
@@ -156,7 +117,7 @@ $ rbenv install --patch 1.9.3-p429 < <(curl -sSL http://git.io/ruby.patch)
156117
$ cat fix1.patch fix2.patch | rbenv install --patch 1.9.3-p429
157118
```
158119

159-
### Checksum verification
120+
#### Checksum Verification
160121

161122
If you have the `shasum`, `openssl`, or `sha256sum` tool installed, ruby-build will
162123
automatically verify the SHA2 checksum of each downloaded package before
@@ -165,12 +126,12 @@ installing it.
165126
Checksums are optional and specified as anchors on the package URL in each
166127
definition. (All bundled definitions include checksums.)
167128

168-
### Package download mirrors
129+
#### Package Mirrors
169130

170-
ruby-build will first attempt to download package files from a mirror hosted on
171-
Amazon CloudFront. If a package is not available on the mirror, if the mirror
172-
is down, or if the download is corrupt, ruby-build will fall back to the
173-
official URL specified in the definition file.
131+
By default, ruby-build downloads package files from a mirror hosted on Amazon
132+
CloudFront. If a package is not available on the mirror, if the mirror is
133+
down, or if the download is corrupt, ruby-build will fall back to the official
134+
URL specified in the definition file.
174135

175136
You can point ruby-build to another mirror by specifying the
176137
`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.
184145
The official ruby-build download mirror is sponsored by
185146
[Basecamp](https://basecamp.com/).
186147

187-
### Package download caching
148+
#### Package Caching
188149

189150
You can instruct ruby-build to keep a local cache of downloaded package files
190151
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`.
194155
The `rbenv install` command defaults this path to `~/.rbenv/cache`, so in most
195156
cases you can enable download caching simply by creating that directory.
196157

197-
### Keeping the build directory after installation
158+
#### Keeping the build directory after installation
198159

199160
Both `ruby-build` and `rbenv install` accept the `-k` or `--keep` flag, which
200161
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
205166
location of the source code with the `RUBY_BUILD_BUILD_PATH` environment
206167
variable when using `--keep` with `ruby-build`.
207168

208-
209169
## Getting Help
210170

211171
Please see the [ruby-build wiki][wiki] for solutions to common problems.

0 commit comments

Comments
 (0)