From c00feffb46ac646605adc277b5454e6b067e2d8a Mon Sep 17 00:00:00 2001 From: Jemma Issroff Date: Mon, 9 May 2022 11:45:50 -0400 Subject: [PATCH] Improve documentation on contributing to Ruby co-authored-by: Peter Zhu co-authored-by: Stan Lo --- .document | 1 - CONTRIBUTING.md | 6 +- README.md | 93 +--- doc/.document | 1 + doc/contributing.md | 10 + doc/contributing.rdoc | 402 ------------------ doc/contributing/building_ruby.md | 74 ++++ .../documentation_guide.md} | 220 ++++++---- doc/contributing/making_changes_to_ruby.md | 36 ++ doc/contributing/reporting_issues.md | 91 ++++ doc/contributing/testing_ruby.md | 100 +++++ doc/hacking.md | 104 ----- doc/make_cheatsheet.md | 124 ------ 13 files changed, 442 insertions(+), 820 deletions(-) create mode 100644 doc/contributing.md delete mode 100644 doc/contributing.rdoc create mode 100644 doc/contributing/building_ruby.md rename doc/{documentation_guide.rdoc => contributing/documentation_guide.md} (64%) create mode 100644 doc/contributing/making_changes_to_ruby.md create mode 100644 doc/contributing/reporting_issues.md create mode 100644 doc/contributing/testing_ruby.md delete mode 100644 doc/hacking.md delete mode 100644 doc/make_cheatsheet.md diff --git a/.document b/.document index 9cdd66f87a..5494bcc7fe 100644 --- a/.document +++ b/.document @@ -41,7 +41,6 @@ README.ja.md COPYING COPYING.ja -CONTRIBUTING.md LEGAL diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7363c106a2..13df6087ca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1 @@ -Please see the [official issue tracker], [doc/contributing.rdoc] and wiki [HowToContribute]. - -[official issue tracker]: https://bugs.ruby-lang.org -[doc/contributing.rdoc]: contributing.rdoc -[HowToContribute]: https://bugs.ruby-lang.org/projects/ruby/wiki/HowToContribute +See ["Contributing to Ruby"](https://docs.ruby-lang.org/en/master/contributing_md.html), which includes setup and build instructions. diff --git a/README.md b/README.md index a4a2ef1c91..0350ec3fb2 100644 --- a/README.md +++ b/README.md @@ -74,107 +74,20 @@ in the mail body (not subject) to the address [ruby-talk-request@ruby-lang.org]. [ruby-talk-request@ruby-lang.org]: mailto:ruby-talk-request@ruby-lang.org?subject=Join%20Ruby%20Mailing%20List&body=subscribe -## Requirements to build from repository - -1. GNU or BSD make -2. C99 compiler -3. autoconf 2.67 or higher -4. automake 1.15 or higher -5. bison 2.3 or higher -6. Ruby 2.2 or higher - -When building from a released version, only a C99 compiler and GNU or BSD make -is required. - -## How to compile and install - -1. If you want to use Microsoft Visual C++ to compile Ruby, read - [win32/README.win32](rdoc-ref:win32/README.win32) instead of this document. - -2. Run `./autogen.sh` to generate configure, when you build the source checked - out from the Git repository. - -3. Run `./configure`, which will generate `config.h` and `Makefile`. - - Some C compiler flags may be added by default depending on your - environment. Specify `optflags=..` and `warnflags=..` as necessary to - override them. - -4. Edit `include/ruby/defines.h` if you need. Usually this step will not be needed. - -5. Optional: Remove comment mark(`#`) before the module names from `ext/Setup`. - - This step is only necessary if you want to link modules statically. - - If you don't want to compile dynamic extensions (probably on architectures - which do not allow dynamic loading), remove comment mark from the line - "`#option nodynamic`" in `ext/Setup`. - - Usually this step will not be needed. - -6. Run `make`. - - * On Mac, set RUBY\_CODESIGN environment variable with a signing identity. - It uses the identity to sign `ruby` binary. See also codesign(1). - -7. Optionally, run '`make check`' to check whether the compiled Ruby - interpreter works well. If you see the message "`check succeeded`", your - Ruby works as it should (hopefully). - -8. Run '`make install`'. - - This command will create the following directories and install files into - them. - - * `${DESTDIR}${prefix}/bin` - * `${DESTDIR}${prefix}/include/ruby-${MAJOR}.${MINOR}.${TEENY}` - * `${DESTDIR}${prefix}/include/ruby-${MAJOR}.${MINOR}.${TEENY}/${PLATFORM}` - * `${DESTDIR}${prefix}/lib` - * `${DESTDIR}${prefix}/lib/ruby` - * `${DESTDIR}${prefix}/lib/ruby/${MAJOR}.${MINOR}.${TEENY}` - * `${DESTDIR}${prefix}/lib/ruby/${MAJOR}.${MINOR}.${TEENY}/${PLATFORM}` - * `${DESTDIR}${prefix}/lib/ruby/site_ruby` - * `${DESTDIR}${prefix}/lib/ruby/site_ruby/${MAJOR}.${MINOR}.${TEENY}` - * `${DESTDIR}${prefix}/lib/ruby/site_ruby/${MAJOR}.${MINOR}.${TEENY}/${PLATFORM}` - * `${DESTDIR}${prefix}/lib/ruby/vendor_ruby` - * `${DESTDIR}${prefix}/lib/ruby/vendor_ruby/${MAJOR}.${MINOR}.${TEENY}` - * `${DESTDIR}${prefix}/lib/ruby/vendor_ruby/${MAJOR}.${MINOR}.${TEENY}/${PLATFORM}` - * `${DESTDIR}${prefix}/lib/ruby/gems/${MAJOR}.${MINOR}.${TEENY}` - * `${DESTDIR}${prefix}/share/man/man1` - * `${DESTDIR}${prefix}/share/ri/${MAJOR}.${MINOR}.${TEENY}/system` - - If Ruby's API version is '*x.y.z*', the `${MAJOR}` is '*x*', the - `${MINOR}` is '*y*', and the `${TEENY}` is '*z*'. - - **NOTE**: teeny of the API version may be different from one of Ruby's - program version - - You may have to be a super user to install Ruby. - -If you fail to compile Ruby, please send the detailed error report with the -error log and machine/OS type, to help others. - -Some extension libraries may not get compiled because of lack of necessary -external libraries and/or headers. You will need to run '`make distclean-ext`' -to remove old configuration after installing them in such a case. - ## Copying See the file [COPYING](rdoc-ref:COPYING). ## Feedback -Questions about the Ruby language can be asked on the [Ruby-Talk] mailing list +Questions about the Ruby language can be asked on the [Ruby-Talk](https://www.ruby-lang.org/en/community/mailing-lists) mailing list or on websites like https://stackoverflow.com. -Bugs should be reported at https://bugs.ruby-lang.org. Read [HowToReport] for more information. - -[Ruby-Talk]: https://www.ruby-lang.org/en/community/mailing-lists -[HowToReport]: https://bugs.ruby-lang.org/projects/ruby/wiki/HowToReport +Bugs should be reported at https://bugs.ruby-lang.org. Read ["Reporting Issues"](https://docs.ruby-lang.org/en/master/reporting_issues_md.html) for more information. ## Contributing -See the file [CONTRIBUTING.md](rdoc-ref:CONTRIBUTING) +See ["Contributing to Ruby"](https://docs.ruby-lang.org/en/master/contributing_md.html), which includes setup and build instructions. ## The Author diff --git a/doc/.document b/doc/.document index 84c1be6e5e..03d332367c 100644 --- a/doc/.document +++ b/doc/.document @@ -1,6 +1,7 @@ *.md *.rb *.rdoc +contributing NEWS syntax optparse diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000000..1f53e6f56e --- /dev/null +++ b/doc/contributing.md @@ -0,0 +1,10 @@ +# Contributing to Ruby + +This guide outlines ways to get started with contributing to Ruby: + +* [Reporting issues](contributing/reporting_issues.md): How to report issues, how to request features, and how backporting works +* [Building Ruby](contributing/building_ruby.md): How to build Ruby on your local machine for development +* [Testing Ruby](contributing/testing_ruby.md): How to test Ruby on your local machine once you've built it +* [Making changes to Ruby](contributing/making_changes_to_ruby.md): How to submit pull requests + to change Ruby's documentation, code, test suite, or standard libraries +* [Making changes to Ruby documentation](contributing/documentation_guide.md): How to make changes to Ruby documentation \ No newline at end of file diff --git a/doc/contributing.rdoc b/doc/contributing.rdoc deleted file mode 100644 index 00875d1428..0000000000 --- a/doc/contributing.rdoc +++ /dev/null @@ -1,402 +0,0 @@ -= Contributing to Ruby - -Ruby has a vast and friendly community with hundreds of people contributing to -a thriving open-source ecosystem. This guide is designed to cover ways for -participating in the development of CRuby. - -There are plenty of ways for you to help even if you're not ready to write -code or documentation. You can help by reporting issues, testing patches, and -trying out beta releases with your applications. - -== How To Report - -If you've encountered a bug in Ruby please report it to the redmine issue -tracker available at {bugs.ruby-lang.org}[https://bugs.ruby-lang.org/]. Do not -report security vulnerabilities here, there is a {separate -channel}[rdoc-label:label-Reporting+Security+Issues] for them. - -There are a few simple steps you should follow in order to receive feedback -on your ticket. - -* If you haven't already, - {sign up for an account}[https://bugs.ruby-lang.org/account/register] on the - bug tracker. -* Try the latest version. - - If you aren't already using the latest version, try installing a newer - stable release. See - {Downloading Ruby}[https://www.ruby-lang.org/en/downloads/]. -* Look to see if anyone already reported your issue, try - {searching on redmine}[https://bugs.ruby-lang.org/projects/ruby-master/issues] - for your problem. -* If you can't find a ticket addressing your issue, - {create a new one}[https://bugs.ruby-lang.org/projects/ruby-master/issues/new]. -* Choose the target version, usually current. Bugs will be first fixed in the - current release and then {backported}[rdoc-label:label-Backport+Requests]. -* Fill in the Ruby version you're using when experiencing this issue - (ruby -v). -* Attach any logs or reproducible programs to provide additional information. - Reproducible scripts should be as small as possible. -* Briefly describe your problem. A 2-3 sentence description will help give a - quick response. -* Pick a category, such as core for common problems, or lib for a standard - library. -* Check the {Maintainers - list}[https://bugs.ruby-lang.org/projects/ruby/wiki/Maintainers] and assign - the ticket if there is an active maintainer for the library or feature. -* If the ticket doesn't have any replies after 10 days, you can send a - reminder. -* Please reply to feedback requests. If a bug report doesn't get any feedback, - it'll eventually get rejected. - -=== Reporting to downstream distributions - -You can report downstream issues for the following distributions via their bug tracker: - -* {debian}[https://bugs.debian.org/cgi-bin/pkgreport.cgi?src=ruby-defaults] -* {freebsd}[http://www.freebsd.org/cgi/query-pr-summary.cgi?text=ruby] -* {redhat}[https://bugzilla.redhat.com/buglist.cgi?bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=MODIFIED] -* {macports}[https://trac.macports.org/query?status=assigned&status=new&status=reopened&port=~ruby] -* etc (add your distribution bug tracker here) - -== Reporting Security Issues - -Security vulnerabilities receive special treatment since they may negatively -affect many users. There is a private mailing list that all security issues -should be reported to and will be handled discretely. Email the -mailto:security@ruby-lang.org list and the problem will be published after -fixes have been released. You can also encrypt the issue using {the PGP public -key}[https://www.ruby-lang.org/security.asc] for the list. - -== Reporting Other Issues - -If you're having an issue with the website, or maybe the mailing list, you can -contact the webmaster to help resolve the problem. - -The current webmaster is: - -* Hiroshi SHIBATA (hsbt) - -You can also report issues with the ruby-lang.org website on the issue tracker: - -* {issue tracker}[https://github.com/ruby/www.ruby-lang.org/issues] - -== Resolve Existing Issues - -As a next step beyond reporting issues you can help the core team resolve -existing issues. If you check the Everyone's Issues list in GitHub Issues, -you will find a lot of issues already requiring attention. What can you do for -these? Quite a bit, actually: - -When a bug report goes for a while without any feedback, it goes to the bug -graveyard which is unfortunate. If you check the {issues -list}[https://bugs.ruby-lang.org/projects/ruby-master/issues] you will find lots -of delinquent bugs that require attention. - -You can help by verifying the existing tickets, try to reproduce the reported -issue on your own and comment if you still experience the bug. Some issues -lack attention because of too much ambiguity, to help you can narrow down the -problem and provide more specific details or instructions to reproduce the -bug. You might also try contributing a failing test in the form of a patch, -which we will cover later in this guide. - -It may also help to try out patches other contributors have submitted to -redmine, if gone without notice. In this case the +patch+ command is your -friend, see man patch for more information. Basically this would -go something like this: - - cd path/to/ruby - patch -p0 < path/to/patch - -You will then be prompted to apply the patch with the associated files. After -building ruby again, you should try to run the tests and verify if the change -actually worked or fixed the bug. It's important to provide valuable feedback -on the patch that can help reach the overall goal, try to answer some of these -questions: - -* What do you like about this change? -* What would you do differently? -* Are there any other edge cases not tested? -* Is there any documentation that would be affected by this change? - -If you can answer some or all of these questions, you're on the right track. -If your comment simply says "+1", then odds are that other reviewers aren't -going to take it too seriously. Show that you took the time to review the -patch. - -== How To Request Features - -If there's a new feature that you want to see added to Ruby, you will need to -write a convincing proposal and patch to implement the feature. - -For new features in CRuby, use the {'Feature' -tracker}[https://bugs.ruby-lang.org/projects/ruby-master/issues?set_filter=1&tracker_id=2] -on ruby-master. For non-CRuby dependent features, features that would apply to -alternate Ruby implementations such as JRuby and Rubinius, use the {CommonRuby -tracker}[https://bugs.ruby-lang.org/projects/common-ruby]. - -When writing a proposal be sure to check for previous discussions on the -topic and have a solid use case. You will need to be persuasive and convince -Matz on your new feature. You should also consider the potential compatibility -issues that this new feature might raise. - -Consider making your feature into a gem, and if there are enough people who -benefit from your feature it could help persuade ruby-core. Although feature -requests can seem like an alluring way to contribute to Ruby, often these -discussions can lead nowhere and exhaust time and energy that could be better -spent fixing bugs. Choose your battles. - -A good template for a feature proposal should look something like this: - -[Abstract] - Summary of your feature -[Background] - Describe current behavior and why it is problem. Related work, such as - solutions in other language helps us to understand the problem. -[Proposal] - Describe your proposal in details -[Details] - If it has complicated feature, describe it -[Usecase] - How would your feature be used? Who will benefit from it? -[Discussion] - Discuss about this proposal. A list of pros and cons will help start - discussion. -[Limitation] - Limitation of your proposal -[Another alternative proposal] - If there are alternative proposals, show them. -[See also] - Links to the other related resources - -== Backport Requests - -When a new version of Ruby is released, it starts at patch level 0 (p0), and -bugs will be fixed first on the master branch. If it's determined that a bug -exists in a previous version of Ruby that is still in the bug fix stage of -maintenance, then a patch will be backported. After the maintenance stage of a -particular Ruby version ends, it goes into "security fix only" mode which -means only security related vulnerabilities will be backported. Versions in -End-of-life (EOL) will not receive any updates and it is recommended you -upgrade as soon as possible. - -If a major security issue is found or after a certain amount of time since the -last patch level release, a new patch-level release will be made. - -When submitting a backport request please confirm the bug has been fixed in -newer versions and exists in maintenance mode versions. There is a backport -tracker for each major version still in maintenance where you can request a -particular revision merged in the affected version of Ruby. - -Each major version of Ruby has a release manager that should be assigned to -handle backport requests. You can find the list of release managers on the -{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering]. - -=== Branches - -Status and maintainers of branches are listed on the -{wiki}[https://bugs.ruby-lang.org/projects/ruby/wiki/ReleaseEngineering]. - -== Running tests - -In order to help resolve existing issues and contributing patches to Ruby you -need to be able to run the test suite. - -CRuby uses git for source control, the {git homepage}[https://git-scm.com/] -has installation instructions with links to documentation for learning more -about git. There is a mirror of the repository on {github}[https://github.com/ruby/ruby]. -For other resources see the {ruby-core documentation on -ruby-lang.org}[https://www.ruby-lang.org/en/community/ruby-core/]. - -Install the prerequisite dependencies for building the CRuby interpreter to -run tests. - -* C compiler -* autoconf - 2.67 or later, preferably 2.69. -* bison - 2.0 or later, preferably 3.4. -* gperf - 3.0.3 or later, preferably 3.1. -* ruby - Ruby itself is prerequisite in order to build Ruby from source. - You should use [a maintained version of Ruby](https://www.ruby-lang.org/en/downloads/). - -You should also have access to development headers for the following -libraries, but these are not required: - -* NDBM/QDBM -* GDBM -* OpenSSL/LibreSSL -* readline/editline(libedit) -* zlib -* libffi -* libyaml -* libexecinfo (FreeBSD) - -Now let's build CRuby: - -* Checkout the CRuby source code: - - git clone https://github.com/ruby/ruby.git ruby-master - -* Generate the configuration files and build: - - cd ruby-master - ./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 - ../configure --prefix="${HOME}/.rubies/ruby-master" - make up && make install - -After adding Ruby to your PATH, you should be ready to run the test suite: - - make test - -You can also use +test-all+ to run all of the tests with the RUNRUBY -interpreter just built. Use TESTS or RUNRUBYOPT to pass parameters, such as: - - make test-all TESTS=-v - -This is also how you can run a specific test from our build dir: - - make test-all TESTS=drb/test_drb.rb - -You can run +test+ and +test-all+ at once by +check+ . - - make check - -For older versions of Ruby you will need to run the build setup again after -checking out the associated branch in git, for example if you wanted to -checkout 1.9.3: - - git clone https://github.com/ruby/ruby.git --branch ruby_1_9_3 - -Once you checked out the source code, you can update the local copy by: - - make up - -Or, update, build, install and check, by just: - - make love - -== Contributing Documentation - -If you're interested in contributing documentation directly to CRuby there is -some information available at -{Contributing}[https://github.com/ruby/ruby#contributing]. - -There is also the {Ruby Reference -Manual}[https://github.com/rurema/doctree/wiki] in Japanese. - -== Contributing A Patch - -=== Deciding what to patch - -Before you submit a patch, there are a few things you should know: - -* Pay attention to the maintenance policy for stable and maintained versions of Ruby. -* Released versions in security mode will not merge feature changes. -* Search for previous discussions on ruby-core to verify the maintenance policy -* Patches must be distributed under Ruby's license. -* This license may change in the future, you must join the discussion if you don't agree to the change - -To improve the chance your patch will be accepted please follow these simple rules: - -* Bug fixes should be committed on master first -* Format of the patch file must be a unified diff (ie: diff -pu, svn diff, or git diff) -* Don't introduce cosmetic changes -* Follow the original coding style of the code -* Don't mix different changes in one commit - -First thing you should do is check out the code if you haven't already: - - git clone https://github.com/ruby/ruby.git ruby-master - -Now create a dedicated branch: - - cd ruby-master - git checkout -b my_new_branch - -The name of your branch doesn't really matter because it will only exist on -your local computer and won't be part of the official Ruby repository. It will -be used to create patches based on the differences between your branch and -master, or edge Ruby. - -=== Coding style - -Here are some general rules to follow when writing Ruby and C code for CRuby: - -* Indent 4 spaces for C without tabs (old codes might use tabs for eight-space indentation, - but newer codes recommend to use spaces only) -* Indent 2 space tabs for Ruby -* Do not use TABs in ruby codes -* ANSI C style for 1.9+ for function declarations -* Follow C90 (not C99) Standard -* PascalStyle for class/module names. -* UNDERSCORE_SEPARATED_UPPER_CASE for other constants. -* Capitalize words. -* ABBRs should be all upper case. -* Do as others do - -=== Commit messages - -When you're ready to commit: - - git commit path/to/files - -This will open your editor in which you write your commit message. -Use the following style for commit messages: - -* Use a succinct subject line. -* Include reasoning behind the change in the commit message, focusing on why - the change is being made. -* Refer to redmine issue (such as Fixes [Bug #1234] or Implements - [Feature #3456]), or discussion on the mailing list - (such as [ruby-core:12345]). -* For GitHub issues, use [GH-#] (such as [Fixes GH-234]). -* Follow the style used by other committers. - -=== Contributing your code - -Now that you've got some code you want to contribute, let's get set up to -generate a patch. Start by forking the github mirror, check the {github docs on -forking}[https://help.github.com/articles/fork-a-repo] if you get stuck here. -You will only need a github account if you intend to host your repository -on github. - -Next copy the writable url for your fork and add it as a git remote, replace -"my_username" with your github account name: - - git remote add my_fork git@github.com:my_username/ruby.git - # Now we can push our branch to our fork - git push my_fork my_new_branch - -In order to generate a patch that you can upload to the bug tracker, we can use -the github interface to review our changes just visit -https://github.com/my_username/ruby/compare/master...my_new_branch - -Next, you can simply add '.patch' to the end of this URL and it will generate -the patch for you, save the file to your computer and upload it to the bug -tracker. Alternatively you can submit a pull request, but for the best chances -to receive feedback add it is recommended you add it to redmine. - -Since git is a distributed system, you are welcome to host your git repository -on any {publicly accessible hosting -site}[https://git.wiki.kernel.org/index.php/GitHosting], including {hosting your -own}[https://www.kernel.org/pub/software/scm/git/docs/user-manual.html#public-repositories] -You may use the {'git format-patch'}[https://git-scm.com/docs/git-format-patch] -command to generate patch files to upload to redmine. You may also use -the {'git request-pull'}[https://git-scm.com/docs/git-request-pull] command for -formatting pull request messages to redmine. - -=== Updating the official repository - -If you are a committer, you can push changes directly into the official -repository: - - git push origin your-branch-name:master - -However, it is likely will have become outdated, and you will have to -update it. In that case, run: - - git fetch origin - git rebase remotes/origin/master - -and then try pushing your changes again. diff --git a/doc/contributing/building_ruby.md b/doc/contributing/building_ruby.md new file mode 100644 index 0000000000..01f8c838a8 --- /dev/null +++ b/doc/contributing/building_ruby.md @@ -0,0 +1,74 @@ +# Building Ruby + +## Quick start guide + +1. Install the prerequisite dependencies for building the CRuby interpreter: + + * C compiler + * autoconf - 2.67 or later + * bison - 2.0 or later + * gperf - 3.0.3 or later + * ruby - 2.7 or later + +2. Install optional, recommended dependencies: + + * OpenSSL/LibreSSL + * readline/editline (libedit) + * zlib + * libffi + * libyaml + * libexecinfo (FreeBSD) + +3. Checkout the CRuby source code: + + ``` + git clone https://github.com/ruby/ruby.git + ``` + +4. Generate the configuration files and build: + + ``` + ./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 + ../configure --prefix="${HOME}/.rubies/ruby-master" + make install + ``` + +5. [Run tests](testing_ruby.md) to confirm your build succeeded + +## More details + +If you're interested in continuing development on Ruby, here are more details +about Ruby's build to help out. + +### Running make scripts in parallel + +To run make scripts in parallel, pass flag `-j`. For instance, +to run tests on 8 processes, use: + +``` +make test-all -j8 +``` + +### 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: + +``` +make miniruby +``` + +## Debugging + +You can use either lldb or gdb for debugging. Before debugging, you need to create a `test.rb` +with the Ruby script you'd like to run. You can use the following make targets: + +* `make run`: Runs `test.rb` using Miniruby +* `make lldb`: Runs `test.rb` using Miniruby in lldb +* `make gdb`: Runs `test.rb` using Miniruby in gdb +* `make runruby`: Runs `test.rb` using Ruby +* `make lldb-runruby`: Runs `test.rb` using Ruby in lldb +* `make gdb-runruby`: Runs `test.rb` using Ruby in gdb diff --git a/doc/documentation_guide.rdoc b/doc/contributing/documentation_guide.md similarity index 64% rename from doc/documentation_guide.rdoc rename to doc/contributing/documentation_guide.md index ae006752a2..1425bf5edb 100644 --- a/doc/documentation_guide.rdoc +++ b/doc/contributing/documentation_guide.md @@ -1,10 +1,25 @@ -= Documentation Guide +# Documentation Guide This guide discusses recommendations for documenting classes, modules, and methods in the Ruby core and in the Ruby standard library. -== Goal +## Generating documentation + +Most Ruby documentation lives in the source files and is written in [RDoc format](https://ruby.github.io/rdoc/RDoc/Markup.html). + +Some pages live under the `doc` folder and can be written in either `.rdoc` or `.md` format, determined by the file extension. + +To generate the output of documentation changes in HTML in the `{build folder}/.ext/html` directory, run the following inside your build directory: + +``` +make html +``` + +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. @@ -15,27 +30,26 @@ Providing too little information is bad, but providing unimportant information or unnecessary examples is not good either. Use your judgment about what the user needs to know. -== General Guidelines +## General Guidelines - Keep in mind that the reader may not be fluent in \English. - 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 [headers](rdoc-ref:RDoc::Markup@Headers). - Refer to authoritative and relevant sources using - {links}[rdoc-ref:RDoc::Markup@Links]. + [links](rdoc-ref:RDoc::Markup@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). + - Idioms and culture-specific references. + - Overuse of headers. + - Using US-ASCII-incompatible characters in C source files; + see [Characters](#label-Characters) below. - - Excessive comma-separated phrases; - consider a {list}[rdoc-ref:RDoc::Markup@Simple+Lists]. - - Idioms and culture-specific references. - - Overuse of headers. - - Using US-ASCII-incompatible characters in C source files; - see {Characters}[#label-Characters] below. - -=== Characters +### Characters Use only US-ASCII-compatible characters in a C source file. (If you use other characters, the Ruby CI will gently let you know.) @@ -44,33 +58,36 @@ If want to put ASCII-incompatible characters into the documentation for a C-coded class, module, or method, there are workarounds involving new files doc/*.rdoc: -- For class +Foo+ (defined in file foo.c), +- For class `Foo` (defined in file foo.c), create file doc/foo.rdoc, declare class Foo; end, and place the class documentation above that declaration: - # :markup: ruby + ```ruby # Documentation for class Foo goes here. class Foo; end + ``` -- Similarly, for module +Bar+ (defined in file bar.c, +- Similarly, for module `Bar` (defined in file bar.c, create file doc/bar.rdoc, declare module Bar; end, and place the module documentation above that declaration: - # :markup: ruby + ```ruby # Documentation for module Bar goes here. module Bar; end + ``` - For a method, things are different. Documenting a method as above disables the "click to toggle source" feature in the rendered documentation. - Therefore it's best to use file inclusion: + Therefore it's best to use file inclusion: + + - Retain the call-seq in the C code. + - Use file inclusion (`:include:`) to include text from an .rdoc file. - - Retain the call-seq in the C code. - - Use file inclusion (+:include:+) to include text from an .rdoc file. - - Example: + Example: + ```c /* * call-seq: * each_byte {|byte| ... } -> self @@ -79,74 +96,77 @@ involving new files doc/*.rdoc: * \:include: doc/string/each_byte.rdoc * */ + ``` -=== \RDoc +### \RDoc Ruby is documented using RDoc. For information on \RDoc syntax and features, see the -{RDoc Markup Reference}[rdoc-ref:RDoc::Markup@RDoc+Markup+Reference]. +[RDoc Markup Reference](rdoc-ref:RDoc::Markup@RDoc+Markup+Reference). -=== Output from irb +### Output from irb For code examples, consider using interactive Ruby, -{irb}[https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html]. +[irb](https://ruby-doc.org/stdlib/libdoc/irb/rdoc/IRB.html). -For a code example that includes +irb+ output, +For a code example that includes `irb` output, consider aligning # => ... in successive lines. Alignment may sometimes aid readability: - a = [1, 2, 3] #=> [1, 2, 3] - a.shuffle! #=> [2, 3, 1] - a #=> [2, 3, 1] +```ruby +a = [1, 2, 3] #=> [1, 2, 3] +a.shuffle! #=> [2, 3, 1] +a #=> [2, 3, 1] +``` -=== Headers +### Headers -Organize a long discussion with {headers}[rdoc-ref:RDoc::Markup@Headers]. +Organize a long discussion with [headers](rdoc-ref:RDoc::Markup@Headers). -=== Blank Lines +### 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::Markup@Paragraphs+and+Verbatim) +or [list](rdoc-ref:RDoc::Markup@Simple+Lists) should be preceded by and followed by a blank line. -This is unnecessary for the HTML output, but helps in the +ri+ output. +This is unnecessary for the HTML output, but helps in the `ri` output. -=== Auto-Linking +### Auto-Linking In general, \RDoc's auto-linking should not be suppressed. -For example, we should write +Array+, not \Array. +For example, we should write `Array`, not \Array. We might consider whether to suppress when: - The word in question 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+). + (e.g., _Array_ in the documentation for class `Array`). - The same reference is repeated many times (e.g., _RDoc_ on this page). -== Documenting Classes and Modules +## Documenting Classes and Modules The general structure of the class or module documentation should be: -* Synopsis -* Common uses, with examples -* "What's Here" summary (optional) +- Synopsis +- Common uses, with examples +- "What's Here" summary (optional) -=== Synopsis +### Synopsis The synopsis is a short description of what the class or module does and why the reader might want to use it. Avoid details in the synopsis. -=== Common Uses +### Common Uses Show common uses of the class or module. Depending on the class or module, this section may vary greatly in both length and complexity. -=== What's Here Summary +### What's Here Summary The documentation for a class or module may include a "What's Here" section. @@ -154,54 +174,58 @@ 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::Markup@Links) to their "What's Here" sections if those exist. - List methods as a bullet list: - - Begin each item with the method name, followed by a colon - and a short description. - - If the method has aliases, mention them in parentheses before the colon - (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]. + - Begin each item with the method name, followed by a colon + and a short description. + - If the method has aliases, mention them in parentheses before the colon + (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). - If there are numerous entries, consider grouping them into subsections with headers. - If there are more than a few such subsections, consider adding a table of contents just below the main section title. -== Documenting Methods +## Documenting Methods -=== General Structure +### General Structure The general structure of the method documentation should be: -* Calling sequence (for methods written in C). -* Synopsis (short description). -* Details and examples. -* Argument description (if necessary). -* Corner cases and exceptions. -* Aliases. -* Related methods (optional). +- Calling sequence (for methods written in C). +- Synopsis (short description). +- Details and examples. +- Argument description (if necessary). +- Corner cases and exceptions. +- Aliases. +- Related methods (optional). -=== Calling Sequence (for methods written in C) +### Calling Sequence (for methods written in C) 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::Markup@Method+arguments). Example: - * call-seq: - * array.count -> integer - * array.count(obj) -> integer - * array.count {|element| ... } -> integer +``` +* call-seq: +* array.count -> integer +* array.count(obj) -> integer +* array.count {|element| ... } -> integer +``` When creating the call-seq, use the form - receiver_type.method_name(arguments) {|block_arguments|} -> return_type +``` +receiver_type.method_name(arguments) {|block_arguments|} -> return_type +``` Omit the parentheses for cases where the method does not accept arguments, and omit the block for cases where a block is not accepted. @@ -215,12 +239,16 @@ 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: - * obj.respond_to?(symbol, include_all=false) -> true or false +``` +obj.respond_to?(symbol, include_all=false) -> true or false +``` Instead of: - * obj.respond_to?(symbol) -> true or false - * obj.respond_to?(symbol, include_all) -> true or false +``` +obj.respond_to?(symbol) -> true or false +obj.respond_to?(symbol, include_all) -> true or false +``` However, as shown above for Array#count, use separate lines if the behavior is different if the argument is omitted. @@ -228,15 +256,15 @@ behavior is different if the argument is omitted. Omit aliases from the call-seq, but mention them near the end (see below). -A +call-seq+ block should have {|x| ... }, not {|x| block } or {|x| code }. +A `call-seq` block should have {|x| ... }, not {|x| block } or {|x| code }. -A +call-seq+ output should: +A `call-seq` output should: -- 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+. +- 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`. -=== Synopsis +### Synopsis The synopsis comes next, and is a short description of what the method does and why you would want to use it. Ideally, this @@ -245,13 +273,15 @@ an entire paragraph. For Array#count, the synopsis is: - Returns a count of specified elements. +``` +Returns a count of specified elements. +``` This is great as it is short and descriptive. Avoid documenting too much in the synopsis, stick to the most important information for the benefit of the reader. -=== Details and Examples +### Details and Examples Most non-trivial methods benefit from examples, as well as details beyond what is given in the synopsis. In the details and examples @@ -261,10 +291,10 @@ section, focus on how to use the method properly, not on how the method handles improper arguments or corner cases. Not every behavior of a method requires an example. If the method -is documented to return +self+, you don't need to provide an example +is documented to return `self`, you don't need to provide an example showing the return value is the same as the receiver. If the method -is documented to return +nil+, you don't need to provide an example -showing that it returns +nil+. If the details mention that for a +is documented to return `nil`, you don't need to provide an example +showing that it returns `nil`. If the details mention that for a certain argument type, an empty array is returned, you don't need to provide an example for that. @@ -273,7 +303,7 @@ do not add an example if it provides the same information given in the synopsis or details. The purpose of examples is not to prove what the details are stating. -=== Argument Description (if necessary) +### Argument Description (if necessary) For methods that require arguments, if not obvious and not explicitly mentioned in the details or implicitly shown in the examples, you can @@ -289,9 +319,9 @@ 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::Markup@Labeled+Lists). -=== Corner Cases and Exceptions +### Corner Cases and Exceptions For corner cases of methods, such as atypical usage, briefly mention the behavior, but do not provide any examples. @@ -302,25 +332,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 +### Aliases Mention aliases in the form - Array#find_index is an alias for Array#index. +```c +// Array#find_index is an alias for Array#index. +``` -=== Related Methods (optional) +### 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 +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. -=== Methods Accepting Multiple Argument Types +### Methods Accepting Multiple Argument Types For methods that accept multiple argument types, in some cases it can be useful to document the different argument types separately. It's diff --git a/doc/contributing/making_changes_to_ruby.md b/doc/contributing/making_changes_to_ruby.md new file mode 100644 index 0000000000..6842ec2888 --- /dev/null +++ b/doc/contributing/making_changes_to_ruby.md @@ -0,0 +1,36 @@ +# Contributing a pull request + +## Code style + +Here are some general rules to follow when writing Ruby and C code for CRuby: + +* Do not change code unrelated to your pull request (including style fixes) +* Indent 4 spaces for C without tabs (tabs are two levels of indentation, equivalent to 8 spaces) +* Indent 2 spaces for Ruby without tabs +* ANSI C style for function declarations +* Follow C99 Standard +* PascalStyle for class/module names +* UNDERSCORE_SEPARATED_UPPER_CASE for other constants +* Abbreviations should be all upper case + +## Commit messages + +Use the following style for commit messages: + +* Use a succinct subject line +* Include reasoning behind the change in the commit message, focusing on why the change is being made +* Refer to issue (such as `Fixes [Bug #1234]` or `Implements [Feature #3456]`), or discussion on the mailing list (such as [ruby-core:12345]) + +## CI + +GitHub actions will run on each pull request. + +There is [a CI that runs on master](https://rubyci.org/). It has broad coverage of different systems and architectures, such as Solaris SPARC and macOS. + +# Contributing to standard libraries + +Everything in the [lib](https://github.com/ruby/ruby/tree/master/lib) directory is mirrored from a standalone repository into the Ruby repository. +If you'd like to make contributions to standard libraries, do so in the standalone repositories, and the +changes will be automatically mirrored into the Ruby repository. + +For example, CSV lives in [a separate repository](https://github.com/ruby/csv) and is mirrored into [Ruby](https://github.com/ruby/ruby/tree/master/lib/csv). diff --git a/doc/contributing/reporting_issues.md b/doc/contributing/reporting_issues.md new file mode 100644 index 0000000000..25516ffc6b --- /dev/null +++ b/doc/contributing/reporting_issues.md @@ -0,0 +1,91 @@ +# Reporting Issues +## Reporting security issues + +If you've found a security vulnerability, please follow +[these instructions](https://www.ruby-lang.org/en/security/). + +## Reporting bugs + +If you've encountered a bug in Ruby, please report it to the Redmine issue +tracker available at [bugs.ruby-lang.org](https://bugs.ruby-lang.org/), by +following these steps: + +* Check if anyone has already reported your issue by + searching [the Redmine issue tracker](https://bugs.ruby-lang.org/projects/ruby-master/issues). +* If you haven't already, + [sign up for an account](https://bugs.ruby-lang.org/account/register) on the + Redmine issue tracker. +* If you can't find a ticket addressing your issue, please [create a new issue](https://bugs.ruby-lang.org/projects/ruby-master/issues/new). You will need to fill in the subject, description and Ruby version. + + * Ensure the issue exists on Ruby master by trying to replicate your bug on + the head of master (see ["making changes to Ruby"](making_changes_to_ruby.md)). + * Write a concise subject and briefly describe your problem in the description section. If + your issue affects [a released version of Ruby](#label-Backport+requests), please say so. + * Fill in the Ruby version you're using when experiencing this issue + (the output of running `ruby -v`). + * Attach any logs or reproducible programs to provide additional information. + Any scripts should be as small as possible. +* If the ticket doesn't have any replies after 10 days, you can send a + reminder. +* Please reply to feedback requests. If a bug report doesn't get any feedback, + it'll eventually get rejected. + +### Reporting website issues + +If you're having an issue with the bug tracker or the mailing list, you can +contact the webmaster, Hiroshi SHIBATA (hsbt@ruby-lang.org). + +You can report issues with ruby-lang.org on the +[repo's issue tracker](https://github.com/ruby/www.ruby-lang.org/issues). + +## Requesting features + +If there's a new feature that you want to see added to Ruby, you will need to +write a proposal on [the Redmine issue tracker](https://bugs.ruby-lang.org/projects/ruby-master/issues/new). +When you open the issue, select `Feature` in the Tracker dropdown. + +When writing a proposal, be sure to check for previous discussions on the +topic and have a solid use case. You should also consider the potential +compatibility issues that this new feature might raise. Consider making +your feature into a gem, and if there are enough people who benefit from +your feature it could help persuade Ruby core. + +Here is a template you can use for a feature proposal: + +``` +[Abstract] + Briefly summarize your feature +[Background] + Describe current behavior +[Proposal] + Describe your feature in detail +[Use cases] + Give specific example uses of your feature +[Discussion] + Describe why this feature is necessary and better than using existing features +[See also] + Link to other related resources (such as implementations in other languages) +``` + +## Backport requests + +If a bug exists in a released version of Ruby, please report this in the issue. +Once this bug is fixed, the fix can be backported if deemed necessary. Only Ruby +committers can request backporting, and backporting is done by the backport manager. +New patch versions are released at the discretion of the backport manager. + +[Ruby versions](https://www.ruby-lang.org/en/downloads/) can be in one of three maintenance states: + +* Stable releases: backport any bug fixes +* Security maintenance: only backport security fixes +* End of life: no backports, please upgrade your Ruby version + +## Add context to existing issues + +There are several ways you can help with a bug that aren't directly +resolving it. These include: + +* Verifying or reproducing the existing issue and reporting it +* Adding more specific reproduction instructions +* Contributing a failing test as a patch (see ["making changes to Ruby"](making_changes_to_ruby.md)) +* Testing patches that others have submitted (see ["making changes to Ruby"](making_changes_to_ruby.md)) diff --git a/doc/contributing/testing_ruby.md b/doc/contributing/testing_ruby.md new file mode 100644 index 0000000000..c54b14c710 --- /dev/null +++ b/doc/contributing/testing_ruby.md @@ -0,0 +1,100 @@ +# Testing Ruby + +## Test suites + +There are several test suites in the Ruby codebase: + +We can run any of the make scripts [in parallel](building_ruby.md#label-Running+make+scripts+in+parallel) to speed them up. + +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: + + ``` + make btest + ``` + + To run it with logs, we can use: + + ``` + make btest OPTS=-v + ``` + + If we want to run the bootstrap test suite on Ruby (not Miniruby), we can use: + + ``` + make test + ``` + + To run it with logs, we can use: + + ``` + make test OPTS=-v + ``` + +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: + + ``` + make test-all + ``` + + We can run a specific test file in this suite using the `TESTS` environment variable, 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 + 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/" + ``` + + To run these specs with logs, we can use: + + ``` + make test-all TESTS=-v + ``` + + If we would like to run both the `test/` and `bootstraptest/` test suites, we can run + + ``` + 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: + + ``` + make test-spec + ``` + + To run a specific file, we can use `MSPECOPT` to specify the file: + + ``` + make test-spec MSPECOPT=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'" + ``` + + To run these specs with logs, we can use: + + ``` + make test-spec MSPECOPT=-Vfs + ``` + +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: + + ``` + make test-bundler + ``` diff --git a/doc/hacking.md b/doc/hacking.md deleted file mode 100644 index e441a40554..0000000000 --- a/doc/hacking.md +++ /dev/null @@ -1,104 +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 -``` - -## 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 behavior of the -language. - -``` shell -make test-spec -``` diff --git a/doc/make_cheatsheet.md b/doc/make_cheatsheet.md deleted file mode 100644 index f679f69cb3..0000000000 --- a/doc/make_cheatsheet.md +++ /dev/null @@ -1,124 +0,0 @@ -# How to use "configure" and "make" commands for Ruby - -This is for developers of Ruby. -If you are a user of Ruby, please see README.md. - -## In-place build - -``` -$ ./autogen.sh -$ ./configure --prefix=$PWD/local -$ make -$ make install -$ ./local/bin/ruby -e 'puts "Hello"' -Hello -``` - -## Out-of-place build - -``` -$ ./autogen.sh -$ mkdir ../ruby-build -$ cd ../ruby-build -$ ../ruby-src/configure --prefix=$PWD/local -$ make -$ make install -$ ./local/bin/ruby -e 'puts "Hello"' -Hello -``` - -## How to run the whole test suite - -``` -$ make check -``` - -It runs (about) four test suites: - -* `make test` (a test suite for the interpreter core) -* `make test-all` (for all builtin classes and libraries) -* `make test-spec` (a conformance test suite for Ruby implementations) -* `make test-bundler` (a test suite for the bundler examples) - -## How to run the test suite with log - -``` -$ make test OPTS=-v - -$ make test-all TESTS=-v - -$ make test-spec MSPECOPT=-Vfs -``` - -## How to run a part of the test suite - -### Runs a directory -``` -$ make test-all TESTS=test/rubygems -$ make test-all TESTS=rubygems -``` - -### Runs a file -``` -$ make test-all TESTS=test/ruby/test_foo.rb -$ make test-all TESTS=ruby/foo -``` - -### Runs a test whose name includes test_bar -``` -$ make test-all TESTS="test/ruby/test_foo.rb -n /test_bar/" -``` - -### Runs a file or directory with GNU make -``` -$ make test/ruby/test_foo.rb -$ make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/" -``` - -### Runs a ruby-spec directory -``` -$ make test-spec MSPECOPT=spec/ruby/core/foo -``` - -### Runs a ruby-spec file -``` -$ make test-spec MSPECOPT=spec/ruby/core/foo/bar_spec.rb -``` - -### Runs a ruby-spec file or directory with GNU make -``` -$ make spec/ruby/core/foo/bar_spec.rb -``` - -### Runs a bundler spec file -``` -$ make test-bundler BUNDLER_SPECS=commands/exec_spec.rb:58 -``` - -## 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 - -## How to benchmark - -see https://github.com/ruby/ruby/tree/master/benchmark#make-benchmark