From 77bd50f8ed5015fd089d5453d66c5f59a2cea2b7 Mon Sep 17 00:00:00 2001 From: Jason Karns Date: Wed, 21 May 2025 12:54:18 -0400 Subject: [PATCH] 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. --- README.md | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 28fc8f3842..6e51cca2e7 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,30 @@ Depending on the context, ruby-build does a little bit more than the above: for #### 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. +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. + +```sh +# As a standalone program +$ ruby-build -d /path/to/3.4-custom /opt/rubies # installs to /opt/rubies/3.4-custom + +# As an rbenv plugin +$ rbenv install /path/to/3.4-custom # installs to $(rbenv root)/versions/3.4-custom +``` + +You can also provide a _directory_ of custom build definition files. +The path(s) will be searched along with ruby-build's bundled `share/ruby-build/` directory. +(Perhaps a collection of 3rd-party build definitions published as a git repo, +or an organization's custom build definitions distributed in-house.) + +```sh +# As a standalone program +$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs ruby-build --definitions # lists all available versions of Ruby, including custom defs +$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs ruby-build -d 3.5-custom /opt/rubies # installs to /opt/rubies/3.5-custom + +# As an rbenv plugin +$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs rbenv install --list # lists all available versions of Ruby, including custom defs +$ RUBY_BUILD_DEFINITIONS=/path/to/custom/defs rbenv install 3.5-custom # installs to $(rbenv root)/versions/3.5-custom +``` Check out [default build definitions][definitions] as examples on how to write definition files.