Skip to content

Commit 77bd50f

Browse files
committed
Readme gains examples of installing custom defs
Add examples of passing a custom build definition file in place of a 'known' ruby version. This is meant to more clearly document how users might use a custom build definition for a recently-released ruby that is not yet bundled in ruby-build. Additionally, document in the readme how to use `RUBY_BUILD_DEFINITIONS` path environment variable to provide a _collection_ of custom build definitions. This is meant to give guidance on how an organization might share multiple custom build definitions, or downstream users of ruby-build (like asdf-ruby) might publish unreleased rubies for installation. - quibbling over wording: custom build defs _are_ recognized by ruby-build, just not bundled or available out of the box.
1 parent d56e228 commit 77bd50f

File tree

1 file changed

+24
-1
lines changed

1 file changed

+24
-1
lines changed

README.md

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,30 @@ Depending on the context, ruby-build does a little bit more than the above: for
6565

6666
#### Custom Build Definitions
6767

68-
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.
68+
To install a version of Ruby that is not available in ruby-build, you can specify the path to a custom build definition file in place of a Ruby version number.
69+
70+
```sh
71+
# As a standalone program
72+
$ ruby-build -d /path/to/3.4-custom /opt/rubies # installs to /opt/rubies/3.4-custom
73+
74+
# As an rbenv plugin
75+
$ rbenv install /path/to/3.4-custom # installs to $(rbenv root)/versions/3.4-custom
76+
```
77+
78+
You can also provide a _directory_ of custom build definition files.
79+
The path(s) will be searched along with ruby-build's bundled `share/ruby-build/` directory.
80+
(Perhaps a collection of 3rd-party build definitions published as a git repo,
81+
or an organization's custom build definitions distributed in-house.)
82+
83+
```sh
84+
# As a standalone program
85+
$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs ruby-build --definitions # lists all available versions of Ruby, including custom defs
86+
$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs ruby-build -d 3.5-custom /opt/rubies # installs to /opt/rubies/3.5-custom
87+
88+
# As an rbenv plugin
89+
$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs rbenv install --list # lists all available versions of Ruby, including custom defs
90+
$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs rbenv install 3.5-custom # installs to $(rbenv root)/versions/3.5-custom
91+
```
6992

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

0 commit comments

Comments
 (0)