kotovalexarian-likes-github
/
ruby--ruby
mirror of https://github.com/ruby/ruby.git
1
0
Fork 0
Code Releases Activity

Add information from doc/hacking.md and doc/make_cheatsheet.md back i… (#5963) 

Add information from doc/hacking.md and doc/make_cheatsheet.md back into contributing docs
This commit is contained in:
Jemma Issroff 2022-05-30 23:50:39 -04:00 committed by GitHub
parent 0cae30e1d3
commit 9241d75a61
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
Notes: git 2022-05-31 12:51:11 +09:00 
Merged-By: peterzhu2118 <peter@peterzhu.ca>
4 changed files with 105 additions and 118 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
doc/contributing.md
View File

@ -9,3 +9,4 @@ This guide outlines ways to get started with contributing to Ruby:
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

74
doc/contributing/building_ruby.md
View File

@ -25,17 +25,27 @@
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.
### 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:
* `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

37
doc/contributing/testing_ruby.md
View File

@ -32,6 +32,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
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+
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+
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+
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+
```
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
```

111
doc/hacking.md
View File

@ -1,111 +0,0 @@
# 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 Fish shell:
export MAKEFLAGS="--jobs "(nproc)
# On Linux with Bash/ZSH shell:
export MAKEFLAGS="--jobs $(nproc)"
```
## Configure Ruby
It's generally advisable to use a build directory.
``` shell
./autogen.sh
mkdir build
cd build
../configure --prefix $HOME/.rubies/ruby-head
make install
```
### Without Documentation
If you are frequently building Ruby, this will reduce the time it takes to `make install`.
``` shell
../configure --disable-install-doc
```
### 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 artefacts from previous releases which can cause build failures.
## Running Ruby
### Run Local Test Script
You can create a file in the Ruby source root called `test.rb`. You can build `miniruby` and execute this script:
``` shell
make run
```
If you want more of the standard library, you can use `runruby` instead of `run`.
## Running Tests
You can run the following tests at once:
``` shell
make check
```
### Run Bootstrap Tests
There are a set of tests in `bootstraptest/` which cover most basic features of the core Ruby language.
``` shell
make test
```
### Run Extensive Tests
There are extensive tests in `test/` which cover a wide range of features of the Ruby core language.
``` shell
make test-all
```
You can run specific tests by specifying their path:
``` shell
make test-all TESTS=../test/fiber/test_io.rb
```
### Run Ruby Spec Suite Tests
The [Ruby Spec Suite](https://github.com/ruby/spec/) is a test suite that aims to provide an executable description for the behaviour of the language.
``` shell
make test-spec
```
### 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 and this is especially true for ASAN which sometimes works incorrectly at higher optimisation levels.