-
Notifications
You must be signed in to change notification settings - Fork 784
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.
We recommend using Homebrew to manage installing packages on macOS.
# install Xcode Command Line Tools
xcode-select --install
# install dependencies with Homebrew
brew install openssl@3 readline libyaml gmp autoconfIt is no longer necessary to set RUBY_CONFIGURE_OPTS to explicitly link to Homebrew OpenSSL, since ruby-build will now automatically detect and link to a compatible OpenSSL version.
Ruby 3.0 or older versions need OpenSSL 1.1 instead of OpenSSL 3. (Note that these Ruby versions are now unsupported upstream and might experience other build failures depending on OS and CPU architecture combinations.)
# only for Ruby 3.0, 2.7, or older
brew install rbenv/tap/openssl@1.1Ruby 3.2 and above requires the Rust compiler if you want to have YJIT enabled:
brew install rust
ruby-build 3.2.2 /opt/rubies/ruby-3.2.2 -- --enable-yjitapt-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 autoconf gcc patch bzip2 openssl-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-devel tarRHEL 9:
dnf install -y autoconf gcc patch bzip2 openssl-devel libffi-devel readline zlib-devel gdbm ncurses-devel tar perl-FindBinRocky Linux 9 The following is needed along with the RHEL 9 install
dnf --enablerepo=crb install libyaml-develIf you want to use YJIT, you need to use after RHEL8 and install rust.
yum install -y rustdnf install -y autoconf gcc rust patch make bzip2 openssl-devel libyaml-devel libffi-devel readline-devel zlib-devel gdbm-devel ncurses-develpkg 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 may need to install openssl development headers:
- Ubuntu:
apt-get install libssl-dev - Fedora:
yum install openssl-devel - Void Linux:
xbps-install -Su openssl-devel - Homebrew:
brew install openssl@3
Note
Keep in mind that ruby-build tries to detect an OpenSSL version already installed on the system and, failing that, it automatically downloads and installs a version of OpenSSL exclusively for use with Ruby. Therefore, the fact that a system OpenSSL version is missing should not be a blocker for installing Ruby with ruby-build. The Missing the OpenSSL lib? error message, however, might be an indicator that something else went wrong when trying to link to an existing OpenSSL version.
If installing these extra packages did not help, something else might have caused Ruby's openssl extension to fail while compiling, but often there will not be any further information in ruby-build's log about this.
To look into the build log for the openssl extension specifically, take a note of the build directory named in Inspect or clean up the working tree at <DIR> of ruby-build's output, then find the ruby-*/ext/openssl/mkmf.log file there.
If you have multiple OpenSSL versions installed on the system, it might help to pick one explicitly:
ruby-build <version> <destination> -- --with-openssl-dir="$(brew --prefix openssl@3)"Suggestions that cover most of the cases:
- check brew and Rosetta 2,
brew config-- it should haveRosetta 2: false, if not, then do full reinstallation of brew and ensure that you are not usingarchcommand anywhere - check if openssl installed by running
brew install openssl - use
export RUBY_CFLAGSenv variable to avoid blocking warnings during compilation, e.g.export RUBY_CFLAGS="-Wno-error=implicit-function-declaration"-- read error log output and tune the flag as needed - for rubies older than 3.1, possibly another compiler required, use
export CC=gccenv variable, which also requiresbrew install gcc
Some 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.
There 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 ...