ÿØÿà JFIF ÿÛ „ ( % !1!%)+//. 383,7(-.+
-% %-////---/-.+/--+------/------/--0+--/-/-----.-----ÿÀ ¥2" ÿÄ ÿÄ J ! 1AQ"aq2‘#BR‚¡ÁÑ3br’¢±Âð$CSƒ²á4c“%DsÓñÿÄ ÿÄ * !1AQa‘"2q3±ð#b¡ÿÚ ? ¼QxJQa Íuò¸Zö Úü8,Ð Úú
"SS n<rçù–´âE—^ªBÖ9À\†¸ÔÁTÃÛ5
ëd´³Í#Ý;Þ38œî ¶ H£M:wÎ3…³…âpÔF&‚FK¸9„â4àGEõªfÿ ‘ñ(ß wpŽF|È¥ù®häðÍѶ¹‘[ÒinÙW¶ùñ Y˜Q{›K"išÒ[Ú8žë\F¹@-? v"ÔU”,ìöžkÿ {I‡£šÍ?e
ríV
?>
.........................................
.............................................................................
ÿØÿà JFIF ÿÛ „
(
% !1!%)+//. 383,7(-.+
-% %-////---/-.+/--+------/------/--0+--/-/-----.-----ÿÀ ¥2" ÿÄ
ÿÄ J ! 1AQ"aq2‘#BR‚¡ÁÑ3br’¢±Âð$CSƒ²á4c“%DsÓñÿÄ
ÿÄ * !1AQa‘"2q3±ð#b¡ÿÚ
? ¼QxJQa Íuò¸Zö
Úü8,Ð Úú
"SS n<rçù–´âE—^ªBÖ9À\†¸ÔÁTÃÛ5
ëd´³Í#Ý;Þ38œî ¶ H£M:wÎ3…³…âpÔF&‚FK¸9„â4àGEõªfÿ ‘ñ(ß wpŽF|È¥ù®häðÍѶ¹‘[ÒinÙW¶ùñ Y˜Q{›K"išÒ[Ú8žë\F¹@-? v"ÔU”,ìöžkÿ {I‡£šÍ?e
ríV
?>
.........................................
.............................................................................
????????????????????????????????????
????????????????????????????????????
ÿØÿà JFIF ÿÛ „ ( % !1!%)+//. 383,7(-.+
-% %-////---/-.+/--+------/------/--0+--/-/-----.-----ÿÀ ¥2" ÿÄ ÿÄ J ! 1AQ"aq2‘#BR‚¡ÁÑ3br’¢±Âð$CSƒ²á4c“%DsÓñÿÄ ÿÄ * !1AQa‘"2q3±ð#b¡ÿÚ ? ¼QxJQa Íuò¸Zö Úü8,Ð Úú
"SS n<rçù–´âE—^ªBÖ9À\†¸ÔÁTÃÛ5
ëd´³Í#Ý;Þ38œî ¶ H£M:wÎ3…³…âpÔF&‚FK¸9„â4àGEõªfÿ ‘ñ(ß wpŽF|È¥ù®häðÍѶ¹‘[ÒinÙW¶ùñ Y˜Q{›K"išÒ[Ú8žë\F¹@-? v"ÔU”,ìöžkÿ {I‡£šÍ?e
ríV
?>
.........................................
.............................................................................
ÿØÿà JFIF ÿÛ „
(
% !1!%)+//. 383,7(-.+
-% %-////---/-.+/--+------/------/--0+--/-/-----.-----ÿÀ ¥2" ÿÄ
ÿÄ J ! 1AQ"aq2‘#BR‚¡ÁÑ3br’¢±Âð$CSƒ²á4c“%DsÓñÿÄ
ÿÄ * !1AQa‘"2q3±ð#b¡ÿÚ
? ¼QxJQa Íuò¸Zö
Úü8,Ð Úú
"SS n<rçù–´âE—^ªBÖ9À\†¸ÔÁTÃÛ5
ëd´³Í#Ý;Þ38œî ¶ H£M:wÎ3…³…âpÔF&‚FK¸9„â4àGEõªfÿ ‘ñ(ß wpŽF|È¥ù®häðÍѶ¹‘[ÒinÙW¶ùñ Y˜Q{›K"išÒ[Ú8žë\F¹@-? v"ÔU”,ìöžkÿ {I‡£šÍ?e
ríV
?>
.........................................
.............................................................................
????????????????????????????????????
????????????????????????????????????
U:RDoc::TopLevel[ i I""contributing/building_ruby.md:ETcRDoc::Parser::Markdowno:RDoc::Markup::Document: @parts[0S:RDoc::Markup::Heading:
leveli: textI"Building Ruby;TS; ;
i; I"Dependencies;To:RDoc::Markup::List:
@type: NUMBER: @items[o:RDoc::Markup::ListItem: @label0;[ o: RDoc::Markup::Paragraph;[I"NInstall the prerequisite dependencies for building the CRuby interpreter:;Fo; ;
: BULLET;[o;;0;[o;;[I"C compiler;Fo;;[I"&For RubyGems, you will also need:;Fo; ;
;;[o;;0;[o;;[I"]{OpenSSL}[https://www.openssl.org] 1.1.x or 3.0.x / {LibreSSL}[https://www.libressl.org];To;;0;[o;;[I"?{libyaml}[https://github.com/yaml/libyaml/] 0.1.7 or later;To;;0;[o;;[I"!{zlib}[https://www.zlib.net];To;;[I"FIf you want to build from the git repository, you will also need:;Fo; ;
;;[o;;0;[o;;[I"G{autoconf}[https://www.gnu.org/software/autoconf/] - 2.67 or later;To;;0;[o;;[I"@{gperf}[https://www.gnu.org/software/gperf/] - 3.1 or later;To; ;
;;[o;;0;[o;;[I"EUsually unneeded; only if you edit some source files using gperf;Fo;;0;[o;;[I"ruby - 3.0 or later;Fo; ;
;;[o;;0;[o;;[I"RWe can upgrade this version to system ruby version of the latest
Ubuntu LTS.;Fo;;0;[ o;;[I"0Install optional, recommended dependencies:;Fo; ;
;;[o;;0;[o;;[I"?{libffi}[https://sourceware.org/libffi/] (to build fiddle);To;;0;[o;;[I"L{gmp}[https://gmplib.org] (if you wish to accelerate Bignum operations);To;;0;[o;;[I"o{rustc}[https://www.rust-lang.org] - 1.58.0 or later, if you wish to build
{YJIT}[rdoc-ref:RubyVM::YJIT].;To;;[I"If you want to link the libraries (e.g., gmp) installed into other than
the OS default place, typically using Homebrew on macOS, pass the
--with-opt-dir (or --with-gmp-dir for gmp) option to configure.;Fo:RDoc::Markup::Verbatim;[I"Mconfigure --with-opt-dir=$(brew --prefix gmp):$(brew --prefix jemalloc)
;F: @format:sho;;[I"As for the libraries needed for particular extensions only and not for
Ruby (openssl, readline, libyaml, zlib), you can add --with-EXTLIB-dir
options to the command line or to CONFIGURE_ARGS environment variable.
The command line options will be embedded in rbconfig.rb, while the
latter environment variable is not embedded and is only used when
building the extension libraries.;Fo;;[I"export CONFIGURE_ARGS=""
for ext in openssl readline libyaml zlib; do
CONFIGURE_ARGS="${CONFIGURE_ARGS} --with-$ext-dir=$(brew --prefix $ext)"
done
;F;;S; ;
i; I"Quick start guide;To; ;
;;[
o;;0;[o;;[I" Download ruby source code:;Fo;;[I" Select one of the below.;Fo; ;
;;[o;;0;[o;;[I" Build from the tarball:;Fo;;[I"Download the latest tarball from {Download Ruby}[https://www.ruby-lang.org/en/downloads/] page and extract
it. Example for Ruby 3.0.2:;Fo;;[I".tar -xzf ruby-3.0.2.tar.gz
cd ruby-3.0.2
;F;;o;;0;[
o;;[I"#Build from the git repository:;Fo;;[I"$Checkout the CRuby source code:;Fo;;[I"8git clone https://github.com/ruby/ruby.git
cd ruby
;F;;o;;[I"URun the GNU Autoconf script (which generates the configure script):;Fo;;[I"./autogen.sh
;F;;o;;0;[o;;[I"KCreate a build directory inside the repository directory:;Fo;;[I" mkdir build && cd build
;F;;o;;[I"gWhile it's not necessary to build in a dedicated directory like this, it's good
practice to do so.;Fo;;0;[o;;[I"qWe'll eventually install our new Ruby in ~/.rubies/ruby-master, so we'll create that directory:;Fo;;[I"mkdir ~/.rubies
;F;;o;;0;[o;;[I"WRun the configure script (which generates the Makefile):;Fo;;[I"9../configure --prefix="${HOME}/.rubies/ruby-master"
;F;;o; ;
;;[o;;0;[o;;[I"nAlso -C (or --config-cache) would reduce time to configure from the
next time.;Fo;;0;[o;;[I"Build Ruby:;Fo;;[I"
make
;F;;o;;0;[o;;[I"B{Run tests}[testing_ruby.md] to confirm your build succeeded.;To;;0;[o;;[I"MInstall our newly-compiled Ruby into ~/.rubies/ruby-master:;Fo;;[I"make install
;F;;o; ;
;;[o;;0;[o;;[I"If you need to run make install with sudo and want to avoid document
generation with different permissions, you can use make SUDO=sudo
install.;Fo;;0;[o;;[I"5You can then try your new Ruby out, for example:;Fo;;[I">~/.rubies/ruby-master/bin/ruby -e "puts 'Hello, World!'"
;F;;o;;[I"/By the end, your repo will look like this:;To;;[I"ruby
├── autogen.sh # Pre-existing Autoconf script, used in step 1
├── configure # Generated in step 1, which generates the `Makefile` in step 4
├── build # Created in step 2 and populated in step 4
│ ├── GNUmakefile # Generated by `../configure`
│ ├── Makefile # Generated by `../configure`
│ ├── object.o # Compiled object file, built my `make`
│ └── ... other compiled `.o` object files
│
│ # Other interesting files:
├── include
│ └── ruby.h # The main public header
├── internal
│ ├── object.h
│ └── ... other header files used by the `.c` files in the repo root.
├── lib
│ └── # Default gems, like `bundler`, `erb`, `set`, `yaml`, etc.
├── spec
│ └── # A mirror of the Ruby specification from github.com/ruby/spec
├── test
│ ├── ruby
│ └── ...
├── object.c
└── ... other `.c` files
;T;; S; ;
i; I" Unexplainable Build Errors;To;;[I"WIf you are having unexplainable build errors, after saving all your work, try
running git clean -xfd in the source root to remove all git ignored local
files. If you are working from a source directory that's been updated several
times, you may have temporary build artifacts from previous releases which can
cause build failures.;TS; ;
i; I"Building on Windows;To;;[I"cThe documentation for building on Windows can be found in {the separated file}[../windows.md].;TS; ;
i; I"More details;To;;[I"rIf you're interested in continuing development on Ruby, here are more details
about Ruby's build to help out.;TS; ;
i; I"%Running make scripts in parallel;To;;[I"In GNU make{*1}[rdoc-label:foottext-1:footmark-1] and BSD make implementations, to run a specific make script in
parallel, pass the flag -j. For instance, to run tests
on 8 processes, use:;To;;[I"make test-all -j8
;T;;o;;[I"`We can also set MAKEFLAGS to run _all_ make commands in parallel.;To;;[I"Having the right --jobs flag will ensure all processors are utilized when
building software projects. To do this effectively, you can set MAKEFLAGS in
your shell configuration/profile:;To;;[I" # On macOS with Fish shell:
export MAKEFLAGS="--jobs "(sysctl -n hw.ncpu)
# On macOS with Bash/ZSH shell:
export MAKEFLAGS="--jobs $(sysctl -n hw.ncpu)"
# On Linux with Fish shell:
export MAKEFLAGS="--jobs "(nproc)
# On Linux with Bash/ZSH shell:
export MAKEFLAGS="--jobs $(nproc)"
;T;;S; ;
i; I"Miniruby vs Ruby;To;;[I"Miniruby is a version of Ruby which has no external dependencies and lacks
certain features. It can be useful in Ruby development because it allows for
faster build times. Miniruby is built before Ruby. A functional Miniruby is
required to build Ruby. To build Miniruby:;To;;[I"make miniruby
;T;;S; ;
i; I"Debugging;To;;[I"You can use either lldb or gdb for debugging. Before debugging, you need to
create a test.rb with the Ruby script you'd like to run. You can use the
following make targets:;To; ;
;;[ o;;0;[o;;[I"Dmake run: Runs test.rb using Miniruby;To;;0;[o;;[I"Mmake lldb: Runs test.rb using Miniruby in lldb;To;;0;[o;;[I"Kmake gdb: Runs test.rb using Miniruby in gdb;To;;0;[o;;[I"Dmake runruby: Runs test.rb using Ruby;To;;0;[o;;[I"Nmake lldb-ruby: Runs test.rb using Ruby in lldb;To;;0;[o;;[I"Lmake gdb-ruby: Runs test.rb using Ruby in gdb;TS; ;
i; I" Compiling for Debugging;To;;[I"fYou should configure Ruby without optimization and other flags that may
interfere with debugging:;To;;[I"K./configure --enable-debug-env optflags="-O0 -fno-omit-frame-pointer"
;T;;S; ;
i; I"$Building with Address Sanitizer;To;;[I"Using the address sanitizer (ASAN) is a great way to detect memory issues. It
can detect memory safety issues in Ruby itself, and also in any C extensions
compiled with and loaded into a Ruby compiled with ASAN.;To;;[I"./autogen.sh
mkdir build && cd build
../configure CC=clang-18 cflags="-fsanitize=address -fno-omit-frame-pointer -DUSE_MN_THREADS=0" # and any other options you might like
make
;T;;o;;[I"The compiled Ruby will now automatically crash with a report and a backtrace
if ASAN detects a memory safety issue. To run Ruby's test suite under ASAN,
issue the following command. Note that this will take quite a long time (over
two hours on my laptop); the RUBY_TEST_TIMEOUT_SCALE and
SYNTAX_SUGEST_TIMEOUT variables are required to make sure tests don't
spuriously fail with timeouts when in fact they're just slow.;To;;[I"ERUBY_TEST_TIMEOUT_SCALE=5 SYNTAX_SUGGEST_TIMEOUT=600 make check
;T;;o;;[I"1Please note, however, the following caveats!;To; ;
;;[
o;;0;[o;;[I"LASAN will not work properly on any currently released version of Ruby; the
necessary support is currently only present on Ruby's master branch (and the
whole test suite passes only as of commit {Revision 9d0a5148}[https://bugs.ruby-lang.org/projects/ruby-master/repository/git/revisions/9d0a5148ae062a0481a4a18fbeb9cfd01dc10428]).;To;;0;[o;;[I"!Due to {Bug #20243}[https://bugs.ruby-lang.org/issues/20243], Clang generates code for threadlocal variables which
doesn't work with M:N threading. Thus, it's necessary to disable M:N
threading support at build time for now (with the -DUSE_MN_THREADS=0
configure argument).;To;;0;[o;;[I"ASAN will only work when using Clang version 18 or later - it requires
{llvm/llvm-project#75290}[https://github.com/llvm/llvm-project/pull/75290] related to multithreaded fork.;To;;0;[o;;[I"1ASAN has only been tested so far with Clang on Linux. It may or may not work
with other compilers or on other platforms - please file an issue on
{Ruby Issue Tracking System}[https://bugs.ruby-lang.org] if you run into problems with such configurations
(or, to report that they actually work properly!);To;;0;[o;;[I"In particular, although I have not yet tried it, I have reason to believe
ASAN will _not_ work properly on macOS yet - the fix for the multithreaded
fork issue was actually reverted for macOS (see {llvm/llvm-project#75659}[https://github.com/llvm/llvm-project/pull/75659#issuecomment-1861584777]).
Please open an issue on {Ruby Issue Tracking System}[https://bugs.ruby-lang.org] if this is a problem for
you.;TS; ;
i; I"/How to measure coverage of C and Ruby code;To;;[I"?You need to be able to use gcc (gcov) and lcov visualizer.;To;;[I"./autogen.sh
./configure --enable-gcov
make
make update-coverage
rm -f test-coverage.dat
make test-all COVERAGE=true
make lcov
open lcov-out/index.html
;T;;o;;[I"If you need only C code coverage, you can remove COVERAGE=true from the
above process. You can also use gcov command directly to get per-file
coverage.;To;;[I"If you need only Ruby code coverage, you can remove --enable-gcov. Note
that test-coverage.dat accumulates all runs of make test-all. Make sure
that you remove the file if you want to measure one test run.;To;;[I"GYou can see the coverage result of CI: https://rubyci.org/coverage;TS:RDoc::Markup::Rule: weightio;;[I"{^1}[rdoc-label:footmark-1:foottext-1] **CAUTION**: GNU make 3 is missing some features for parallel execution, we
recommend to upgrade to GNU make 4 or later.;T:
@file@:0@omit_headings_from_table_of_contents_below0