зеркало из https://github.com/github/ruby.git
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
GitHub
Родитель
0cae30e1d3
Коммит
9241d75a61
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
111
doc/hacking.md
|
|
@ -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.
|
||||
Загрузка…
Ссылка в новой задаче