Tooling

A tour of the build-time helpers in tool/, the parser generator, and the codegen pipelines.

Build orchestration

Tool	Purpose
autoconf + autogen.sh	Regenerate configure from configure.ac
make	Drive everything else
tool/extlibs.rb	Fetch and build optional C libraries (e.g., libffi)
tool/runruby.rb	Run an in-tree Ruby with the right -I flags
tool/file2lastrev.rb	Compute revision metadata for revision.h
tool/checksum.rb	Verify gem and tarball checksums

common.mk is the platform-independent Makefile body, included from generated Makefiles on each platform.

Parser generator: Lrama

tool/lrama/ contains an entire LALR(1) parser generator written in Ruby. It consumes parse.y and emits parse.c. Key entry points:

• tool/lrama/lib/lrama.rb — gem entry.
• tool/lrama/exe/lrama — CLI driver.
• tool/lrama/lib/lrama/parser.rb — the meta-parser that reads .y files.
• tool/lrama/lib/lrama/states.rb — LALR state computation.

Building Ruby therefore needs Ruby (the base ruby) before it can build Ruby — a classic bootstrapping problem. BASERUBY in the Makefile points to the base Ruby.

Prism templates

Prism (prism/) is largely generated from a YAML spec:

• prism/config.yml — declarative description of every AST node, token, and option.
• prism/templates/ — ERB templates that render prism.c, prism.h, the Ruby AST classes, the bindings for other languages, etc.
• prism/templates/template.rb — the ERB driver.

tool/sync_default_gems.rb prism re-pulls the canonical Prism repo into this tree.

VM instruction codegen

tool/ruby_vm/ consumes insns.def and emits:

• vm_exec.c (the dispatch loop).
• vmtc.inc (the threaded-code table).
• vm_callinfo.h-related helpers.
• JIT entry stubs.

Files of interest:

• tool/ruby_vm/views/_mjit_compile_insn.erb (legacy MJIT template; mostly historical).
• tool/ruby_vm/views/vm.inc.erb, tool/ruby_vm/views/vmtc.inc.erb.
• tool/instruction.rb — the loader for insns.def.
• tool/insns2vm.rb — the entry point.

Run with make srcs (which calls tool/insns2vm.rb internally).

Built-in Ruby loader

Several core classes have method bodies in Ruby (array.rb, hash.rb, gc.rb, kernel.rb, etc.) that are compiled into the binary. The pipeline:

1. tool/mk_builtin_loader.rb reads each *.rb.
2. It produces a <name>.rbinc file containing serialized iseqs.
3. mini_builtin.c and builtin.c register those iseqs at startup.
4. Primitive.foo calls in the Ruby code resolve to C primitives declared via rb_define_builtin_primitive.

Run with make srcs after editing any of these .rb files.

Transcoding tables

enc/trans/ contains C tables for converting between encodings (Shift-JIS → UTF-8, etc.). Sources are in enc/trans/*.trans and Unicode data files; tool/transcode-tblgen.rb consumes them.

Encoding tables

tool/enc-unicode.rb, tool/enc-emoji-citrus-gen.rb, and tool/enc-emoji4unicode.rb produce regular-expression and case-folding tables from the Unicode Character Database. The output lives in enc/unicode/data/ and is regenerated when Ruby tracks a new Unicode version.

Default-gem sync

tool/sync_default_gems.rb is the workhorse for keeping lib/<gem>/, ext/<gem>/, test/<gem>/, and spec/ruby/library/<gem>/ in sync with their authoritative upstream repos:

ruby tool/sync_default_gems.rb prism
ruby tool/sync_default_gems.rb optparse
ruby tool/sync_default_gems.rb -a   # all gems

The REPOSITORIES hash at the top of the file lists the gem ↔ upstream-repo mapping.

Release / changelog tooling

Tool	Purpose
tool/format-release	Formats release notes from changelogs
tool/gen-github-release.rb	Cuts a GitHub release once a tag is pushed
tool/update-NEWS-gemlist.rb	Refreshes the gem-list section of NEWS.md
tool/update-NEWS-github-release.rb	Generates per-gem release links in NEWS.md
tool/redmine-backporter.rb	Helps with backporting bug fixes
tool/auto-style.rb	Mass-applies coding style fixes
tool/auto_review_pr.rb	Runs review-style automation on PRs

CI helpers

.github/actions/setup/ defines reusable composite actions for installing dependencies on Ubuntu, macOS, and Windows. Workflows under .github/workflows/ reuse them.

tool/leaked-globals runs nm on the built binary and verifies no internal symbols leak out (an old but persistent concern for embedders).

Linting and static analysis

• tool/auto-style.rb enforces project-wide whitespace and trivial-style rules. Runs as a job in CI.
• tool/check-source.sh (called from make exam) does broader source checks.
• .github/codeql/ configures GitHub CodeQL for security scanning.
• .github/zizmor.yml configures the Zizmor lint for GitHub Actions workflows.

ZJIT-specific tools

• tool/zjit_bisect.rb — bisect a misbehaving ZJIT compilation.
• tool/zjit_diff.rb — diff IR between two compilations.
• tool/zjit_iongraph.rb (+ zjit_iongraph.html) — render IR graphs in the browser.

Build artifacts inventory

After make, the repo contains:

• ./miniruby — bootstrap interpreter, statically linked, no extensions.
• ./ruby — the production binary, dynamically links extensions.
• ./libruby.so (or .dylib/.dll) — present with --enable-shared.
• ./<ext>.so — built extension libraries.
• revision.h — auto-generated revision metadata.
• verconf.h, config.h — generated headers from configure.