[DOC] Improve formatting in Markdown files (#12322)
* Fix WASM bullet/code indentation * Use `console` code highlighting where appropriate … which handles the prefix `$` correctly. * Migrate feature proposal template to MarkDown * Set language on code blocks
This commit is contained in:
Alexander Momchilov
GitHub
parent
beff3e1272
commit
0ea5c13bc6
31
NEWS.md
31
NEWS.md
@ -259,21 +259,24 @@ details of the default gems or bundled gems.
|
||||
* Other keys now have spaces around `=>`: `'{"user" => 1}'`, while previously they didn't: `'{"user"=>1}'`
|
||||
|
||||
* Kernel#Float() now accepts a decimal string with decimal part omitted. [[Feature #20705]]
|
||||
```
|
||||
|
||||
```rb
|
||||
Float("1.") #=> 1.0 (previously, an ArgumentError was raised)
|
||||
Float("1.E-1") #=> 0.1 (previously, an ArgumentError was raised)
|
||||
```
|
||||
|
||||
* String#to_f now accepts a decimal string with decimal part omitted. [[Feature #20705]]
|
||||
Note that the result changes when an exponent is specified.
|
||||
```
|
||||
|
||||
```rb
|
||||
"1.".to_f #=> 1.0
|
||||
"1.E-1".to_f #=> 0.1 (previously, 1.0 was returned)
|
||||
```
|
||||
|
||||
* Object#singleton_method now returns methods in modules prepended to or included in the
|
||||
receiver's singleton class. [[Bug #20620]]
|
||||
```
|
||||
|
||||
```rb
|
||||
o = Object.new
|
||||
o.extend(Module.new{def a = 1})
|
||||
o.singleton_method(:a).call #=> 1
|
||||
@ -288,17 +291,17 @@ details of the default gems or bundled gems.
|
||||
* Net::HTTP
|
||||
|
||||
* Removed the following deprecated constants:
|
||||
`Net::HTTP::ProxyMod`
|
||||
`Net::NetPrivate::HTTPRequest`
|
||||
`Net::HTTPInformationCode`
|
||||
`Net::HTTPSuccessCode`
|
||||
`Net::HTTPRedirectionCode`
|
||||
`Net::HTTPRetriableCode`
|
||||
`Net::HTTPClientErrorCode`
|
||||
`Net::HTTPFatalErrorCode`
|
||||
`Net::HTTPServerErrorCode`
|
||||
`Net::HTTPResponseReceiver`
|
||||
`Net::HTTPResponceReceiver`
|
||||
* `Net::HTTP::ProxyMod`
|
||||
* `Net::NetPrivate::HTTPRequest`
|
||||
* `Net::HTTPInformationCode`
|
||||
* `Net::HTTPSuccessCode`
|
||||
* `Net::HTTPRedirectionCode`
|
||||
* `Net::HTTPRetriableCode`
|
||||
* `Net::HTTPClientErrorCode`
|
||||
* `Net::HTTPFatalErrorCode`
|
||||
* `Net::HTTPServerErrorCode`
|
||||
* `Net::HTTPResponseReceiver`
|
||||
* `Net::HTTPResponceReceiver`
|
||||
|
||||
These constants were deprecated from 2012.
|
||||
|
||||
|
||||
@ -40,11 +40,15 @@ https://www.ruby-lang.org/ja/downloads/
|
||||
|
||||
ミラーをGitHubに公開しています． 以下のコマンドでリポジトリを取得できます．
|
||||
|
||||
$ git clone https://github.com/ruby/ruby.git
|
||||
```console
|
||||
$ git clone https://github.com/ruby/ruby.git
|
||||
```
|
||||
|
||||
他のブランチの一覧は次のコマンドで見られます．
|
||||
|
||||
$ git ls-remote https://github.com/ruby/ruby.git
|
||||
```console
|
||||
$ git ls-remote https://github.com/ruby/ruby.git
|
||||
```
|
||||
|
||||
Rubyリポジトリの本来のmasterは https://git.ruby-lang.org/ruby.git にあります．
|
||||
コミッタはこちらを使います．
|
||||
|
||||
@ -27,6 +27,7 @@ benchmark-driver benchmark/*.yml
|
||||
See also:
|
||||
|
||||
```console
|
||||
benchmark-driver --help
|
||||
Usage: benchmark-driver [options] RUBY|YAML...
|
||||
-r, --runner TYPE Specify runner type: ips, time, memory, once, block (default: ips)
|
||||
-o, --output TYPE Specify output type: compare, simple, markdown, record, all (default: compare)
|
||||
|
||||
@ -741,7 +741,7 @@ end
|
||||
foo(42)
|
||||
```
|
||||
|
||||
```
|
||||
```console
|
||||
$ typeprof test.rb
|
||||
# Classes
|
||||
class Object
|
||||
|
||||
@ -552,7 +552,7 @@ Example: `title = json[:article][:title]`
|
||||
|
||||
If `json` is nil, it shows:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby test.rb
|
||||
test.rb:2:in `<main>': undefined method `[]' for nil:NilClass (NoMethodError)
|
||||
|
||||
@ -562,7 +562,7 @@ title = json[:article][:title]
|
||||
|
||||
If `json[:article]` returns nil, it shows:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby test.rb
|
||||
test.rb:2:in `<main>': undefined method `[]' for nil:NilClass (NoMethodError)
|
||||
|
||||
|
||||
@ -623,13 +623,13 @@ The following deprecated methods are removed.
|
||||
Psych and fiddle supported the static build with specific version of libyaml
|
||||
and libffi sources. You can build psych with libyaml-0.2.5 like this.
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ ./configure --with-libyaml-source-dir=/path/to/libyaml-0.2.5
|
||||
```
|
||||
|
||||
And you can build fiddle with libffi-3.4.4 like this.
|
||||
|
||||
```bash
|
||||
```console
|
||||
$ ./configure --with-libffi-source-dir=/path/to/libffi-3.4.4
|
||||
```
|
||||
|
||||
|
||||
@ -8,7 +8,7 @@ of the invoked Ruby program.
|
||||
The examples here use command-line option `-e`,
|
||||
which passes the Ruby code to be executed on the command line itself:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -e 'puts "Hello, World."'
|
||||
```
|
||||
|
||||
@ -18,7 +18,7 @@ The argument to option `-C` specifies a working directory
|
||||
for the invoked Ruby program;
|
||||
does not change the working directory for the current process:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ basename `pwd`
|
||||
ruby
|
||||
$ ruby -C lib -e 'puts File.basename(Dir.pwd)'
|
||||
@ -35,7 +35,7 @@ The argument to option `-I` specifies a directory
|
||||
to be added to the array in global variable `$LOAD_PATH`;
|
||||
the option may be given more than once:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ pushd /tmp
|
||||
$ ruby -e 'p $LOAD_PATH.size'
|
||||
8
|
||||
@ -54,7 +54,7 @@ The argument to option `-r` specifies a library to be required
|
||||
before executing the Ruby program;
|
||||
the option may be given more than once:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -e 'p defined?(JSON); p defined?(CSV)'
|
||||
nil
|
||||
nil
|
||||
@ -83,10 +83,10 @@ these digits are prefixed with digit `0` to form an octal value:
|
||||
|
||||
Examples:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -0 -e 'p $/'
|
||||
"\x00"
|
||||
ruby -00 -e 'p $/'
|
||||
$ ruby -00 -e 'p $/'
|
||||
""
|
||||
$ ruby -012 -e 'p $/'
|
||||
"\n"
|
||||
@ -109,7 +109,7 @@ these commonly write to `$stdout` or `$stderr`.
|
||||
The default value for `$DEBUG` is `false`;
|
||||
option `-d` (or `--debug`) sets it to `true`:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -e 'p $DEBUG'
|
||||
false
|
||||
$ ruby -d -e 'p $DEBUG'
|
||||
@ -140,7 +140,7 @@ by setting the initial value of global variable `$-W`:
|
||||
The value of `$-W`, in turn, determines which warning messages (if any)
|
||||
are to be printed to `$stdout` (see Kernel#warn):
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -W1 -e 'p $foo'
|
||||
nil
|
||||
$ ruby -W2 -e 'p $foo'
|
||||
@ -151,14 +151,15 @@ nil
|
||||
Ruby code may also define warnings for certain categories;
|
||||
these are the default settings for the defined categories:
|
||||
|
||||
```
|
||||
```ruby
|
||||
Warning[:experimental] # => true
|
||||
Warning[:deprecated] # => false
|
||||
Warning[:performance] # => false
|
||||
```
|
||||
|
||||
They may also be set:
|
||||
```
|
||||
|
||||
```ruby
|
||||
Warning[:experimental] = false
|
||||
Warning[:deprecated] = true
|
||||
Warning[:performance] = true
|
||||
@ -166,7 +167,7 @@ Warning[:performance] = true
|
||||
|
||||
You can suppress a category by prefixing `no-` to the category name:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby -W:no-experimental -e 'p IO::Buffer.new'
|
||||
#<IO::Buffer>
|
||||
```
|
||||
|
||||
@ -32,7 +32,7 @@
|
||||
the OS default place, typically using Homebrew on macOS, pass the
|
||||
`--with-opt-dir` (or `--with-gmp-dir` for gmp) option to `configure`.
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
configure --with-opt-dir=$(brew --prefix gmp):$(brew --prefix jemalloc)
|
||||
```
|
||||
|
||||
@ -43,7 +43,7 @@
|
||||
latter environment variable is not embedded and is only used when
|
||||
building the extension libraries.
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
export CONFIGURE_ARGS=""
|
||||
for ext in openssl readline libyaml zlib; do
|
||||
CONFIGURE_ARGS="${CONFIGURE_ARGS} --with-$ext-dir=$(brew --prefix $ext)"
|
||||
@ -71,7 +71,7 @@
|
||||
Download the latest tarball from [Download Ruby] page and extract
|
||||
it. Example for Ruby 3.0.2:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
tar -xzf ruby-3.0.2.tar.gz
|
||||
cd ruby-3.0.2
|
||||
```
|
||||
@ -80,20 +80,20 @@
|
||||
|
||||
Checkout the CRuby source code:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
git clone https://github.com/ruby/ruby.git
|
||||
cd ruby
|
||||
```
|
||||
|
||||
Generate the configure file:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
./autogen.sh
|
||||
```
|
||||
|
||||
2. Create a `build` directory separate from the source directory:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
mkdir build && cd build
|
||||
```
|
||||
|
||||
@ -102,13 +102,13 @@
|
||||
|
||||
3. We'll install Ruby in `~/.rubies/ruby-master`, so create the directory:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
mkdir ~/.rubies
|
||||
```
|
||||
|
||||
4. Run configure:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
../configure --prefix="${HOME}/.rubies/ruby-master"
|
||||
```
|
||||
|
||||
@ -117,7 +117,7 @@
|
||||
|
||||
5. Build Ruby:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
make
|
||||
```
|
||||
|
||||
@ -125,7 +125,7 @@
|
||||
|
||||
7. Install Ruby:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
make install
|
||||
```
|
||||
|
||||
@ -159,7 +159,7 @@ In GNU make[^caution-gmake-3] and BSD make implementations, to run a specific ma
|
||||
parallel, pass the flag `-j<number of processes>`. For instance, to run tests
|
||||
on 8 processes, use:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
make test-all -j8
|
||||
```
|
||||
|
||||
@ -169,7 +169,7 @@ 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
|
||||
```sh
|
||||
# On macOS with Fish shell:
|
||||
export MAKEFLAGS="--jobs "(sysctl -n hw.ncpu)
|
||||
|
||||
@ -193,7 +193,7 @@ 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
|
||||
```sh
|
||||
make miniruby
|
||||
```
|
||||
|
||||
@ -215,7 +215,7 @@ following make targets:
|
||||
You should configure Ruby without optimization and other flags that may
|
||||
interfere with debugging:
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
./configure --enable-debug-env optflags="-O0 -fno-omit-frame-pointer"
|
||||
```
|
||||
|
||||
@ -225,7 +225,7 @@ 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
|
||||
```sh
|
||||
./autogen.sh
|
||||
mkdir build && cd build
|
||||
../configure CC=clang-18 cflags="-fsanitize=address -fno-omit-frame-pointer -DUSE_MN_THREADS=0" # and any other options you might like
|
||||
@ -239,7 +239,7 @@ 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
|
||||
```sh
|
||||
RUBY_TEST_TIMEOUT_SCALE=5 SYNTAX_SUGGEST_TIMEOUT=600 make check
|
||||
```
|
||||
|
||||
@ -274,7 +274,7 @@ Please note, however, the following caveats!
|
||||
|
||||
You need to be able to use gcc (gcov) and lcov visualizer.
|
||||
|
||||
``` shell
|
||||
```sh
|
||||
./autogen.sh
|
||||
./configure --enable-gcov
|
||||
make
|
||||
|
||||
@ -95,7 +95,7 @@ involving new files `doc/*.rdoc`:
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
```c
|
||||
/*
|
||||
* call-seq:
|
||||
* each_byte {|byte| ... } -> self
|
||||
@ -173,12 +173,13 @@ Code that is a simple string should include the quote marks.
|
||||
Most often, the name of a class, module, or method
|
||||
is auto-linked:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
- Float.
|
||||
- Enumerable.
|
||||
- File.new
|
||||
- File#read.
|
||||
```
|
||||
|
||||
renders as:
|
||||
|
||||
> - Float.
|
||||
@ -189,7 +190,7 @@ renders as:
|
||||
In general, \RDoc's auto-linking should not be suppressed.
|
||||
For example, we should write just plain _Float_ (which is auto-linked):
|
||||
|
||||
```
|
||||
```rdoc
|
||||
Returns a Float.
|
||||
```
|
||||
|
||||
@ -200,13 +201,13 @@ which renders as:
|
||||
However, _do_ suppress auto-linking when the word in question
|
||||
does not refer to a Ruby entity (e.g., some uses of _Class_ or _English_):
|
||||
|
||||
```
|
||||
```rdoc
|
||||
\Class variables can be tricky.
|
||||
```
|
||||
|
||||
renders as:
|
||||
|
||||
> \\Class variables can be tricky.
|
||||
> Class variables can be tricky.
|
||||
|
||||
Also, _do_ suppress auto-linking when the word in question
|
||||
refers to the current document
|
||||
@ -216,7 +217,7 @@ In this case you may consider forcing the name to
|
||||
[monofont](rdoc-ref:RDoc::MarkupReference@Monofont),
|
||||
which suppresses auto-linking, and also emphasizes that the word is a class name:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
A +Float+ object represents ....
|
||||
```
|
||||
|
||||
@ -231,7 +232,7 @@ you might write simply the lowercase _array_.
|
||||
|
||||
Instead of:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
For an empty Array, ....
|
||||
```
|
||||
|
||||
@ -241,7 +242,7 @@ which renders as:
|
||||
|
||||
you might write:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
For an empty array, ....
|
||||
```
|
||||
|
||||
@ -398,13 +399,13 @@ the method accepts, so those need to be documented using \RDoc directive
|
||||
|
||||
For a singleton method, use the form:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
class_name.method_name(method_args) {|block_args| ... } -> return_type
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
* call-seq:
|
||||
* Hash.new(default_value = nil) -> new_hash
|
||||
* Hash.new {|hash, key| ... } -> new_hash
|
||||
@ -413,19 +414,20 @@ Example:
|
||||
For an instance method, use the form
|
||||
(omitting any prefix, just as RDoc does for a Ruby-coded method):
|
||||
|
||||
```
|
||||
```rdoc
|
||||
method_name(method_args) {|block_args| ... } -> return_type
|
||||
```
|
||||
|
||||
For example, in Array, use:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
* call-seq:
|
||||
* count -> integer
|
||||
* count(obj) -> integer
|
||||
* count {|element| ... } -> integer
|
||||
```
|
||||
|
||||
```
|
||||
```rdoc
|
||||
* call-seq:
|
||||
* <=> other -> -1, 0, 1, or nil
|
||||
```
|
||||
@ -433,7 +435,7 @@ For example, in Array, use:
|
||||
For a binary-operator style method (e.g., Array#&),
|
||||
cite `self` in the call-seq (not, e.g., `array` or `receiver`):
|
||||
|
||||
```
|
||||
```rdoc
|
||||
* call-seq:
|
||||
* self & other_array -> new_array
|
||||
```
|
||||
@ -449,7 +451,7 @@ Arguments:
|
||||
or an explicit argument, use a `call-seq` with optional arguments.
|
||||
For example, use:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
* call-seq:
|
||||
* respond_to?(symbol, include_all = false) -> true or false
|
||||
```
|
||||
@ -458,7 +460,7 @@ Arguments:
|
||||
use a `call-seq` with separate lines.
|
||||
For example, in Enumerable, use:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
* call-seq:
|
||||
* max -> element
|
||||
* max(n) -> array
|
||||
@ -472,7 +474,7 @@ Block:
|
||||
- If the method accepts a block, but returns an Enumerator when the block is omitted,
|
||||
the `call-seq` should show both forms:
|
||||
|
||||
```
|
||||
```rdoc
|
||||
* call-seq:
|
||||
* array.select {|element| ... } -> new_array
|
||||
* array.select -> new_enumerator
|
||||
@ -505,9 +507,7 @@ 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
|
||||
@ -550,7 +550,7 @@ but return a new Enumerator if the block is not given;
|
||||
in that case, do not provide an example,
|
||||
but do state the fact (with the auto-linking uppercase Enumerator):
|
||||
|
||||
```
|
||||
```rdoc
|
||||
* With no block given, returns a new Enumerator.
|
||||
```
|
||||
|
||||
|
||||
@ -14,7 +14,7 @@ You can find the list of maintainers [here](https://docs.ruby-lang.org/en/master
|
||||
|
||||
First, install its dependencies using:
|
||||
|
||||
```
|
||||
```shell
|
||||
bundle install
|
||||
```
|
||||
|
||||
@ -22,7 +22,7 @@ bundle install
|
||||
|
||||
If the library has a `/ext` directory, it has C files that you need to compile with:
|
||||
|
||||
```
|
||||
```shell
|
||||
bundle exec rake compile
|
||||
```
|
||||
|
||||
@ -32,18 +32,18 @@ All standard libraries use [test-unit](https://github.com/test-unit/test-unit) a
|
||||
|
||||
To run all tests:
|
||||
|
||||
```
|
||||
```shell
|
||||
bundle exec rake test
|
||||
```
|
||||
|
||||
To run a single test file:
|
||||
|
||||
```
|
||||
```shell
|
||||
bundle exec rake test TEST="test/test_foo.rb"
|
||||
```
|
||||
|
||||
To run a single test case:
|
||||
|
||||
```
|
||||
```shell
|
||||
bundle exec rake test TEST="test/test_foo.rb" TESTOPS="--name=/test_mytest/"
|
||||
```
|
||||
|
||||
@ -52,19 +52,30 @@ 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)
|
||||
```markdown
|
||||
# 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
|
||||
|
||||
@ -10,38 +10,38 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
```sh
|
||||
make btest
|
||||
```
|
||||
|
||||
To run it with logs, we can use:
|
||||
|
||||
```
|
||||
```sh
|
||||
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"
|
||||
```sh
|
||||
make btest BTESTS="../bootstraptest/test_fork.rb ../bootstraptest/test_gc.rb"
|
||||
make btest BTESTS="--sets=fork,gc"
|
||||
```
|
||||
|
||||
If we want to run the bootstrap test suite on Ruby (not Miniruby), we can use:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test
|
||||
```
|
||||
|
||||
To run it with logs, we can use:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test OPTS=-v
|
||||
```
|
||||
|
||||
To run a file or directory with GNU make, we can use:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test/ruby/test_foo.rb
|
||||
make test/ruby/test_foo.rb TESTOPTS="-n /test_bar/"
|
||||
```
|
||||
@ -50,44 +50,44 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
|
||||
|
||||
This is a more comprehensive test suite that runs on Ruby. We can run it with:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test-all
|
||||
```
|
||||
|
||||
We can run a specific test directory in this suite using the `TESTS` option, for example:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test-all TESTS=test/rubygems
|
||||
```
|
||||
|
||||
We can run a specific test file in this suite by also using the `TESTS` option, for example:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test-all TESTS=test/ruby/test_array.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"
|
||||
```
|
||||
|
||||
To run these specs with logs, we can use:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test-all TESTS=-v
|
||||
```
|
||||
|
||||
We can display the help of the `TESTS` option:
|
||||
|
||||
```
|
||||
```sh
|
||||
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
|
||||
|
||||
```
|
||||
```sh
|
||||
make check
|
||||
```
|
||||
|
||||
@ -95,37 +95,37 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
```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:
|
||||
|
||||
```
|
||||
```sh
|
||||
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:
|
||||
|
||||
```
|
||||
```sh
|
||||
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:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test-spec SPECOPTS=-Vfs
|
||||
```
|
||||
|
||||
To run a ruby-spec file or directory with GNU make, we can use
|
||||
|
||||
```
|
||||
```sh
|
||||
make spec/ruby/core/foo/bar_spec.rb
|
||||
```
|
||||
|
||||
@ -133,13 +133,13 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test-bundler
|
||||
```
|
||||
|
||||
To run a specific bundler spec file, we can use `BUNDLER_SPECS` as follows:
|
||||
|
||||
```
|
||||
```sh
|
||||
make test-bundler BUNDLER_SPECS=commands/exec_spec.rb
|
||||
```
|
||||
|
||||
@ -149,7 +149,7 @@ We can run any of the make scripts [in parallel](building_ruby.md#label-Running+
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
```sh
|
||||
DFLTCC=0 make check
|
||||
```
|
||||
|
||||
|
||||
@ -19,7 +19,8 @@ See the Snapshots section of the [Ruby website](https://www.ruby-lang.org/en/dow
|
||||
This can be useful if the nightly tarball does not have all changes yet.
|
||||
|
||||
At Ruby source tree cloned using git:
|
||||
```sh-session
|
||||
|
||||
```console
|
||||
$ ./autogen.sh
|
||||
$ ./configure -C
|
||||
$ make
|
||||
|
||||
@ -9,7 +9,7 @@ and may need to be handled.
|
||||
Code throughout the Ruby core, Ruby standard library, and Ruby gems generates exceptions
|
||||
in certain circumstances:
|
||||
|
||||
```
|
||||
```rb
|
||||
File.open('nope.txt') # Raises Errno::ENOENT: "No such file or directory"
|
||||
```
|
||||
|
||||
@ -24,7 +24,7 @@ If an exception not _rescued_
|
||||
execution transfers to code in the Ruby interpreter
|
||||
that prints a message and exits the program (or thread):
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby -e "raise"
|
||||
-e:1:in `<main>': unhandled exception
|
||||
```
|
||||
@ -38,7 +38,7 @@ and may prevent the program from exiting.
|
||||
|
||||
A simple example:
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
raise 'Boom!' # Raises an exception, transfers control.
|
||||
puts 'Will not get here.'
|
||||
@ -94,7 +94,7 @@ The rescue clause rescues both the specified class
|
||||
(or StandardError if none given) or any of its subclasses;
|
||||
see [Built-In Exception Class Hierarchy](rdoc-ref:Exception@Built-In+Exception+Class+Hierarchy).
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
1 / 0 # Raises ZeroDivisionError, a subclass of StandardError.
|
||||
rescue
|
||||
@ -113,7 +113,7 @@ only that class (or one of its subclasses) is rescued;
|
||||
this example exits with a ZeroDivisionError,
|
||||
which was not rescued because it is not ArgumentError or one of its subclasses:
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
1 / 0
|
||||
rescue ArgumentError
|
||||
@ -125,7 +125,7 @@ A `rescue` statement may specify multiple classes,
|
||||
which means that its code rescues an exception
|
||||
of any of the given classes (or their subclasses):
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
1 / 0
|
||||
rescue FloatDomainError, ZeroDivisionError
|
||||
@ -139,7 +139,7 @@ An exception handler may contain multiple rescue clauses;
|
||||
in that case, the first clause that rescues the exception does so,
|
||||
and those before and after are ignored:
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
Dir.open('nosuch')
|
||||
rescue Errno::ENOTDIR
|
||||
@ -161,7 +161,7 @@ A `rescue` statement may specify a variable
|
||||
whose value becomes the rescued exception
|
||||
(an instance of Exception or one of its subclasses:
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
1 / 0
|
||||
rescue => x
|
||||
@ -188,7 +188,7 @@ there:
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
1 / 0
|
||||
rescue
|
||||
@ -212,7 +212,7 @@ elsewhere, the method returns `nil`.
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
raise('Boom 0')
|
||||
rescue => x0
|
||||
@ -246,7 +246,7 @@ The `else` clause:
|
||||
- Contains code that is to be executed if no exception is raised in the begin clause.
|
||||
- Ends with the first following `ensure` or `end` statement.
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
puts 'Begin.'
|
||||
rescue
|
||||
@ -273,7 +273,7 @@ The ensure clause:
|
||||
and regardless of whether a raised exception is handled.
|
||||
- Ends with the first following `end` statement.
|
||||
|
||||
```
|
||||
```rb
|
||||
def foo(boom: false)
|
||||
puts 'Begin.'
|
||||
raise 'Boom!' if boom
|
||||
@ -314,7 +314,7 @@ An exception handler may also be implemented as:
|
||||
|
||||
- A method body:
|
||||
|
||||
```
|
||||
```rb
|
||||
def foo(boom: false) # Serves as beginning of exception handler.
|
||||
puts 'Begin.'
|
||||
raise 'Boom!' if boom
|
||||
@ -327,7 +327,7 @@ An exception handler may also be implemented as:
|
||||
|
||||
- A block:
|
||||
|
||||
```
|
||||
```rb
|
||||
Dir.chdir('.') do |dir| # Serves as beginning of exception handler.
|
||||
raise 'Boom!'
|
||||
rescue
|
||||
@ -349,7 +349,7 @@ a rescuing clause:
|
||||
- Calls method `raise` with no argument,
|
||||
which raises the rescued exception:
|
||||
|
||||
```
|
||||
```rb
|
||||
begin
|
||||
1 / 0
|
||||
rescue ZeroDivisionError
|
||||
@ -374,7 +374,7 @@ for example, if it must access a possibly-volatile resource
|
||||
it can be useful to try the access more than once
|
||||
(in the hope that it may become available):
|
||||
|
||||
```
|
||||
```rb
|
||||
retries = 0
|
||||
begin
|
||||
puts "Try ##{retries}."
|
||||
@ -419,7 +419,7 @@ Each should be a subclass of one of the built-in exception classes
|
||||
(commonly StandardError or RuntimeError);
|
||||
see [Built-In Exception Class Hierarchy](rdoc-ref:Exception@Built-In+Exception+Class+Hierarchy).
|
||||
|
||||
```
|
||||
```rb
|
||||
class MyException < StandardError; end
|
||||
```
|
||||
|
||||
|
||||
14
doc/fiber.md
14
doc/fiber.md
@ -6,7 +6,7 @@ Fibers provide a mechanism for cooperative concurrency.
|
||||
|
||||
Fibers execute a user-provided block. During the execution, the block may call `Fiber.yield` or `Fiber.transfer` to switch to another fiber. `Fiber#resume` is used to continue execution from the point where `Fiber.yield` was called.
|
||||
|
||||
``` ruby
|
||||
```rb
|
||||
#!/usr/bin/env ruby
|
||||
|
||||
puts "1: Start program."
|
||||
@ -38,13 +38,13 @@ instrumentation.
|
||||
|
||||
To set the scheduler for the current thread:
|
||||
|
||||
``` ruby
|
||||
```rb
|
||||
Fiber.set_scheduler(MyScheduler.new)
|
||||
```
|
||||
|
||||
When the thread exits, there is an implicit call to `set_scheduler`:
|
||||
|
||||
``` ruby
|
||||
```rb
|
||||
Fiber.set_scheduler(nil)
|
||||
```
|
||||
|
||||
@ -60,7 +60,7 @@ no changes.
|
||||
|
||||
This is the interface you need to implement.
|
||||
|
||||
``` ruby
|
||||
```rb
|
||||
class Scheduler
|
||||
# Wait for the specified process ID to exit.
|
||||
# This hook is optional.
|
||||
@ -166,7 +166,7 @@ program.
|
||||
|
||||
Fibers can be used to create non-blocking execution contexts.
|
||||
|
||||
``` ruby
|
||||
```rb
|
||||
Fiber.new do
|
||||
puts Fiber.current.blocking? # false
|
||||
|
||||
@ -184,7 +184,7 @@ end.resume
|
||||
We also introduce a new method which simplifies the creation of these
|
||||
non-blocking fibers:
|
||||
|
||||
``` ruby
|
||||
```rb
|
||||
Fiber.schedule do
|
||||
puts Fiber.current.blocking? # false
|
||||
end
|
||||
@ -196,7 +196,7 @@ fibers.
|
||||
|
||||
You can also create blocking execution contexts:
|
||||
|
||||
``` ruby
|
||||
```rb
|
||||
Fiber.new(blocking: true) do
|
||||
# Won't use the scheduler:
|
||||
sleep(n)
|
||||
|
||||
@ -259,7 +259,6 @@ r.take # Receive from r's outgoing port
|
||||
The last example shows the following ractor network.
|
||||
|
||||
```
|
||||
|
||||
+------+ +---+
|
||||
* main |------> * r *---+
|
||||
+------+ +---+ |
|
||||
@ -875,17 +874,17 @@ p Ractor.select(*rs, Ractor.current) #=> [:receive, "r0r10r9r8r7r6r5r4r3r2r1"]
|
||||
r.send "e0"
|
||||
p Ractor.select(*rs, Ractor.current)
|
||||
#=>
|
||||
#<Thread:0x000056262de28bd8 run> terminated with exception (report_on_exception is true):
|
||||
Traceback (most recent call last):
|
||||
2: from /home/ko1/src/ruby/trunk/test.rb:7:in `block (2 levels) in <main>'
|
||||
1: from /home/ko1/src/ruby/trunk/test.rb:7:in `loop'
|
||||
/home/ko1/src/ruby/trunk/test.rb:9:in `block (3 levels) in <main>': unhandled exception
|
||||
Traceback (most recent call last):
|
||||
2: from /home/ko1/src/ruby/trunk/test.rb:7:in `block (2 levels) in <main>'
|
||||
1: from /home/ko1/src/ruby/trunk/test.rb:7:in `loop'
|
||||
/home/ko1/src/ruby/trunk/test.rb:9:in `block (3 levels) in <main>': unhandled exception
|
||||
1: from /home/ko1/src/ruby/trunk/test.rb:21:in `<main>'
|
||||
<internal:ractor>:69:in `select': thrown by remote Ractor. (Ractor::RemoteError)
|
||||
# <Thread:0x000056262de28bd8 run> terminated with exception (report_on_exception is true):
|
||||
# Traceback (most recent call last):
|
||||
# 2: from /home/ko1/src/ruby/trunk/test.rb:7:in `block (2 levels) in <main>'
|
||||
# 1: from /home/ko1/src/ruby/trunk/test.rb:7:in `loop'
|
||||
# /home/ko1/src/ruby/trunk/test.rb:9:in `block (3 levels) in <main>': unhandled exception
|
||||
# Traceback (most recent call last):
|
||||
# 2: from /home/ko1/src/ruby/trunk/test.rb:7:in `block (2 levels) in <main>'
|
||||
# 1: from /home/ko1/src/ruby/trunk/test.rb:7:in `loop'
|
||||
# /home/ko1/src/ruby/trunk/test.rb:9:in `block (3 levels) in <main>': unhandled exception
|
||||
# 1: from /home/ko1/src/ruby/trunk/test.rb:21:in `<main>'
|
||||
# <internal:ractor>:69:in `select': thrown by remote Ractor. (Ractor::RemoteError)
|
||||
```
|
||||
|
||||
```ruby
|
||||
|
||||
@ -5,7 +5,7 @@ see {Option --dump}[options_md.html#label--dump-3A+Dump+Items].
|
||||
|
||||
For the examples here, we use this program:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ cat t.rb
|
||||
puts 'Foo'
|
||||
```
|
||||
@ -26,7 +26,7 @@ The supported dump items:
|
||||
- `parsetree`: {Abstract syntax tree}[https://en.wikipedia.org/wiki/Abstract_syntax_tree]
|
||||
(AST):
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby --dump=parsetree t.rb
|
||||
###########################################################
|
||||
## Do NOT use this node dump for any purpose other than ##
|
||||
@ -52,7 +52,7 @@ The supported dump items:
|
||||
|
||||
- `parsetree_with_comment`: AST with comments:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby --dump=parsetree_with_comment t.rb
|
||||
###########################################################
|
||||
## Do NOT use this node dump for any purpose other than ##
|
||||
@ -89,7 +89,7 @@ The supported dump items:
|
||||
|
||||
- `yydebug`: Debugging information from yacc parser generator:
|
||||
|
||||
```sh
|
||||
```
|
||||
$ ruby --dump=yydebug t.rb
|
||||
Starting parse
|
||||
Entering state 0
|
||||
|
||||
@ -5,13 +5,13 @@
|
||||
Some examples here use command-line option `-e`,
|
||||
which passes the Ruby code to be executed on the command line itself:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -e 'puts "Hello, World."'
|
||||
```
|
||||
|
||||
Some examples here assume that file `desiderata.txt` exists:
|
||||
|
||||
```
|
||||
```console
|
||||
$ cat desiderata.txt
|
||||
Go placidly amid the noise and the haste,
|
||||
and remember what peace there may be in silence.
|
||||
@ -44,7 +44,7 @@ argument values:
|
||||
|
||||
Examples:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -0 -e 'p $/'
|
||||
"\x00"
|
||||
ruby -00 -e 'p $/'
|
||||
@ -77,7 +77,7 @@ See also:
|
||||
Option `-a`, when given with either of options `-n` or `-p`,
|
||||
splits the string at `$_` into an array of strings at `$F`:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -an -e 'p $F' desiderata.txt
|
||||
["Go", "placidly", "amid", "the", "noise", "and", "the", "haste,"]
|
||||
["and", "remember", "what", "peace", "there", "may", "be", "in", "silence."]
|
||||
@ -107,7 +107,7 @@ See also:
|
||||
Option `-c` specifies that the specified Ruby program
|
||||
should be checked for syntax, but not actually executed:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby -e 'puts "Foo"'
|
||||
Foo
|
||||
$ ruby -c -e 'puts "Foo"'
|
||||
@ -120,7 +120,7 @@ The argument to option `-C` specifies a working directory
|
||||
for the invoked Ruby program;
|
||||
does not change the working directory for the current process:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ basename `pwd`
|
||||
ruby
|
||||
$ ruby -C lib -e 'puts File.basename(Dir.pwd)'
|
||||
@ -140,7 +140,7 @@ these commonly write to `$stdout` or `$stderr`.
|
||||
The default value for `$DEBUG` is `false`;
|
||||
option `-d` sets it to `true`:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -e 'p $DEBUG'
|
||||
false
|
||||
$ ruby -d -e 'p $DEBUG'
|
||||
@ -154,7 +154,7 @@ Option `--debug` is an alias for option `-d`.
|
||||
Option `-e` requires an argument, which is Ruby code to be executed;
|
||||
the option may be given more than once:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby -e 'puts "Foo"' -e 'puts "Bar"'
|
||||
Foo
|
||||
Bar
|
||||
@ -170,7 +170,7 @@ but should not include arguments (which, if given, are ignored).
|
||||
Option `-E` requires an argument, which specifies either the default external encoding,
|
||||
or both the default external and internal encodings for the invoked Ruby program:
|
||||
|
||||
```
|
||||
```console
|
||||
# No option -E.
|
||||
$ ruby -e 'p [Encoding::default_external, Encoding::default_internal]'
|
||||
[#<Encoding:UTF-8>, nil]
|
||||
@ -198,7 +198,7 @@ Option `--encoding` is an alias for option `-E`.
|
||||
Option `-F`, when given with option `-a`,
|
||||
specifies that its argument is to be the input field separator to be used for splitting:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -an -Fs -e 'p $F' desiderata.txt
|
||||
["Go placidly amid the noi", "e and the ha", "te,\n"]
|
||||
["and remember what peace there may be in ", "ilence.\n"]
|
||||
@ -208,7 +208,7 @@ $ ruby -an -Fs -e 'p $F' desiderata.txt
|
||||
|
||||
The argument may be a regular expression:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby -an -F'[.,]\s*' -e 'p $F' desiderata.txt
|
||||
["Go placidly amid the noise and the haste"]
|
||||
["and remember what peace there may be in silence"]
|
||||
@ -247,7 +247,7 @@ For a longer help message, use option `--help`.
|
||||
Option `-i` sets the \ARGF in-place mode for the invoked Ruby program;
|
||||
see ARGF#inplace_mode=:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby -e 'p ARGF.inplace_mode'
|
||||
nil
|
||||
$ ruby -i -e 'p ARGF.inplace_mode'
|
||||
@ -262,7 +262,7 @@ The argument to option `-I` specifies a directory
|
||||
to be added to the array in global variable `$LOAD_PATH`;
|
||||
the option may be given more than once:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ pushd /tmp
|
||||
$ ruby -e 'p $LOAD_PATH.size'
|
||||
8
|
||||
@ -287,7 +287,7 @@ modifies line-ending processing by:
|
||||
|
||||
Without option `-l` (unchopped):
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -n -e 'p $_' desiderata.txt
|
||||
"Go placidly amid the noise and the haste,\n"
|
||||
"and remember what peace there may be in silence.\n"
|
||||
@ -297,7 +297,7 @@ $ ruby -n -e 'p $_' desiderata.txt
|
||||
|
||||
With option `-l' (chopped):
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -ln -e 'p $_' desiderata.txt
|
||||
"Go placidly amid the noise and the haste,"
|
||||
"and remember what peace there may be in silence."
|
||||
@ -320,9 +320,9 @@ See also:
|
||||
|
||||
### `-n`: Run Program in `gets` Loop
|
||||
|
||||
Option `-n` runs your program in a Kernel#gets loop:
|
||||
Option `-n` runs your program in a `Kernel#gets` loop:
|
||||
|
||||
```
|
||||
```ruby
|
||||
while gets
|
||||
# Your Ruby code.
|
||||
end
|
||||
@ -331,7 +331,7 @@ end
|
||||
Note that `gets` reads the next line and sets global variable `$_`
|
||||
to the last read line:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -n -e 'puts $_' desiderata.txt
|
||||
Go placidly amid the noise and the haste,
|
||||
and remember what peace there may be in silence.
|
||||
@ -356,7 +356,7 @@ See also:
|
||||
|
||||
Option `-p` is like option `-n`, but also prints each line:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -p -e 'puts $_.size' desiderata.txt
|
||||
42
|
||||
Go placidly amid the noise and the haste,
|
||||
@ -387,7 +387,7 @@ The argument to option `-r` specifies a library to be required
|
||||
before executing the Ruby program;
|
||||
the option may be given more than once:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -e 'p defined?(JSON); p defined?(CSV)'
|
||||
nil
|
||||
nil
|
||||
@ -413,7 +413,7 @@ in the invoked Ruby program:
|
||||
|
||||
More than one custom option may be given:
|
||||
|
||||
```
|
||||
```console
|
||||
$ cat t.rb
|
||||
p [$foo, $bar]
|
||||
$ ruby t.rb
|
||||
@ -439,7 +439,7 @@ the program is executed in the shell's current working directory
|
||||
|
||||
This example uses adds path `'tmp/'` to the `PATH` environment variable:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ export PATH=/tmp:$PATH
|
||||
$ echo "puts File.basename(Dir.pwd)" > /tmp/t.rb
|
||||
$ ruby -S t.rb
|
||||
@ -450,7 +450,7 @@ ruby
|
||||
|
||||
Options `-v` prints the Ruby version and sets global variable `$VERBOSE`:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby -e 'p $VERBOSE'
|
||||
false
|
||||
$ ruby -v -e 'p $VERBOSE'
|
||||
@ -482,7 +482,7 @@ by setting the initial value of global variable `$-W`:
|
||||
The value of `$-W`, in turn, determines which warning messages (if any)
|
||||
are to be printed to `$stdout` (see Kernel#warn):
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -W1 -e 'p $foo'
|
||||
nil
|
||||
$ ruby -W2 -e 'p $foo'
|
||||
@ -493,14 +493,15 @@ nil
|
||||
Ruby code may also define warnings for certain categories;
|
||||
these are the default settings for the defined categories:
|
||||
|
||||
```
|
||||
```rb
|
||||
Warning[:experimental] # => true
|
||||
Warning[:deprecated] # => false
|
||||
Warning[:performance] # => false
|
||||
```
|
||||
|
||||
They may also be set:
|
||||
```
|
||||
|
||||
```rb
|
||||
Warning[:experimental] = false
|
||||
Warning[:deprecated] = true
|
||||
Warning[:performance] = true
|
||||
@ -508,7 +509,7 @@ Warning[:performance] = true
|
||||
|
||||
You can suppress a category by prefixing `no-` to the category name:
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby -W:no-experimental -e 'p IO::Buffer.new'
|
||||
#<IO::Buffer>
|
||||
```
|
||||
@ -529,7 +530,7 @@ The ruby code:
|
||||
|
||||
Example:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ cat t.txt
|
||||
Leading garbage.
|
||||
#!ruby
|
||||
@ -545,7 +546,7 @@ The optional argument specifies the directory where the text file
|
||||
is to be found;
|
||||
the Ruby code is executed in that directory:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ cp t.txt /tmp/
|
||||
$ ruby -x/tmp t.txt
|
||||
tmp
|
||||
@ -567,7 +568,7 @@ See Thread::Backtrace.limit.
|
||||
|
||||
Option `--copyright` prints a copyright message:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby --copyright
|
||||
ruby - Copyright (C) 1993-2024 Yukihiro Matsumoto
|
||||
```
|
||||
@ -642,7 +643,7 @@ sets the default external encoding for the invoked Ruby program;
|
||||
for values of +encoding+,
|
||||
see {Encoding: Names and Aliases}[rdoc-ref:encodings.rdoc@Names+and+Aliases].
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -e 'puts Encoding::default_external'
|
||||
UTF-8
|
||||
$ ruby --external-encoding=cesu-8 -e 'puts Encoding::default_external'
|
||||
@ -664,7 +665,7 @@ sets the default internal encoding for the invoked Ruby program;
|
||||
for values of +encoding+,
|
||||
see {Encoding: Names and Aliases}[rdoc-ref:encodings.rdoc@Names+and+Aliases].
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ ruby -e 'puts Encoding::default_internal.nil?'
|
||||
true
|
||||
$ ruby --internal-encoding=cesu-8 -e 'puts Encoding::default_internal'
|
||||
|
||||
@ -16,7 +16,7 @@ editor.
|
||||
|
||||
Ruby core development can be done either in Windows `cmd` like:
|
||||
|
||||
```
|
||||
```batch
|
||||
ridk enable ucrt64
|
||||
|
||||
pacman -S --needed %MINGW_PACKAGE_PREFIX%-openssl %MINGW_PACKAGE_PREFIX%-libyaml %MINGW_PACKAGE_PREFIX%-libffi
|
||||
@ -34,7 +34,7 @@ make
|
||||
|
||||
or in MSYS2 `bash` like:
|
||||
|
||||
```
|
||||
```bash
|
||||
ridk enable ucrt64
|
||||
bash
|
||||
|
||||
@ -85,14 +85,14 @@ make
|
||||
|
||||
You can use [scoop](https://scoop.sh/) to install them like:
|
||||
|
||||
```
|
||||
```batch
|
||||
scoop install git sed ruby
|
||||
```
|
||||
|
||||
5. You need to install required libraries using [vcpkg](https://vcpkg.io/) on
|
||||
directory of ruby repository like:
|
||||
|
||||
```
|
||||
```batch
|
||||
vcpkg --triplet x64-windows install
|
||||
```
|
||||
|
||||
@ -146,7 +146,7 @@ make
|
||||
install directory: C:\usr\local
|
||||
```
|
||||
|
||||
```
|
||||
```batch
|
||||
C:
|
||||
cd \ruby
|
||||
win32\configure --prefix=/usr/local
|
||||
@ -163,7 +163,7 @@ make
|
||||
install directory: C:\usr\local
|
||||
```
|
||||
|
||||
```
|
||||
```batch
|
||||
C:
|
||||
cd \ruby
|
||||
mkdir mswin32
|
||||
@ -182,7 +182,7 @@ make
|
||||
install directory: C:\usr\local
|
||||
```
|
||||
|
||||
```
|
||||
```batch
|
||||
D:
|
||||
cd D:\build\ruby
|
||||
C:\src\ruby\win32\configure --prefix=/usr/local
|
||||
@ -199,7 +199,7 @@ make
|
||||
install directory: C:\usr\local
|
||||
```
|
||||
|
||||
```
|
||||
```batch
|
||||
C:
|
||||
cd \ruby
|
||||
win32\configure --prefix=/usr/local --target=x64-mswin64
|
||||
@ -224,7 +224,7 @@ Ruby uses [vcpkg](https://vcpkg.io/) to manage dependencies on mswin platform.
|
||||
|
||||
You can update and install it under the build directory like:
|
||||
|
||||
```
|
||||
```batch
|
||||
nmake update-vcpkg # Update baseline version of vcpkg
|
||||
nmake install-vcpkg # Install vcpkg from build directory
|
||||
```
|
||||
|
||||
@ -36,7 +36,7 @@ If you wish to learn more about the approach taken, here are some conference tal
|
||||
|
||||
To cite YJIT in your publications, please cite the MPLR 2023 paper:
|
||||
|
||||
```
|
||||
```BibTeX
|
||||
@inproceedings{yjit_mplr_2023,
|
||||
author = {Chevalier-Boisvert, Maxime and Kokubun, Takashi and Gibbs, Noah and Wu, Si Xing (Alan) and Patterson, Aaron and Issroff, Jemma},
|
||||
title = {Evaluating YJIT’s Performance in a Production Context: A Pragmatic Approach},
|
||||
@ -440,7 +440,7 @@ instructions below, but there are a few caveats listed further down.
|
||||
|
||||
First, install Rosetta:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ softwareupdate --install-rosetta
|
||||
```
|
||||
|
||||
@ -448,13 +448,13 @@ Now any command can be run with Rosetta via the `arch` command line tool.
|
||||
|
||||
Then you can start your shell in an x86 environment:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ arch -x86_64 zsh
|
||||
```
|
||||
|
||||
You can double check your current architecture via the `arch` command:
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ arch -x86_64 zsh
|
||||
$ arch
|
||||
i386
|
||||
@ -462,7 +462,7 @@ i386
|
||||
|
||||
You may need to set the default target for `rustc` to x86-64, e.g.
|
||||
|
||||
```sh
|
||||
```console
|
||||
$ rustup default stable-x86_64-apple-darwin
|
||||
```
|
||||
|
||||
|
||||
@ -13,50 +13,58 @@
|
||||
### Steps
|
||||
|
||||
1. Download a prebuilt WASI SDK package from [WASI SDK release page](https://github.com/WebAssembly/wasi-sdk/releases).
|
||||
|
||||
2. Set `WASI_SDK_PATH` environment variable to the root directory of the WASI SDK package.
|
||||
```console
|
||||
$ export WASI_SDK_PATH=/path/to/wasi-sdk-X.Y
|
||||
```
|
||||
|
||||
```console
|
||||
$ export WASI_SDK_PATH=/path/to/wasi-sdk-X.Y
|
||||
```
|
||||
|
||||
3. Download a prebuilt binaryen from [Binaryen release page](https://github.com/WebAssembly/binaryen/releases)
|
||||
|
||||
4. Set PATH environment variable to lookup binaryen tools
|
||||
```console
|
||||
$ export PATH=path/to/binaryen:$PATH
|
||||
```
|
||||
5. Download the latest `config.guess` with WASI support, and run `./autogen.sh` to generate configure when you
|
||||
are building from the source checked out from Git repository
|
||||
```console
|
||||
$ ruby tool/downloader.rb -d tool -e gnu config.guess config.sub
|
||||
$ ./autogen.sh
|
||||
```
|
||||
|
||||
```console
|
||||
$ export PATH=path/to/binaryen:$PATH
|
||||
```
|
||||
|
||||
5. Download the latest `config.guess` with WASI support, and run `./autogen.sh` to generate configure when you are building from the source checked out from Git repository
|
||||
|
||||
```console
|
||||
$ ruby tool/downloader.rb -d tool -e gnu config.guess config.sub
|
||||
$ ./autogen.sh
|
||||
```
|
||||
|
||||
6. Configure
|
||||
- You can select which extensions you want to build.
|
||||
- If you got `Out of bounds memory access` while running the produced ruby, you may need to increase the maximum size of stack.
|
||||
```console
|
||||
$ ./configure LDFLAGS="-Xlinker -zstack-size=16777216" \
|
||||
--host wasm32-unknown-wasi \
|
||||
--with-destdir=./ruby-wasm32-wasi \
|
||||
--with-static-linked-ext \
|
||||
--with-ext=ripper,monitor
|
||||
```
|
||||
- You can select which extensions you want to build.
|
||||
- If you got `Out of bounds memory access` while running the produced ruby, you may need to increase the maximum size of stack.
|
||||
|
||||
```console
|
||||
$ ./configure LDFLAGS="-Xlinker -zstack-size=16777216" \
|
||||
--host wasm32-unknown-wasi \
|
||||
--with-destdir=./ruby-wasm32-wasi \
|
||||
--with-static-linked-ext \
|
||||
--with-ext=ripper,monitor
|
||||
```
|
||||
|
||||
7. Make
|
||||
```console
|
||||
$ make install
|
||||
```
|
||||
|
||||
```console
|
||||
$ make install
|
||||
```
|
||||
|
||||
Now you have a WASI compatible ruby binary. You can run it by any WebAssembly runtime like [`wasmtime`](https://github.com/bytecodealliance/wasmtime), [`wasmer`](https://github.com/wasmerio/wasmer), [Node.js](https://nodejs.org/api/wasi.html), or browser with [WASI polyfill](https://www.npmjs.com/package/@wasmer/wasi).
|
||||
|
||||
Note: it may take a long time (~20 sec) for the first time for JIT compilation
|
||||
|
||||
```
|
||||
```console
|
||||
$ wasmtime ruby-wasm32-wasi/usr/local/bin/ruby --mapdir /::./ruby-wasm32-wasi/ -- -e 'puts RUBY_PLATFORM'
|
||||
wasm32-wasi
|
||||
```
|
||||
|
||||
Note: you cannot run the built ruby without a WebAssembly runtime, because of the difference of the binary file type.
|
||||
|
||||
```
|
||||
```console
|
||||
$ ruby-wasm32-wasi/usr/local/bin/ruby -e 'puts "a"'
|
||||
bash: ruby-wasm32-wasi/usr/local/bin/ruby: cannot execute binary file: Exec format error
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user