Getting started

This page walks through cloning, building, testing, and running the Ruby interpreter from this repository. The authoritative document is the upstream Building Ruby guide; this page summarises the pieces relevant to working in ruby/ruby itself.

Prerequisites

You will need:

• A base Ruby (any recent stable release works) to bootstrap the build. CRuby uses Ruby itself for many code-generation steps. tool/runruby.rb and tool/missing-baseruby.bat find or stub a base Ruby.
• A C compiler with C99 support (gcc, clang, MSVC).
• autoconf, make, bison is not needed — Lrama (a Ruby gem in tool/lrama/) replaces it.
• Rust (≥ 1.85.0, see Cargo.toml's rust-version) only if you want to build with --enable-yjit or --enable-zjit.
• For some extensions: OpenSSL, libffi, libyaml, zlib, readline, gdbm, etc. The repo ships tool/extlibs.rb to fetch and build many of these from ext/<name>/depend.

The .github/workflows/ directory shows what Ubuntu, macOS, and Windows CI assume. .github/actions/setup/ has the OS-specific dependency lists in one place.

Cloning

git clone https://github.com/ruby/ruby.git
cd ruby

The repo is a regular Git repo with submodule-like sync scripts (see tool/sync_default_gems.rb); there are no real Git submodules to initialize.

Configure and build

./autogen.sh
./configure --prefix=$HOME/ruby-dev --enable-yjit
make -j$(nproc)

Useful configure flags:

• --prefix=... — install location.
• --enable-shared — build libruby.so instead of static.
• --enable-yjit / --enable-zjit — include the Rust JITs.
• --with-gc=mmtk — use the MMTk-backed GC (see gc/mmtk/).
• --disable-install-doc — skip RDoc generation; speeds up local builds.
• --with-ext=... / --without-ext=... — pick which C extensions to build.
• optflags=-O0 debugflags="-g3" — debug-friendly build.

A typical local development invocation:

./configure --prefix=$HOME/ruby-dev \
  --enable-yjit \
  --disable-install-doc \
  optflags="-O3" debugflags="-g3"
make -j$(nproc)
make install

Running tests

The test suite has several layers, in increasing order of coverage and time:

Layer	Command	What it covers
btest	make btest (also make test-bootstrap)	Quick smoke tests in bootstraptest/ driven by minunit-like runner
test-basic	make test-basic	A handful of must-pass scripts in basictest/
test-all	make test-all	The full test/ suite (test-unit / minitest)
test-spec	make test-spec	The ruby/spec submodule under spec/ruby/
check	make check	Runs btest + test-all + test-spec
yjit-bench	external repo	Performance benchmarks, used by YJIT contributors

Run a single test file:

./miniruby -I./lib -I. test/ruby/test_array.rb
# or with the installed binary:
make test-all TESTS="test/ruby/test_array.rb"

Run the bootstraptest for a single file:

make btest BTESTS="bootstraptest/test_method.rb"

JIT-specific tests live in test/ruby/test_yjit.rb and test/ruby/test_zjit.rb. There are also exclusion lists under spec/.excludes-zjit/ and spec/.excludes-mmtk/.

Running your in-tree build

Avoid make install for quick iteration. Instead:

./miniruby -e 'puts RUBY_DESCRIPTION'    # raw, without stdlib search paths set up
./tool/runruby.rb -e 'puts RUBY_DESCRIPTION'  # with proper -I paths
make run                                   # convenience target

miniruby is a stripped-down Ruby produced very early in the build that is just powerful enough to run the build's Ruby helpers. It cannot load most C extensions because it is statically linked. For real testing, use ./ruby (built later) or make run.

Running a single Ruby file with YJIT / ZJIT

./ruby --yjit -e 'puts "hello, yjit"'
./ruby --zjit -e 'puts "hello, zjit"'
RUBYOPT="--yjit-stats" ./ruby some_script.rb

./ruby --help lists all --yjit-*/--zjit-* flags. The stats flags print performance counters at exit.

Picking a parser

Ruby ships two parsers; pick at runtime:

./ruby --parser=prism -e 'pp RubyVM::AbstractSyntaxTree.parse("1+2")'
./ruby --parser=parse.y -e 'pp RubyVM::AbstractSyntaxTree.parse("1+2")'

The default is parse.y. Prism is exercised heavily in CI and is the default for Ruby tools like Ruby LSP and RuboCop.

Where to look next

• Make a change: see how-to-contribute/development-workflow.md.
• Debug a crash: see how-to-contribute/debugging.md.
• Add a Ruby method: see how-to-contribute/patterns-and-conventions.md.
• Understand the VM: see systems/vm.md.