diff options
Diffstat (limited to 'doc/contributing/building_ruby.md')
| -rw-r--r-- | doc/contributing/building_ruby.md | 79 |
1 files changed, 57 insertions, 22 deletions
diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md index d4cedbcb69..38c78e3cca 100644 --- a/doc/contributing/building_ruby.md +++ b/doc/contributing/building_ruby.md @@ -17,7 +17,7 @@ * autoconf - 2.67 or later * gperf - 3.1 or later * Usually unneeded; only if you edit some source files using gperf - * ruby - 2.5 or later + * ruby - 3.0 or later * We can upgrade this version to system ruby version of the latest Ubuntu LTS. 2. Install optional, recommended dependencies: @@ -25,7 +25,8 @@ * libffi (to build fiddle) * gmp (if you with to accelerate Bignum operations) * libexecinfo (FreeBSD) - * rustc - 1.58.0 or later (if you wish to build [YJIT](/doc/yjit/yjit.md)) + * rustc - 1.58.0 or later, if you wish to build + [YJIT](https://docs.ruby-lang.org/en/master/RubyVM/YJIT.html). If you installed the libraries needed for extensions (openssl, readline, libyaml, zlib) into other than the OS default place, typically using Homebrew on macOS, add `--with-EXTLIB-dir` options to `CONFIGURE_ARGS` environment variable. @@ -41,29 +42,32 @@ 1. Download ruby source code: + Select one of the below. + 1. Build from the tarball: - Download the latest tarball from [ruby-lang.org](https://www.ruby-lang.org/en/downloads/) and - extract it. Example for Ruby 3.0.2: + Download the latest tarball from [ruby-lang.org](https://www.ruby-lang.org/en/downloads/) and + extract it. Example for Ruby 3.0.2: - ``` shell - tar -xzf ruby-3.0.2.tar.gz - cd ruby-3.0.2 - ``` + ``` shell + tar -xzf ruby-3.0.2.tar.gz + cd ruby-3.0.2 + ``` 2. Build from the git repository: - Checkout the CRuby source code: + Checkout the CRuby source code: - ``` shell - git clone https://github.com/ruby/ruby.git - ``` + ``` shell + git clone https://github.com/ruby/ruby.git + cd ruby + ``` - Generate the configure file: + Generate the configure file: - ``` shell - ./autogen.sh - ``` + ``` shell + ./autogen.sh + ``` 2. Create a `build` directory separate from the source directory: @@ -85,20 +89,33 @@ ../configure --prefix="${HOME}/.rubies/ruby-master" ``` - - If you are frequently building Ruby, add the `--disable-install-doc` flag to not build documentation which will speed up the build process. + - Also `-C` (or `--config-cache`) would reduce time to configure from the next time. 5. Build Ruby: ``` shell - make install + make ``` 6. [Run tests](testing_ruby.md) to confirm your build succeeded. +7. Install Ruby: + + ``` shell + make install + ``` + + - 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`. + ### Unexplainable Build Errors If 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. +## Building on Windows + +The documentation for building on Windows can be found [here](../windows.md). + ## More details If you're interested in continuing development on Ruby, here are more details @@ -153,19 +170,37 @@ with the Ruby script you'd like to run. You can use the following make targets: * `make lldb-ruby`: Runs `test.rb` using Ruby in lldb * `make gdb-ruby`: Runs `test.rb` using Ruby in gdb +### Compiling for Debugging + +You should configure Ruby without optimization and other flags that may interfere with debugging: + +``` shell +./configure --enable-debug-env optflags="-O0 -fno-omit-frame-pointer" +``` + ### Building with Address Sanitizer -Using the address sanitizer is a great way to detect memory issues. +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. ``` shell ./autogen.sh mkdir build && cd build -export ASAN_OPTIONS="halt_on_error=0:use_sigaltstack=0:detect_leaks=0" -../configure cppflags="-fsanitize=address -fno-omit-frame-pointer" optflags=-O0 LDFLAGS="-fsanitize=address -fno-omit-frame-pointer" +../configure CC=clang-18 cflags="-fsanitize=address -fno-omit-frame-pointer -DUSE_MN_THREADS=0" # and any other options you might like make ``` +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. + +``` shell +RUBY_TEST_TIMEOUT_SCALE=5 SYNTAX_SUGGEST_TIMEOUT=600 make check +``` + +Please note, however, the following caveats! -On Linux it is important to specify `-O0` when debugging. This is especially true for ASAN which sometimes works incorrectly at higher optimisation levels. +* ASAN 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 [9d0a5148ae062a0481a4a18fbeb9cfd01dc10428](https://bugs.ruby-lang.org/projects/ruby-master/repository/git/revisions/9d0a5148ae062a0481a4a18fbeb9cfd01dc10428)) +* Due to [this bug](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). +* ASAN will only work when using Clang version 18 or later - it requires [this bugfix](https://github.com/llvm/llvm-project/pull/75290) related to multithreaded `fork`. +* ASAN 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 [https://bugs.ruby-lang.org](https://bugs.ruby-lang.org) if you run into problems with such configurations (or, to report that they actually work properly!) +* 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 [here](https://github.com/llvm/llvm-project/commit/2a03854e4ce9bb1bcd79a211063bc63c4657f92c)). Please open an issue on [https://bugs.ruby-lang.org](https://bugs.ruby-lang.org) if this is a problem for you. ## How to measure coverage of C and Ruby code |