configure

configure.ac is the autoconf script that, after autoconf, becomes configure. It runs platform probes and emits Makefile, config.h, and other inputs. The file is ~164,000 bytes and probes a large number of platform features.

Running

./autogen.sh                           # regenerate ./configure from configure.ac
./configure --prefix=/opt/ruby \
            --enable-yjit \
            --enable-zjit \
            --disable-install-doc

./configure --help lists every option. The most-used flags:

Common configure flags

Flag	Purpose
--prefix=PATH	Install location. Default /usr/local.
--exec-prefix=PATH	Architecture-specific files location.
--bindir, --libdir, --includedir, ...	Override individual install paths.
--with-arch=...	Cross-compile target arch (with --host=...).
--enable-shared / --disable-shared	Build (or not) libruby.so. Default depends on platform.
--enable-static	Also build libruby-static.a.
--enable-debug-env	Read more RUBY_*_DEBUG env vars. Useful in dev.
--enable-yjit / --disable-yjit	Include / exclude YJIT.
--enable-zjit	Include ZJIT.
--enable-yjit-dev	Build YJIT in dev mode (capstone disasm support).
--with-gc=mmtk	Use the MMTk-based GC instead of the default.
--with-baseruby=PATH	Override base Ruby (the bootstrap Ruby).
--with-ext=A,B,C	Build only the listed extensions.
--without-ext=A,B,C	Skip the listed extensions.
--with-out-ext=A,B,C	Build but do not install the listed extensions.
--enable-multiarch	Multi-arch install layout (arm64-darwin, x86_64-linux).
--with-openssl-dir=PATH	Where to find OpenSSL.
--with-libyaml-dir=PATH	Where to find libyaml (for psych).
--with-readline-dir=PATH	Where to find readline.
--with-readline=editline	Use BSD editline instead of readline.
--enable-bundled-libffi	Build the bundled libffi rather than using system.
--with-soname=NAME	Set the SONAME of libruby.so.
--disable-install-rdoc	Skip RDoc generation. Massively speeds up make install.
--disable-install-doc	Skip both RDoc and capi docs.
--enable-jit-support	Enable JITs (default; explicit flag for old builds).
--with-mantype=...	Manpage format (man, doc).
optflags=...	Override compiler optimization flags.
debugflags=...	Override compiler debug flags.
warnflags=...	Override compiler warning flags.
CC=clang	Compiler choice.
LDFLAGS=...	Extra linker flags.
CFLAGS=...	Extra C-compiler flags.
RUSTFLAGS=...	Extra rustc flags for YJIT/ZJIT.

What configure probes

Running configure writes hundreds of HAVE_*/RUBY_* macros into config.h and verconf.h. Probes include:

• Compiler features: __attribute__((aligned)), computed gotos (for the threaded VM dispatch), inline asm syntax, TLS support.
• Headers: <stdint.h>, <sys/syscall.h>, <linux/random.h>, <execinfo.h>, <ucontext.h>, ...
• Functions: dlopen, getrandom, pthread_setname_np, clock_gettime, fcntl, accept4, ...
• Types: pid_t, pthread_attr_t, socklen_t, ...
• Sizes: sizeof(long), sizeof(void *), sizeof(double).
• ABI: alignment, calling convention quirks, byte order.
• Library availability: OpenSSL ≥ 1.0.2 / 3.x, libyaml, libffi, gmp (optional), readline, editline.
• Platform: Linux/BSD/macOS/Solaris/AIX/Windows differences.

config.h is included by nearly every .c file via internal.h. Conditional compilation (#ifdef HAVE_GETRANDOM) flows from these probes.

Cross-compiling

./configure --host=aarch64-linux-gnu \
            --target=aarch64-linux-gnu \
            CC=aarch64-linux-gnu-gcc \
            --with-baseruby=/usr/bin/ruby

Cross-compilation needs a BASERUBY that runs on the build machine — used to generate parser/instruction tables — plus a cross C toolchain. The result is a ruby that runs on the target.

The WASM port (wasm/) cross-compiles to wasm32-wasi with a special --with-static-linked-ext build profile.

Override knobs

Several environment variables are honoured at configure time:

Variable	Effect
CC	Override compiler
CXX	Override C++ compiler
CFLAGS	Extra C-compiler flags
CXXFLAGS	Extra C++-compiler flags
LDFLAGS	Extra linker flags
LIBS	Extra libraries to link
CPPFLAGS	Preprocessor flags
optflags	Optimisation flags (overrides default -O3)
debugflags	Debug flags (default -ggdb3)
warnflags	Warning flags
cflags	Extra C-only flags (preserved across reconfigures)
XCFLAGS	Extra flags for ext/ builds
RUBY_DEVEL	Development build mode
BASERUBY	Path to the bootstrap Ruby

tool/m4

configure.ac includes custom m4 macros from tool/m4/:

• ruby_universal_arch.m4 — macOS universal binary support
• ruby_check_setjmp.m4 — picks the correct setjmp/longjmp variant for the platform
• ruby_thread_local.m4 — TLS detection
• ruby_default_int_size.m4 — Pointer/long sizes

These are reused across versions and rarely need editing.

Output files

After a successful ./configure:

• Makefile — the top-level build script.
• config.status — caches the chosen options for subsequent re-runs.
• config.log — full transcript of probes and their outcomes (very useful for debugging configure failures).
• config.h — #define HAVE_* for everything probed.
• verconf.h — version + arch info baked into the binary.
• rbconfig.rb — installed alongside the binary; lets gems query "how was this Ruby built?".

rbconfig.rb is consumed by mkmf when building C extensions: RbConfig::CONFIG['CC'], ['CFLAGS'], etc.

Reconfiguring

./config.status --recheck re-runs configure with the same options. Useful after editing configure.ac (re-run ./autogen.sh first to regenerate configure).

make distclean wipes everything; you need to re-run ./configure from scratch.

See makefile.md for what make does after ./configure finishes.