-
Notifications
You must be signed in to change notification settings - Fork 785
Home
ruby-build is a tool that downloads and compiles various versions of Ruby. It is
exposed as rbenv install through rbenv or simply as ruby-build when
used standalone.
ruby-build will try its best to download and compile the wanted Ruby version, but sometimes compilation fails because of unmet system dependencies, or compilation succeeds but the new Ruby version exhibits weird failures at runtime. The following instructions are our recommendations for a reasonable build environment.
If you haven't done so, install Xcode Command Line Tools
(xcode-select --install) and Homebrew.
For Ruby versions 2.x–3.0:
brew install [email protected] readline libyaml gmp
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix [email protected])"Ruby 3.1 and above requires OpenSSL 3:
brew install openssl@3 readline libyaml gmp
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix openssl@3)"Using RUBY_CONFIGURE_OPTS to link to a specific OpenSSL installation like suggested above is not a strict requirement for installing Ruby on macOS, but it will speed up your Ruby installation and avoid any OpenSSL compilation issues.
Ruby 3.2 and above requires the Rust compiler if you want to have YJIT enabled:
brew install rustIn a MacPorts environment:
sudo port install libyaml openssl3 # if building OpenSSL 3
export RUBY_CONFIGURE_OPTS="--with-openssl-dir=/opt/local/libexec/openssl3 --with-libyaml-dir=/opt/local/"apt-get install autoconf patch build-essential rustc libssl-dev libyaml-dev libreadline6-dev zlib1g-dev libgmp-dev libncurses5-dev libffi-dev libgdbm6 libgdbm-dev libdb-dev uuid-devDepending on your OS version, libgdbm6 won't be available. In that case, try an earlier version, such as libgdbm5.
yum install -y gcc-6 patch bzip2 openssl-devel libyaml-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-develIf you want to use YJIT, you need to use after RHEL8 and install rust.
yum install -y rustdnf install -y gcc rust patch make bzip2 openssl-devel libyaml-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-develFor Ruby < 3 you'll also need to install the following perl modules:
dnf install perl-FindBin perl-File-Comparepkg install devel/autoconf devel/bison devel/patch lang/gcc lang/rust databases/gdbm devel/gmake devel/libffi textproc/libyaml devel/ncurses security/openssl devel/readlinezypper install -y gcc make rust patch automake bzip2 libopenssl-devel libyaml-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-develpacman -S --needed base-devel rust libffi libyaml openssl zlibIf needed, install gcc6 from the AUR.
apk add build-base gcc6 patch bzip2 libffi-dev openssl-dev ncurses-dev gdbm-dev zlib-dev readline-dev yaml-devIf you plan to use YJIT, the rust package will also be required
apk add rustIf you have trouble installing a Ruby version, first try to update ruby-build to get the latest bug fixes and Ruby definitions.
First locate it on your system:
which ruby-build
ls "$(rbenv root)"/pluginsIf it's in /opt/homebrew/bin or /usr/local/bin on a Mac, you've probably installed it via
Homebrew:
brew upgrade ruby-build
Or, if you have it installed via git as an rbenv plugin:
git -C "$(rbenv root)"/plugins/ruby-build pullFor more troubleshooting tips, check the Discussions section.
The Ruby openssl extension was not compiled. Missing the OpenSSL lib?
You probably need to install openssl development headers:
- Ubuntu:
apt-get install libssl-dev - Fedora:
yum install openssl-devel - Void Linux:
xbps-install -Su openssl-devel
MacPorts users may need to specify OpenSSL's location manually:
RUBY_CONFIGURE_OPTS=--with-openssl-dir=/opt/local rbenv installSome macOS users on M1 laptops have experienced the following failures:
dyld: could not load inserted library
...
incompatible architecture (have 'arm64', need 'arm64e')
See this discussion for workarounds.
Ruby < 2.4 is not compatible with OpenSSL 1.1.
When building Ruby 2.3 or older, you must ensure that OpenSSL 1.0 is available
somewhere on the system and point to it via the --with-openssl-dir configure
flag. At the moment, most Linux distributions that come with OpenSSL 1.1 have a
separate package for OpenSSL 1.0.
For example:
# with Homebrew on macOS
brew install rbenv/tap/[email protected]
RUBY_CONFIGURE_OPTS="--with-openssl-dir=$(brew --prefix [email protected])" rbenv install 2.3.8If an OpenSSL 1.0 package no longer exists for your distro, you can install a shared library from source by downloading a 1.0.x version of the source, unarchiving the files, then running the following from a terminal:
# cd into source directory you downloaded and unarchived
./config --prefix=/opt/openssl-1.0 shared
make
make test
sudo make install
RUBY_CONFIGURE_OPTS="--with-openssl-dir=/opt/openssl-1.0" rbenv install 2.3.8In Arch-based Linux, this is done with a different option. See this Arch Wiki page.
OpenSSL does not come with CA certificates and Error during failsafe response: SSL_connect returned=1 errno=0 state=error: certificate verify failed will occur if you don't install the CA Certificates for OpenSSL 1.0.
With Ubuntu for example, you can install the ca-certificate package and link to the CA certificates
sudo apt install ca-certificates
rm -rf /opt/openssl-1.0/ssl/certs
ln -s /etc/ssl/certs /opt/openssl-1.0/ssl/certsThere can be different causes of this error and none of them are usually immediately apparent. However, often the cause is that the build environment is incomplete or broken. Make sure you first follow the instructions in Suggested build environment.
Having the Anaconda set of Python tools is known to cause issues with building Ruby. The only know solution so far is to uninstall Anaconda.
This can occur if you have more than one disk drive and your home
directory is physically mounted on a volume that might have a space in its name,
such as Macintosh HD:
$ df
/dev/disk2 ... /
/dev/disk1s2 ... /Volumes/Macintosh HD
The easiest solution is to avoid building a Ruby version to any path that has
space characters in it. So instead of building into
~/.rbenv/versions/<version>, which is the default for rbenv install <version>, instead you could install into /opt/rubies/<version> and symlink
/opt/rubies as ~/.rbenv/versions so rbenv continues to work as before.
WARNING: You don't have ${HOME}/.gem/ruby/1.8/bin in your PATH,
gem executables will not run.
The system Ruby creates the /etc/gemrc file which contains --user-install by
default so that pacman-managed gems are not mixed up with externally installed
gems. This setting affects the gem command in all Ruby versions, so all gems
will get installed under ~/.gem instead of the default install path
$(rbenv prefix)/lib/ruby/gems.
This is not a problem for ruby-build, but rbenv doesn't play well with
--user-install, since it can't discover gem executables that were placed under
~/.gem.
Some distributions will mount a tmpfs partition with low disk space to /tmp,
such as 250 MB. You can check this with:
mount | grep tmp
df -h | grep tmp
Compiling MRI requires at least 265 MB, so you should temporarily resize /tmp
to allow more usage:
rm -rf /tmp/ruby-build*
mount -o remount,size=300M,noatime /tmp
Gentoo defines a system-wide RUBYOPT environment variable that automatically
wants to load auto_gem whenever any Ruby scripts gets executed. This will fail
for Ruby versions other than the system one.
$ cat /etc/env.d/10rubygems
RUBYOPT="-rauto_gem"
The solution is to configure your shell init script to export -n RUBYOPT
(unexport) the value from your environment.
Machines that report a large amount of CPU cores but not enough RAM might experience this error when compiling.
Use MAKE_OPTS to lower the number of parallel processes:
MAKE_OPTS=-j2 ruby-build ...Apple changed the default compilation flags of clang on later macOS which breaks compilation of older rubies.
To work around this you can disable some errors:
RUBY_CFLAGS='-Wno-error=implicit-function-declaration' ruby-build ...