ruby-changes:72028
From: Jemma <ko1@a...>
Date: Tue, 31 May 2022 12:51:04 +0900 (JST)
Subject: [ruby-changes:72028] 9241d75a61 (master): Add information from doc/hacking.md and doc/make_cheatsheet.md back i… (#5963)
https://git.ruby-lang.org/ruby.git/commit/?id=9241d75a61 From 9241d75a615f652dee45bc999524cc3c6ede8c5d Mon Sep 17 00:00:00 2001 From: Jemma Issroff <jemmaissroff@g...> Date: Mon, 30 May 2022 23:50:39 -0400 Subject: =?UTF-8?q?Add=20information=20from=20doc/hacking.md=20and=20doc/m?= =?UTF-8?q?ake=5Fcheatsheet.md=20back=20i=E2=80=A6=20(#5963)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add information from doc/hacking.md and doc/make_cheatsheet.md back into contributing docs --- doc/contributing.md | 1 + doc/contributing/building_ruby.md | 74 +++++++++++++++++++++++-- doc/contributing/testing_ruby.md | 37 +++++++++++-- doc/hacking.md | 111 -------------------------------------- 4 files changed, 105 insertions(+), 118 deletions(-) delete mode 100644 doc/hacking.md diff --git a/doc/contributing.md b/doc/contributing.md index a8deea7969..a6c63de9b2 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -9,3 +9,4 @@ This guide outlines ways to get started with contributing to Ruby: https://github.com/ruby/ruby/blob/trunk/doc/contributing.md#L9 to change Ruby's documentation, code, test suite, or standard libraries * [Making changes to Ruby standard libraries](contributing/making_changes_to_stdlibs.md): How to build, test, and contribute to Ruby standard libraries * [Making changes to Ruby documentation](contributing/documentation_guide.md): How to make changes to Ruby documentation +* [Benchmarking Ruby](https://github.com/ruby/ruby/tree/master/benchmark#make-benchmark): How to benchmark Ruby diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md index f20eacc0ae..52d6042ec3 100644 --- a/doc/contributing/building_ruby.md +++ b/doc/contributing/building_ruby.md @@ -25,17 +25,27 @@ https://github.com/ruby/ruby/blob/trunk/doc/contributing/building_ruby.md#L25 git clone https://github.com/ruby/ruby.git ``` -4. Generate the configuration files and build: +4. Generate the configuration files and build. It's generally advisable to use a build directory: ``` ./autogen.sh - mkdir build && cd build # its good practice to build outside of source dir + mkdir build && cd build # it's good practice to build outside of source dir mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir ../configure --prefix="${HOME}/.rubies/ruby-master" make install ``` -5. [Run tests](testing_ruby.md) to confirm your build succeeded +5. Optional: If you are frequently building Ruby, disabling documentation will reduce the time it takes to `make`: + + ``` shell + ../configure --disable-install-doc + ``` + +6. [Run tests](testing_ruby.md) to confirm your build succeeded + +### 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. ## More details @@ -44,13 +54,31 @@ about Ruby's build to help out. https://github.com/ruby/ruby/blob/trunk/doc/contributing/building_ruby.md#L54 ### Running make scripts in parallel -To run make scripts in parallel, pass flag `-j<number of processes>`. For instance, +In GNU make and BSD make implementations, to run a specific make script in parallel, pass the flag `-j<number of processes>`. For instance, to run tests on 8 processes, use: ``` make test-all -j8 ``` +We can also set `MAKEFLAGS` to run _all_ `make` commands in parallel. + +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: + +``` shell +# 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)" +``` + ### Miniruby vs Ruby Miniruby is a version of Ruby which has no external dependencies and lacks certain features. @@ -72,3 +100,41 @@ with the Ruby script you'd like to run. You can use the following make targets: https://github.com/ruby/ruby/blob/trunk/doc/contributing/building_ruby.md#L100 * `make runruby`: Runs `test.rb` using Ruby * `make lldb-ruby`: Runs `test.rb` using Ruby in lldb * `make gdb-ruby`: Runs `test.rb` using Ruby in gdb + +### Building with Address Sanitizer + +Using the address sanitizer is a great way to detect memory issues. + +``` 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" +make +``` + +On Linux it is important to specify `-O0` when debugging. This is especially true for ASAN which sometimes works incorrectly at higher optimisation levels. + +## How to measure coverage of C and Ruby code + +You need to be able to use gcc (gcov) and lcov visualizer. + +``` +./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 +``` + +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. + +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. + +You can see the coverage result of CI: https://rubyci.org/coverage diff --git a/doc/contributing/testing_ruby.md b/doc/contributing/testing_ruby.md index c54b14c710..74300d221d 100644 --- a/doc/contributing/testing_ruby.md +++ b/doc/contributing/testing_ruby.md @@ -32,6 +32,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+ https://github.com/ruby/ruby/blob/trunk/doc/contributing/testing_ruby.md#L32 make test OPTS=-v ``` + To run a file or directory with GNU make, we can use: + + ``` + make test/ruby/test_foo.rb + make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/" + ``` + 2. [test/](https://github.com/ruby/ruby/tree/master/test) This is a more comprehensive test suite that runs on Ruby. We can run it with: @@ -40,13 +47,19 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+ https://github.com/ruby/ruby/blob/trunk/doc/contributing/testing_ruby.md#L47 make test-all ``` - We can run a specific test file in this suite using the `TESTS` environment variable, for example: + We can run a specific test directory in this suite using the `TESTS` option, for example: + + ``` + make test-all TESTS=test/rubygems + ``` + + We can run a specific test file in this suite by also using the `TESTS` option, for example: ``` make test-all TESTS=test/ruby/test_array.rb ``` - We can run a specific test in this suite using the `TESTS` environment variable, specifying + We can run a specific test in this suite using the `TESTS` option, specifying first the file name, and then the test name, prefixed with `--name`. For example: ``` @@ -73,7 +86,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+ https://github.com/ruby/ruby/blob/trunk/doc/contributing/testing_ruby.md#L86 make test-spec ``` - To run a specific file, we can use `MSPECOPT` to specify the file: + To run a specific directory, we can use `MSPECOPT` to specify the directory: + + ``` + make test-spec MSPECOPT=spec/ruby/core/array + ``` + + To run a specific file, we can also use `MSPECOPT` to specify the file: ``` make test-spec MSPECOPT=spec/ruby/core/array/any_spec.rb @@ -91,6 +110,12 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+ https://github.com/ruby/ruby/blob/trunk/doc/contributing/testing_ruby.md#L110 make test-spec MSPECOPT=-Vfs ``` + To run a ruby-spec file or directory with GNU make, we can use + + ``` + make spec/ruby/core/foo/bar_spec.rb + ``` + 4. [spec/bundler](https://github.com/ruby/ruby/tree/master/spec/bundler) The bundler test suite exists in [the RubyGems repository](https://github.com/rubygems/rubygems/tree/master/bundler/spec) and is mirrored into the `spec/bundler` directory in the Ruby repository. We can run this using: @@ -98,3 +123,9 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+ https://github.com/ruby/ruby/blob/trunk/doc/contributing/testing_ruby.md#L123 ``` make test-bundler ``` + + To run a specific bundler spec file, we can use `BUNDLER_SPECS` as follows: + + ``` + $ make test-bundler BUNDLER_SPECS=commands/exec_spec.rb + ``` diff --git a/doc/hacking.md b/doc/hacking.md deleted file mode 100644 index c326e13532..0000000000 --- a/doc/hacking.md +++ /dev/null @@ -1,111 +0,0 @@ https://github.com/ruby/ruby/blob/trunk/doc/contributing/testing_ruby.md#L0 -# Ruby Hacking Guide - -This document gives some helpful instructions which should make your experience as a Ruby core developer easier. - -## Setup - -### Make - -It's common to want to compile things as quickly as possible. Ensuring `make` has 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: - -``` shell -# 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 Fis (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/