Definitions

Build definitions are simple shell scripts that get sourced in the ruby-build environment so they can invoke functions that fetch necessary packages and compile them into the destination directory.

The basic invocation from a build definition is the function to download and install a package from a tarball:

install_package PACKAGE_NAME PACKAGE_URL#SHA2 [BUILD_STEPS...] [--if CONDITION]

PACKAGE_URL specifies the location of the tarball where the package is published. After download, its signature verified against the optional SHA2 checksum.

PACKAGE_NAME is the name of the directory to cd into after extracting the tarball. The subsequent BUILD_STEPS will be executed within that directory.

Alternatively, a package may be retrieved via git or SVN:

install_git PACKAGE_NAME GIT_URL BRANCH [...]
install_svn PACKAGE_NAME SVN_URL REVISION [...]

BUILD_STEPS is a list of operations to run in order to complete the installation of a Ruby version. If empty, the list defaults to "standard".

CONDITION is a way to specify that this package is optional and will only be installed if the function of the same name returns a success status. Some condition functions used in built-in definitions are:

• needs_yaml: true if there isn't an adequate libyaml found on the system
• has_broken_mac_openssl: true for Apple-patched openssl v0.9.8

Build steps

Pre-build steps:

• ldflags_dirs: Ensures that directories listed in LDFLAGS exist. Necessary workaround for some Ruby versions.
• auto_tcltk: Detects XQuartz on OS X or disables TK.
• autoconf: Runs autoconf. Prerequisite for "standard" step when fetching Ruby versions from git/SVN.

Build steps:

• standard: ./configure + make. This is the default.
• ree_installer: invokes REE's own ./installer.
• rbx: bundle + ./configure + rake install for Rubinius.
• mruby: rake
• maglev: ./install.sh
• topaz: copies over pre-built Topaz.
• jruby: copies over pre-built JRuby.
• ruby: ruby setup.rb. Used when installing RubyGems.
• mac_openssl: builds OpenSSL on OS X.

Post-build steps:

• verify_openssl: Checks that openssl extension can be loaded.

Constraints

These constraints should appear in the beginning of the build definition to check whether the system is compatible with the Ruby version:

• require_gcc: ensures that gcc is not LLVM-based. Required check for Ruby <= 1.9.3-p0.
• require_java7: necessary for JRuby 9000 operation.

Hooks

Before and after installing each package, ruby-build invokes these functions:

before_install_package PACKAGE_NAME
after_install_package PACKAGE_NAME

You can take advantage of this by defining these functions in the definition itself and filtering by package name as necessary:

before_install_package() {
  local package_name="$1"
  case "$package_name" in
  ruby-* )
    # do something for all Ruby packages
    ;;
  esac
}

install_package ...