diff options
Diffstat (limited to 'doc/contributing')
| -rw-r--r-- | doc/contributing/building_ruby.md | 191 | ||||
| -rw-r--r-- | doc/contributing/documentation_guide.md | 279 | ||||
| -rw-r--r-- | doc/contributing/glossary.md | 41 | ||||
| -rw-r--r-- | doc/contributing/making_changes_to_stdlibs.md | 2 | ||||
| -rw-r--r-- | doc/contributing/testing_ruby.md | 72 |
5 files changed, 488 insertions, 97 deletions
diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md index f20eacc0ae..96cee40cb4 100644 --- a/doc/contributing/building_ruby.md +++ b/doc/contributing/building_ruby.md @@ -1,41 +1,120 @@ # Building Ruby -## Quick start guide +## Dependencies 1. Install the prerequisite dependencies for building the CRuby interpreter: * C compiler + + For RubyGems, you will also need: + + * OpenSSL 1.1.x or 3.0.x / LibreSSL + * libyaml 0.1.7 or later + * zlib + + If you want to build from the git repository, you will also need: + * autoconf - 2.67 or later - * bison - 2.0 or later - * gperf - 3.0.3 or later - * ruby - 2.7 or later + * gperf - 3.1 or later + * Usually unneeded; only if you edit some source files using gperf + * ruby - 3.0 or later + * We can upgrade this version to system ruby version of the latest Ubuntu LTS. 2. Install optional, recommended dependencies: - * OpenSSL/LibreSSL - * readline/editline (libedit) - * zlib - * libffi - * libyaml + * 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](https://docs.ruby-lang.org/en/master/RubyVM/YJIT.html). -3. Checkout the CRuby source code: + 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. + ``` shell + export CONFIGURE_ARGS="" + for ext in openssl readline libyaml zlib; do + CONFIGURE_ARGS="${CONFIGURE_ARGS} --with-$ext-dir=$(brew --prefix $ext)" + done ``` - git clone https://github.com/ruby/ruby.git + +## Quick start guide + +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: + + ``` 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: + + ``` shell + git clone https://github.com/ruby/ruby.git + cd ruby + ``` + + Generate the configure file: + + ``` shell + ./autogen.sh + ``` + +2. Create a `build` directory separate from the source directory: + + ``` shell + mkdir build && cd build ``` -4. Generate the configuration files and build: + While it's not necessary to build in a separate directory, it's good practice to do so. + +3. We'll install Ruby in `~/.rubies/ruby-master`, so create the directory: + ``` shell + mkdir ~/.rubies ``` - ./autogen.sh - mkdir build && cd build # its good practice to build outside of source dir - mkdir ~/.rubies # we will install to .rubies/ruby-master in our home dir + +4. Run configure: + + ``` shell ../configure --prefix="${HOME}/.rubies/ruby-master" + ``` + + - Also `-C` (or `--config-cache`) would reduce time to configure from the next time. + +5. Build Ruby: + + ``` shell + make + ``` + +6. [Run tests](testing_ruby.md) to confirm your build succeeded. + +7. Install Ruby: + + ``` shell make install ``` -5. [Run tests](testing_ruby.md) to confirm your build succeeded + - 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 @@ -44,20 +123,38 @@ 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: -``` +``` shell 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. It can be useful in Ruby development because it allows for faster build times. Miniruby is built before Ruby. A functional Miniruby is required to build Ruby. To build Miniruby: -``` +``` shell make miniruby ``` @@ -72,3 +169,59 @@ 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 + +### 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 (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 +../configure CC=clang 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! + +* 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). +* Currently, ASAN will only work correctly when using a recent head build of LLVM/Clang - it requires [this bugfix](https://github.com/llvm/llvm-project/pull/75290) related to multithreaded `fork`, which is not yet in any released version. See [here](https://llvm.org/docs/CMake.html) for instructions on how to build LLVM/Clang from source (note you will need at least the `clang` and `compiler-rt` projects enabled). Then, you will need to replace `CC=clang` in the instructions with an explicit path to your built Clang binary. +* 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 + +You need to be able to use gcc (gcov) and lcov visualizer. + +``` shell +./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/documentation_guide.md b/doc/contributing/documentation_guide.md index 6219ec605c..59953d0d52 100644 --- a/doc/contributing/documentation_guide.md +++ b/doc/contributing/documentation_guide.md @@ -20,14 +20,16 @@ build directory: make html ``` +If you don't have a build directory, follow the [quick start +guide](building_ruby.md#label-Quick+start+guide) up to step 4. + Then you can preview your changes by opening `{build folder}/.ext/html/index.html` file in your browser. - ## Goal The goal of Ruby documentation is to impart the most important -and relevant in the shortest time. +and relevant information in the shortest time. The reader should be able to quickly understand the usefulness of the subject code and how to use it. @@ -41,16 +43,17 @@ Use your judgment about what the user needs to know. - Write short declarative or imperative sentences. - Group sentences into (ideally short) paragraphs, each covering a single topic. -- Organize material with [headers](rdoc-ref:RDoc::Markup@Headers). +- Organize material with + [headings](rdoc-ref:RDoc::MarkupReference@Headings). - Refer to authoritative and relevant sources using - [links](rdoc-ref:RDoc::Markup@Links). + [links](rdoc-ref:RDoc::MarkupReference@Links). - Use simple verb tenses: simple present, simple past, simple future. - Use simple sentence structure, not compound or complex structure. - Avoid: - Excessive comma-separated phrases; - consider a [list](rdoc-ref:RDoc::Markup@Simple+Lists). + consider a [list](rdoc-ref:RDoc::MarkupReference@Lists). - Idioms and culture-specific references. - - Overuse of headers. + - Overuse of headings. - Using US-ASCII-incompatible characters in C source files; see [Characters](#label-Characters) below. @@ -92,7 +95,7 @@ involving new files `doc/*.rdoc`: Example: - ```c + ``` /* * call-seq: * each_byte {|byte| ... } -> self @@ -124,32 +127,136 @@ a.shuffle! #=> [2, 3, 1] a #=> [2, 3, 1] ``` -### Headers +### Headings + +Organize a long discussion for a class or module with [headings](rdoc-ref:RDoc::MarkupReference@Headings). -Organize a long discussion with [headers](rdoc-ref:RDoc::Markup@Headers). +Do not use formal headings in the documentation for a method or constant. + +In the rare case where heading-like structures are needed +within the documentation for a method or constant, use +[bold text](rdoc-ref:RDoc::MarkupReference@Bold) +as pseudo-headings. ### Blank Lines A blank line begins a new paragraph. -A [code block](rdoc-ref:RDoc::Markup@Paragraphs+and+Verbatim) -or [list](rdoc-ref:RDoc::Markup@Simple+Lists) +A [code block](rdoc-ref:RDoc::MarkupReference@Code+Blocks) +or [list](rdoc-ref:RDoc::MarkupReference@Lists) should be preceded by and followed by a blank line. This is unnecessary for the HTML output, but helps in the `ri` output. +### \Method Names + +For a method name in text: + +- For a method in the current class or module, + use a double-colon for a singleton method, + or a hash mark for an instance method: + <tt>::bar</tt>, <tt>#baz</tt>. +- Otherwise, include the class or module name + and use a dot for a singleton method, + or a hash mark for an instance method: + <tt>Foo.bar</tt>, <tt>Foo#baz</tt>. + +### Embedded Code and Commands + +Code or commands embedded in running text (i.e., not in a code block) +should marked up as +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Code that is a simple string should include the quote marks. + ### Auto-Linking In general, \RDoc's auto-linking should not be suppressed. For example, we should write `Array`, not `\Array`. -We might consider whether to suppress when: +However, suppress when the word in question: -- The word in question does not refer to a Ruby entity +- Does not refer to a Ruby entity (e.g., some uses of _Class_ or _English_). -- The reference is to the current class document - (e.g., _Array_ in the documentation for class `Array`). -- The same reference is repeated many times - (e.g., _RDoc_ on this page). +- Refers to the current document + (e.g., _Array_ in the documentation for class `Array`); + in that case, the word should be forced to + [monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Most often, the name of a class, module, or method +will be auto-linked: + +- Array. +- Enumerable. +- File.new +- File#read. + +If not, or if you suppress autolinking, consider forcing +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +### Explicit Links + +When writing an explicit link, follow these guidelines. + +#### +rdoc-ref+ Scheme + +Use the +rdoc-ref+ scheme for: + +- A link in core documentation to other core documentation. +- A link in core documentation to documentation in a standard library package. +- A link in a standard library package to other documentation in that same + standard library package. + +See section "+rdoc-ref+ Scheme" in {Links}[rdoc-ref:RDoc::MarkupReference@Links]. + +#### URL-Based Link + +Use a full URL-based link for: + +- A link in standard library documentation to documentation in the core. +- A link in standard library documentation to documentation in a different + standard library package. + +Doing so ensures that the link will valid even when the package documentation +is built independently (separately from the core documentation). + +The link should lead to a target in https://docs.ruby-lang.org/en/master/. + +Also use a full URL-based link for a link to an off-site document. + +### Variable Names + +The name of a variable (as specified in its call-seq) should be marked up as +[monofont](rdoc-ref:RDoc::MarkupReference@Monofont). + +Also, use monofont text for the name of a transient variable +(i.e., one defined and used only in the discussion, such as +n+). + +### HTML Tags + +In general, avoid using HTML tags (even in formats where it's allowed) +because `ri` (the Ruby Interactive reference tool) +may not render them properly. + +### Tables + +In particular, avoid building tables with HTML tags +(<tt><table></tt>, etc.). + +Alternatives: + +- A {verbatim text block}[rdoc-ref:RDoc::MarkupReference@Verbatim+Text+Blocks], + using spaces and punctuation to format the text; + note that {text markup}[rdoc-ref:RDoc::MarkupReference@Text+Markup] + will not be honored: + + - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/file.c#L6570-L6596]. + - Corresponding {output}[rdoc-ref:File@Read-2FWrite+Mode]. + +- (Markdown format only): A {Github Flavored Markdown (GFM) table}[https://github.github.com/gfm/#tables-extension-], + using special formatting for the text: + + - Example {source}[https://github.com/ruby/ruby/blob/34d802f32f00df1ac0220b62f72605827c16bad8/doc/contributing/glossary.md?plain=1]. + - Corresponding {output}[https://docs.ruby-lang.org/en/master/contributing/glossary_md.html]. ## Documenting Classes and Modules @@ -179,9 +286,12 @@ Guidelines: - The section title is `What's Here`. - Consider listing the parent class and any included modules; consider - [links](rdoc-ref:RDoc::Markup@Links) + [links](rdoc-ref:RDoc::MarkupReference@Links) to their "What's Here" sections if those exist. -- List methods as a bullet list: +- All methods mentioned in the left-pane table of contents + should be listed (including any methods extended from another class). +- Attributes (which are not included in the TOC) may also be listed. +- Display methods as items in one or more bullet lists: - Begin each item with the method name, followed by a colon and a short description. @@ -189,9 +299,9 @@ Guidelines: (and do not list the aliases separately). - Check the rendered documentation to determine whether \RDoc has recognized the method and linked to it; if not, manually insert a - [link](rdoc-ref:RDoc::Markup@Links). + [link](rdoc-ref:RDoc::MarkupReference@Links). -- If there are numerous entries, consider grouping them into subsections with headers. +- If there are numerous entries, consider grouping them into subsections with headings. - If there are more than a few such subsections, consider adding a table of contents just below the main section title. @@ -206,7 +316,6 @@ The general structure of the method documentation should be: - Details and examples. - Argument description (if necessary). - Corner cases and exceptions. -- Aliases. - Related methods (optional). ### Calling Sequence (for methods written in C) @@ -215,59 +324,89 @@ For methods written in Ruby, \RDoc documents the calling sequence automatically. For methods written in C, \RDoc cannot determine what arguments the method accepts, so those need to be documented using \RDoc directive -[`:call-seq:`](rdoc-ref:RDoc::Markup@Method+arguments). +[`call-seq:`](rdoc-ref:RDoc::MarkupReference@Directives+for+Method+Documentation). -Example: +For a singleton method, use the form: -```c -* call-seq: -* array.count -> integer -* array.count(obj) -> integer -* array.count {|element| ... } -> integer +``` +class_name.method_name(method_args) {|block_args| ... } -> return_type ``` -When creating the `call-seq`, use the form +Example: ``` -receiver_type.method_name(arguments) {|block_arguments|} -> return_type +* call-seq: +* Hash.new(default_value = nil) -> new_hash +* Hash.new {|hash, key| ... } -> new_hash ``` -Omit the parentheses for cases where the method does not accept arguments, -and omit the block for cases where a block is not accepted. - -In the cases where method can return multiple different types, separate the -types with "or". If the method can return any type, use "object". If the -method returns the receiver, use "self". - -In cases where the method accepts optional arguments, use a `call-seq` with -an optional argument if the method has the same behavior when an argument is -omitted as when the argument is passed with the default value. For example, -use: +For an instance method, use the form +(omitting any prefix, just as RDoc does for a Ruby-coded method): ``` -obj.respond_to?(symbol, include_all=false) -> true or false +method_name(method_args) {|block_args| ... } -> return_type ``` +For example, in Array, use: -Instead of: +``` +* call-seq: +* count -> integer +* count(obj) -> integer +* count {|element| ... } -> integer +``` ``` -obj.respond_to?(symbol) -> true or false -obj.respond_to?(symbol, include_all) -> true or false +* call-seq: +* <=> other -> -1, 0, 1, or nil ``` -However, as shown above for `Array#count`, use separate lines if the -behavior is different if the argument is omitted. +Arguments: + +- If the method does not accept arguments, omit the parentheses. +- If the method accepts optional arguments: + + - Separate each argument name and its default value with ` = ` + (equal-sign with surrounding spaces). + - If the method has the same behavior with either an omitted + or an explicit argument, use a `call-seq` with optional arguments. + For example, use: + + ``` + respond_to?(symbol, include_all = false) -> true or false + ``` -Omit aliases from the `call-seq`, but mention them near the end (see below). + - If the behavior is different with an omitted or an explicit argument, + use a `call-seq` with separate lines. + For example, in Enumerable, use: + ``` + * max -> element + * max(n) -> array + ``` -A `call-seq` block should have `{|x| ... }`, not `{|x| block }` or `{|x| code }`. +Block: -A `call-seq` output should: +- If the method does not accept a block, omit the block. +- If the method accepts a block, the `call-seq` should have `{|args| ... }`, + not `{|args| block }` or `{|args| code }`. -- Have `self`, not `receiver` or `array`. -- Begin with `new_` if and only if the output object is a new instance - of the receiver's class, to emphasize that the output object is not `self`. +Return types: + +- If the method can return multiple different types, + separate the types with "or" and, if necessary, commas. +- If the method can return multiple types, use +object+. +- If the method returns the receiver, use +self+. +- If the method returns an object of the same class, + prefix `new_` if an only if the object is not +self+; + example: `new_array`. + +Aliases: + +- Omit aliases from the `call-seq`, unless the alias is an + operator method. If listing both a regular method and an + operator method in the `call-seq`, explain in the details and + examples section when it is recommended to use the regular method + and when it is recommended to use the operator method. ### Synopsis @@ -324,7 +463,7 @@ argument passed if it is not obvious, not explicitly mentioned in the details, and not implicitly shown in the examples. If there is more than one argument or block argument, use a -[labeled list](rdoc-ref:RDoc::Markup@Labeled+Lists). +[labeled list](rdoc-ref:RDoc::MarkupReference@Labeled+Lists). ### Corner Cases and Exceptions @@ -337,25 +476,27 @@ you do not need to document that a `TypeError` is raised if a non-integer is passed. Do not provide examples of exceptions being raised unless that is a common case, such as `Hash#fetch` raising a `KeyError`. -### Aliases - -Mention aliases in the form - -```c -// Array#find_index is an alias for Array#index. -``` - ### Related Methods (optional) In some cases, it is useful to document which methods are related to the current method. For example, documentation for `Hash#[]` might mention `Hash#fetch` as a related method, and `Hash#merge` might mention -`Hash#merge!` as a related method. Consider which methods may be related -to the current method, and if you think the reader would benefit it, -at the end of the method documentation, add a line starting with -"Related: " (e.g. "Related: #fetch"). Don't list more than three -related methods. If you think more than three methods are related, -pick the three you think are most important and list those three. +`Hash#merge!` as a related method. + +- Consider which methods may be related + to the current method, and if you think the reader would benefit it, + at the end of the method documentation, add a line starting with + "Related: " (e.g. "Related: #fetch."). +- Don't list more than three related methods. + If you think more than three methods are related, + list the three you think are most important. +- Consider adding: + + - A phrase suggesting how the related method is similar to, + or different from,the current method. + See an example at Time#getutc. + - Example code that illustrates the similarities and differences. + See examples at Time#ctime, Time#inspect, Time#to_s. ### Methods Accepting Multiple Argument Types diff --git a/doc/contributing/glossary.md b/doc/contributing/glossary.md new file mode 100644 index 0000000000..86c6671fbd --- /dev/null +++ b/doc/contributing/glossary.md @@ -0,0 +1,41 @@ +# Ruby Internals Glossary + +Just a list of acronyms I've run across in the Ruby source code and their meanings. + +| Term | Definition | +| --- | -----------| +| `BIN` | Basic Instruction Name. Used as a macro to reference the YARV instruction. Converts pop into YARVINSN_pop. | +| `bop` | Basic Operator. Relates to methods like `Integer` plus and minus which can be optimized as long as they haven't been redefined. | +| `cc` | Call Cache. An inline cache structure for the call site. Stored in the `cd` | +| `cd` | Call Data. A data structure that points at the `ci` and the `cc`. `iseq` objects points at the `cd`, and access call information and call caches via this structure | +| `cfp`| Control Frame Pointer. Represents a Ruby stack frame. Calling a method pushes a new frame (cfp), returning pops a frame. Points at the `pc`, `sp`, `ep`, and the corresponding `iseq`| +| `ci` | Call Information. Refers to an `rb_callinfo` struct. Contains call information about the call site, including number of parameters to be passed, whether it they are keyword arguments or not, etc. Used in conjunction with the `cc` and `cd`. | +| `cref` | Class reference. A structure pointing to the class reference where `klass_or_self`, visibility scope, and refinements are stored. It also stores a pointer to the next class in the hierarchy referenced by `rb_cref_struct * next`. The Class reference is lexically scoped. | +| CRuby | Implementation of Ruby written in C | +| `cvar` | Class Variable. Refers to a Ruby class variable like `@@foo` | +| `dvar` | Dynamic Variable. Used by the parser to refer to local variables that are defined outside of the current lexical scope. For example `def foo; bar = 1; -> { p bar }; end` the "bar" inside the block is a `dvar` | +| `ec` | Execution Context. The top level VM context, points at the current `cfp` | +| `ep` | Environment Pointer. Local variables, including method parameters are stored in the `ep` array. The `ep` is pointed to by the `cfp` | +| GC | Garbage Collector | +| `gvar` | Global Variable. Refers to a Ruby global variable like `$$`, etc | +| `ICLASS` | Internal Class. When a module is included, the target class gets a new superclass which is an instance of an `ICLASS`. The `ICLASS` represents the module in the inheritance chain. | +| `ifunc` | Internal FUNCtion. A block implemented in C. | +| `iseq` | Instruction Sequence. Usually "iseq" in the C code will refer to an `rb_iseq_t` object that holds a reference to the actual instruction sequences which are executed by the VM. The object also holds information about the code, like the method name associated with the code. | +| `insn` | Instruction. Refers to a YARV instruction. | +| `insns` | Instructions. Usually an array of YARV instructions. | +| `ivar` | Instance Variable. Refers to a Ruby instance variable like `@foo` | +| `imemo` | Internal Memo. A tagged struct whose memory is managed by Ruby's GC, but contains internal information and isn't meant to be exposed to Ruby programs. Contains various information depending on the type. See the `imemo_type` enum for different types. | +| JIT | Just In Time compiler | +| `lep` | Local Environment Pointer. An `ep` which is tagged `VM_ENV_FLAG_LOCAL`. Usually this is the `ep` of a method (rather than a block, whose `ep` isn't "local") | +| `local` | Local. Refers to a local variable. | +| `me` | Method Entry. Refers to an `rb_method_entry_t` struct, the internal representation of a Ruby method. +| MRI | Matz's Ruby Implementation | +| `pc` | Program Counter. Usually the instruction that will be executed _next_ by the VM. Pointed to by the `cfp` and incremented by the VM | +| `sp` | Stack Pointer. The top of the stack. The VM executes instructions in the `iseq` and instructions will push and pop values on the stack. The VM updates the `sp` on the `cfp` to point at the top of the stack| +| `svar` | Special Variable. Refers to special local variables like `$~` and `$_`. See the `getspecial` instruction in `insns.def` | +| `VALUE` | VALUE is a pointer to a ruby object from the Ruby C code. | +| VM | Virtual Machine. In MRI's case YARV (Yet Another Ruby VM) +| WB | Write Barrier. To do with GC write barriers | +| WC | Wild Card. As seen in instructions like `getlocal_WC_0`. It means this instruction takes a "wild card" for the parameter (in this case an index for a local) | +| YARV | Yet Another Ruby VM. The virtual machine that CRuby uses | +| ZOMBIE | A zombie object. An object that has a finalizer which hasn't been executed yet. The object has been collected, so is "dead", but the finalizer hasn't run yet so it's still somewhat alive. | diff --git a/doc/contributing/making_changes_to_stdlibs.md b/doc/contributing/making_changes_to_stdlibs.md index ef3811ea12..3b33092fea 100644 --- a/doc/contributing/making_changes_to_stdlibs.md +++ b/doc/contributing/making_changes_to_stdlibs.md @@ -8,7 +8,7 @@ For example, CSV lives in [a separate repository](https://github.com/ruby/csv) a ## Maintainers -You can find the list of maintainers [here](https://docs.ruby-lang.org/en/master/maintainers_rdoc.html#label-Maintainers). +You can find the list of maintainers [here](https://docs.ruby-lang.org/en/master/maintainers_md.html#label-Maintainers). ## Build diff --git a/doc/contributing/testing_ruby.md b/doc/contributing/testing_ruby.md index c54b14c710..dfb7fb3a65 100644 --- a/doc/contributing/testing_ruby.md +++ b/doc/contributing/testing_ruby.md @@ -20,6 +20,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+ make btest OPTS=-v ``` + To run individual bootstrap tests, we can either specify a list of filenames or use the `--sets` flag in the variable `BTESTS`: + + ``` + make btest BTESTS="bootstraptest/test_fork.rb bootstraptest/tes_gc.rb" + make btest BTESTS="--sets=fork,gc" + ``` + If we want to run the bootstrap test suite on Ruby (not Miniruby), we can use: ``` @@ -32,6 +39,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,17 +54,23 @@ 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: ``` - make test-all TESTS="../test/ruby/test_alias.rb --name=/test_aias_with_zsuper_method/" + make test-all TESTS="../test/ruby/test_alias.rb --name=TestAlias#test_alias_with_zsuper_method" ``` To run these specs with logs, we can use: @@ -59,7 +79,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+ make test-all TESTS=-v ``` - If we would like to run both the `test/` and `bootstraptest/` test suites, we can run + We can display the help of the `TESTS` option: + + ``` + 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 ``` make check @@ -73,22 +99,34 @@ 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 `SPECOPTS` to specify the directory: ``` - make test-spec MSPECOPT=spec/ruby/core/array/any_spec.rb + make test-spec SPECOPTS=spec/ruby/core/array + ``` + + To run a specific file, we can also use `SPECOPTS` to specify the file: + + ``` + make test-spec SPECOPTS=spec/ruby/core/array/any_spec.rb ``` To run a specific test, we can use the `--example` flag to match against the test name: ``` - make test-spec MSPECOPT="../spec/ruby/core/array/any_spec.rb --example='is false if the array is empty'" + make test-spec SPECOPTS="../spec/ruby/core/array/any_spec.rb --example='is false if the array is empty'" ``` To run these specs with logs, we can use: ``` - make test-spec MSPECOPT=-Vfs + make test-spec SPECOPTS=-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) @@ -98,3 +136,21 @@ 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 + ``` + +## Troubleshooting + +### Running test suites on s390x CPU Architecture + +If we see failing tests related to the zlib library on s390x CPU architecture, we can run the test suites with `DFLTCC=0` to pass: + +``` +DFLTCC=0 make check +``` + +The failures can happen with the zlib library applying the patch [madler/zlib#410](https://github.com/madler/zlib/pull/410) to enable the deflate algorithm producing a different compressed byte stream. We manage this issue at [[ruby-core:114942][Bug #19909]](https://bugs.ruby-lang.org/issues/19909). |