Skip to content

Commit

Permalink
Improve "Building Ruby" docs (ruby#12320)
Browse files Browse the repository at this point in the history 
* Clarify “Building Ruby” docs

* Fix test examples to work from `build` dir

* Clarify “Testing Ruby” examples with real examples

All the commands should run correctly by default, without the user needing to modify them. This builds confidence that the relative paths are working correct from within the `build` directory.

Also, let’s use a consistent example throughout, for greater clarity.

* Improve examples to use `-v` flag in-context

This shows the correct way to combine `-v` with another parameter, e.g. a specific file to test.

* Other readability improvements

* Clarify `make` implementation support
  • Loading branch information
@amomchilov
amomchilov authored Dec 13, 2024
1 parent f0f9e2f commit 8cc47c9
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 42 deletions.
47 changes: 41 additions & 6 deletions doc/contributing/building_ruby.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -85,28 +85,28 @@
cd ruby
```

Generate the configure file:
Run the GNU Autoconf script (which generates the `configure` script):

```sh
./autogen.sh
```

2. Create a `build` directory separate from the source directory:
2. Create a `build` directory inside the repository directory:

```sh
mkdir build && cd build
```

While it's not necessary to build in a separate directory, it's good
While it's not necessary to build in a dedicated directory like this, it's good
practice to do so.

3. We'll install Ruby in `~/.rubies/ruby-master`, so create the directory:
3. We'll eventually install our new Ruby in `~/.rubies/ruby-master`, so we'll create that directory:

```sh
mkdir ~/.rubies
```

4. Run configure:
4. Run the `configure` script (which generates the `Makefile`):

```sh
../configure --prefix="${HOME}/.rubies/ruby-master"
Expand All @@ -123,7 +123,7 @@

6. [Run tests](testing_ruby.md) to confirm your build succeeded.

7. Install Ruby:
7. Install our newly-compiled Ruby into `~/.rubies/ruby-master`:

```sh
make install
Expand All @@ -133,6 +133,41 @@
generation with different permissions, you can use `make SUDO=sudo
install`.

8. You can then try your new Ruby out, for example:

```sh
~/.rubies/ruby-master/bin/ruby -e "puts 'Hello, World!'"
```

By the end, your repo will look like this:

```text
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
```

[Download Ruby]: https://www.ruby-lang.org/en/downloads/

### Unexplainable Build Errors
Expand Down
71 changes: 35 additions & 36 deletions doc/contributing/testing_ruby.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Testing Ruby

All the commands below assume that you're running them from the `build/` directory made during [Building Ruby](building_ruby.md).

Most commands below should work with [GNU make](https://www.gnu.org/software/make/) (the default on Linux and macOS), [BSD make](https://man.freebsd.org/cgi/man.cgi?make(1)) and [NMAKE](https://learn.microsoft.com/en-us/cpp/build/reference/nmake-reference), except where indicated otherwise.

## Test suites

There are several test suites in the Ruby codebase:
Expand All @@ -8,23 +12,23 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+

1. [bootstraptest/](https://github.com/ruby/ruby/tree/master/bootstraptest)

This is a small test suite that runs on Miniruby (see [building Ruby](building_ruby.md#label-Miniruby+vs+Ruby)). We can run it with:
This is a small test suite that runs on [Miniruby](building_ruby.md#label-Miniruby+vs+Ruby). We can run it with:

```sh
make btest
```

To run it with logs, we can use:
To run individual bootstrap tests, we can either specify a list of filenames or use the `--sets` flag in the variable `BTESTS`:

```sh
make btest OPTS=-v
make btest BTESTS="../bootstraptest/test_string.rb ../bootstraptest/test_class.rb"
make btest BTESTS="--sets=string,class"
```

To run individual bootstrap tests, we can either specify a list of filenames or use the `--sets` flag in the variable `BTESTS`:
To run these tests with verbose logging, we can add `-v` to the `OPTS`:

```sh
make btest BTESTS="../bootstraptest/test_fork.rb ../bootstraptest/test_gc.rb"
make btest BTESTS="--sets=fork,gc"
make btest OPTS="--sets=string,class -v"
```

If we want to run the bootstrap test suite on Ruby (not Miniruby), we can use:
Expand All @@ -33,47 +37,47 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
make test
```

To run it with logs, we can use:
To run these tests with verbose logging, we can add `-v` to the `OPTS`:

```sh
make test OPTS=-v
```

To run a file or directory with GNU make, we can use:
(GNU make only) To run a specific file, we can use:

```sh
make test/ruby/test_foo.rb
make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/"
make ../test/ruby/test_string.rb
```

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:
You can use the `-n` test option to run a specific test with a regex:

```sh
make test-all
make ../test/ruby/test_string.rb TESTOPTS="-n /test_.*_to_s/"
```

We can run a specific test directory in this suite using the `TESTS` option, for example:
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:

```sh
make test-all TESTS=test/rubygems
make test-all
```

We can run a specific test file in this suite by also using the `TESTS` option, for example:
We can run a specific test file or directory in this suite using the `TESTS` option, for example:

```sh
make test-all TESTS=test/ruby/test_array.rb
make test-all TESTS="../test/ruby/"
make test-all TESTS="../test/ruby/test_string.rb"
```

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:

```sh
make test-all TESTS="../test/ruby/test_alias.rb --name=TestAlias#test_alias_with_zsuper_method"
make test-all TESTS="../test/ruby/test_string.rb --name=TestString#test_to_s"
```

To run these specs with logs, we can use:
To run these tests with verbose logging, we can add `-v` to `TESTS`:

```sh
make test-all TESTS=-v
Expand All @@ -85,53 +89,48 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
make test-all TESTS=--help
```

If we would like to run the `test/`, `bootstraptest/` and `spec/` test suites (the `spec/` is explained in a later section), we can run
We can run all the tests in `test/`, `bootstraptest/` and `spec/` (the `spec/` is explained in a later section) all together with:

```sh
make check
```

3. [spec/ruby](https://github.com/ruby/ruby/tree/master/spec/ruby)

This is a test suite that exists in [the Ruby spec repository](https://github.com/ruby/spec) and is mirrored into the `spec/ruby` directory in the Ruby repository. It tests the behavior of the Ruby programming language. We can run this using:
This is a test suite defined in [the Ruby spec repository](https://github.com/ruby/spec), and is periodically mirrored into the `spec/ruby` directory of this repository. It tests the behavior of the Ruby programming language. We can run this using:

```sh
make test-spec
```

To run a specific directory, we can use `SPECOPTS` to specify the directory:

```sh
make test-spec SPECOPTS=spec/ruby/core/array
```

To run a specific file, we can also use `SPECOPTS` to specify the file:
We can run a specific test file or directory in this suite using the `SPECOPTS` option, for example:

```sh
make test-spec SPECOPTS=spec/ruby/core/array/any_spec.rb
make test-spec SPECOPTS="../spec/ruby/core/string/"
make test-spec SPECOPTS="../spec/ruby/core/string/to_s_spec.rb"
```

To run a specific test, we can use the `--example` flag to match against the test name:

```sh
make test-spec SPECOPTS="../spec/ruby/core/array/any_spec.rb --example='is false if the array is empty'"
make test-spec SPECOPTS="../spec/ruby/core/string/to_s_spec.rb --example='returns self when self.class == String'"
```

To run these specs with logs, we can use:
To run these specs with verbose logging, we can add `-v` to the `SPECOPTS`:

```sh
make test-spec SPECOPTS=-Vfs
make test-spec SPECOPTS="../spec/ruby/core/string/to_s_spec.rb -Vfs"
```

To run a ruby-spec file or directory with GNU make, we can use
(GNU make only) To run a ruby-spec file or directory, we can use

```sh
make spec/ruby/core/foo/bar_spec.rb
make ../spec/ruby/core/string/to_s_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:
The bundler test suite is defined in [the RubyGems repository](https://github.com/rubygems/rubygems/tree/master/bundler/spec), and is periodically mirrored into the `spec/ruby` directory of this repository. We can run this using:

```sh
make test-bundler
Expand Down

0 comments on commit 8cc47c9

Please sign in to comment.