mirror of
https://github.com/mruby/mruby
synced 2026-06-08 16:11:16 +00:00
docs: standardize whitespace in Markdown files
Most of the Markdown has a single space between sentences. This pr changes `2 spaces` to `1 space`.
This commit is contained in:
@@ -7,10 +7,10 @@
|
||||
mruby is the lightweight implementation of the Ruby language complying to (part
|
||||
of) the [ISO standard][ISO-standard]. Its syntax is Ruby 2.x compatible.
|
||||
|
||||
mruby can be linked and embedded within your application. We provide the
|
||||
mruby can be linked and embedded within your application. We provide the
|
||||
interpreter program "mruby", and the interactive mruby shell "mirb" as examples.
|
||||
You can also compile Ruby programs into compiled byte code using the mruby
|
||||
compiler "mrbc". All those tools reside in the "bin" directory. "mrbc" is
|
||||
compiler "mrbc". All those tools reside in the "bin" directory. "mrbc" is
|
||||
also able to generate compiled byte code in a C source file, see the "mrbtest"
|
||||
program under the "test" directory for an example.
|
||||
|
||||
@@ -78,7 +78,7 @@ mruby has chosen a MIT License due to its permissive license allowing
|
||||
developers to target various environments such as embedded systems.
|
||||
However, the license requires the display of the copyright notice and license
|
||||
information in manuals for instance. Doing so for big projects can be
|
||||
complicated or troublesome. This is why mruby has decided to display "mruby
|
||||
complicated or troublesome. This is why mruby has decided to display "mruby
|
||||
developers" as the copyright name to make it simple conventionally.
|
||||
In the future, mruby might ask you to distribute your new code
|
||||
(that you will commit,) under the MIT License as a member of
|
||||
@@ -92,7 +92,7 @@ Please ask us if you want to distribute your code under another license.
|
||||
## How to Contribute
|
||||
|
||||
See the [contribution guidelines][contribution-guidelines], and then send a pull
|
||||
request to <https://github.com/mruby/mruby>. We consider you have granted
|
||||
request to <https://github.com/mruby/mruby>. We consider you have granted
|
||||
non-exclusive right to your contributed code under MIT license.
|
||||
|
||||
[ISO-standard]: https://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=59579
|
||||
|
||||
@@ -7,19 +7,19 @@ _Some parts are updated to reflect recent changes._
|
||||
|
||||
When you are extending mruby using C language, you may encounter
|
||||
mysterious "arena overflow error" or memory leak or very slow
|
||||
execution speed. This is an error indicating overflow of "GC arena"
|
||||
execution speed. This is an error indicating overflow of "GC arena"
|
||||
implementing "conservative GC".
|
||||
|
||||
GC (garbage collector) must ensure that object is "alive", in other
|
||||
words, that it is referenced by somewhere from the program. This can be
|
||||
words, that it is referenced by somewhere from the program. This can be
|
||||
determined by checking if the object can be directly or indirectly
|
||||
referenced by root. The local variables, global variables and
|
||||
referenced by root. The local variables, global variables and
|
||||
constants etc. are root.
|
||||
|
||||
If program execution is performed inside mruby VM, there is nothing to
|
||||
worry about because GC can access all roots owned by the VM.
|
||||
|
||||
The problem arises when executing C functions. The object referenced
|
||||
The problem arises when executing C functions. The object referenced
|
||||
by C variable is also "alive", but mruby GC cannot aware of this, so
|
||||
it might mistakenly recognize the objects referenced by only C
|
||||
variables as dead.
|
||||
@@ -27,15 +27,15 @@ variables as dead.
|
||||
This can be a fatal bug if the GC tries to collect a live object.
|
||||
|
||||
In CRuby, we scan C stack area, and use C variable as root to check
|
||||
whether object is alive or not. Of course, because we are accessing C
|
||||
whether object is alive or not. Of course, because we are accessing C
|
||||
stack just as memory region, we never know it is an integer or a
|
||||
pointer. We work around this by assuming that if it looks like a
|
||||
pointer, then assume it as a pointer. We call it "conservative".
|
||||
pointer. We work around this by assuming that if it looks like a
|
||||
pointer, then assume it as a pointer. We call it "conservative".
|
||||
|
||||
By the way, CRuby's "conservative GC" has some problems.
|
||||
|
||||
The biggest problem is we have no way to access to the stack area in
|
||||
portable way. Therefore, we cannot use this method if we'd like to
|
||||
portable way. Therefore, we cannot use this method if we'd like to
|
||||
implement highly portable runtime, like mruby.
|
||||
|
||||
So we came up with another plan to implement "conservative GC" in mruby.
|
||||
@@ -65,11 +65,11 @@ objects (See `MRB_GC_FIXED_ARENA` and `MRB_GC_ARENA_SIZE` in
|
||||
doc/guides/mrbconf.md).
|
||||
|
||||
If you create many objects in C functions, memory usage will increase, since
|
||||
GC never kicks in. This memory usage may look like memory leaks, but will also
|
||||
GC never kicks in. This memory usage may look like memory leaks, but will also
|
||||
make execution slower as more memory will need to be allocated.
|
||||
|
||||
With the build time configuration, you can limit the maximum size of
|
||||
arena (e.g., 100). Then if you create many objects, arena overflows,
|
||||
arena (e.g., 100). Then if you create many objects, arena overflows,
|
||||
thus you will get an "arena overflow error".
|
||||
|
||||
To work around these problems, we have `mrb_gc_arena_save()` and
|
||||
@@ -93,7 +93,7 @@ In mruby, C function calls are surrounded by this save/restore, but we
|
||||
can further optimize memory usage by surrounding save/restore, and can
|
||||
avoid creating arena overflow bugs.
|
||||
|
||||
Let's take a real example. Here is the source code of `Array#inspect`:
|
||||
Let's take a real example. Here is the source code of `Array#inspect`:
|
||||
|
||||
```c
|
||||
static mrb_value
|
||||
@@ -146,7 +146,7 @@ of array using `inspect` method, we join them together so that we can
|
||||
get `inspect` representation of the entire array.
|
||||
|
||||
After the `inspect` representation is created, we no longer require the
|
||||
individual string representation. This means that we don't have to register
|
||||
individual string representation. This means that we don't have to register
|
||||
these temporal objects into GC arena.
|
||||
|
||||
Therefore, in order to keep the arena size small; the `ary_inspect()` function
|
||||
@@ -158,11 +158,11 @@ will do the following:
|
||||
- restore stack top position using `mrb_gc_arena_restore()`.
|
||||
|
||||
Please note that the final `inspect` representation of entire array
|
||||
was created before the call of `mrb_gc_arena_restore()`. Otherwise,
|
||||
was created before the call of `mrb_gc_arena_restore()`. Otherwise,
|
||||
required temporal object may be deleted by GC.
|
||||
|
||||
We may have an usecase where after creating many temporal objects, we'd
|
||||
like to keep some of them. In this case, we cannot use the same idea
|
||||
like to keep some of them. In this case, we cannot use the same idea
|
||||
in `ary_inspect()` like appending objects to existing one.
|
||||
Instead, after `mrb_gc_arena_restore()`, we must re-register the objects we
|
||||
want to keep in the arena using `mrb_gc_protect(mrb, obj)`.
|
||||
|
||||
+2
-2
@@ -8,7 +8,7 @@ You have two ways to link `libmruby` to your application.
|
||||
## Executable Gems
|
||||
|
||||
If your application is relatively small, `mrbgem` is an easier way to
|
||||
create the executable. By tradition, the gem name start with
|
||||
create the executable. By tradition, the gem name start with
|
||||
`mruby-bin-`, e.g. `mruby-bin-debugger`.
|
||||
|
||||
### `mrbgem.rake` file
|
||||
@@ -28,7 +28,7 @@ end
|
||||
### Source tree structure
|
||||
|
||||
The source file for the gem executable should be in
|
||||
`<gem-name>/tools/<bin-name>`. Currently, we support C or C++ source code
|
||||
`<gem-name>/tools/<bin-name>`. Currently, we support C or C++ source code
|
||||
(`.c`, `.cpp`, `.cxx`, `.cc`) for the executable. Ruby source files are not
|
||||
supported. Put the functionality in the different gem and specify dependency to
|
||||
it in `mrbgem.rake`.
|
||||
|
||||
@@ -6,7 +6,7 @@ standardised way into mruby. Conventionally, each mrbgem name is prefixed by
|
||||
|
||||
## Usage
|
||||
|
||||
You have to activate mrbgems explicitly in your build configuration. To add
|
||||
You have to activate mrbgems explicitly in your build configuration. To add
|
||||
a gem, add the following line to your build configuration file, for example:
|
||||
|
||||
```ruby
|
||||
@@ -61,7 +61,7 @@ mrbgem from the core or mgem-list.
|
||||
Note that if more than one git-based gem has the same base name
|
||||
(i.e. the default checkout directory name), it is (now) an error
|
||||
**UNLESS** they have the same repository URL, branch name and
|
||||
commit-id (i.e. checksum hash). You can bypass this by explicitly
|
||||
commit-id (i.e. checksum hash). You can bypass this by explicitly
|
||||
importing your preferred version **first** and setting the
|
||||
`canonical:` option to `true`:
|
||||
|
||||
@@ -72,8 +72,8 @@ conf.gem github: 'me/mruby-yaml', branch: 'my-hacked-branch', canonical: true
|
||||
If you do this, the system will (mostly) silently ignore other
|
||||
attempts to clone a gem with this name.
|
||||
|
||||
Note that this only affects cloning the gem from git. It does not
|
||||
resolve version conflicts. If the version as specified in the gem's
|
||||
Note that this only affects cloning the gem from git. It does not
|
||||
resolve version conflicts. If the version as specified in the gem's
|
||||
rakefile is incompatible with a dependency, your build will still
|
||||
fail.
|
||||
|
||||
@@ -81,10 +81,10 @@ fail.
|
||||
|
||||
There are instances when you wish to add a collection of mrbgems into mruby at
|
||||
once, or be able to substitute mrbgems based on configuration, without having to
|
||||
add each gem to your build configuration file. A packaged collection of mrbgems
|
||||
is called a GemBox. A GemBox is a file that contains a list of mrbgems to load
|
||||
add each gem to your build configuration file. A packaged collection of mrbgems
|
||||
is called a GemBox. A GemBox is a file that contains a list of mrbgems to load
|
||||
into mruby, in the same format as if you were adding them to the build config
|
||||
via `config.gem`, but wrapped in an `MRuby::GemBox` object. GemBoxes are
|
||||
via `config.gem`, but wrapped in an `MRuby::GemBox` object. GemBoxes are
|
||||
loaded into mruby via `config.gembox 'boxname'`.
|
||||
|
||||
Below we have created a GemBox containing `mruby-time` and `mrbgems-example`:
|
||||
@@ -96,7 +96,7 @@ MRuby::GemBox.new do |conf|
|
||||
end
|
||||
```
|
||||
|
||||
As mentioned, the GemBox uses the same conventions as `MRuby::Build`. The GemBox
|
||||
As mentioned, the GemBox uses the same conventions as `MRuby::Build`. The GemBox
|
||||
must be saved with a `.gembox` extension inside the `mrbgems` directory to be
|
||||
picked up by mruby.
|
||||
|
||||
@@ -397,7 +397,7 @@ See C and Ruby example.
|
||||
## Binary gems
|
||||
|
||||
Some gems can generate executables under `bin` directory. Those gems are called
|
||||
binary gems. Names of binary gems are conventionally prefixed by `mruby-bin`,
|
||||
binary gems. Names of binary gems are conventionally prefixed by `mruby-bin`,
|
||||
e.g. `mruby-bin-mirb` and `mruby-bin-strip`.
|
||||
|
||||
To specify the name of executable, you need to specify `spec.bins` in the
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Symbols
|
||||
|
||||
Symbols in `mruby` C source code is represented by `mrb_sym` which is alias of
|
||||
`uint32_t`. Lower 30 bits are used for symbols so that higher 2 bits can be
|
||||
`uint32_t`. Lower 30 bits are used for symbols so that higher 2 bits can be
|
||||
used as flags, e.g. `struct mt_elem` in `class.c`.
|
||||
|
||||
```c
|
||||
@@ -71,9 +71,9 @@ can be specified for it). Other than that, describe only word characters
|
||||
excluding leading and ending punctuations.
|
||||
|
||||
These macros are converted to static symbol IDs at compile time, unless
|
||||
preallocate symbols are disabled by `conf.disable_presym`. In that case,
|
||||
preallocate symbols are disabled by `conf.disable_presym`. In that case,
|
||||
these macros are expanded to `mrb_intern_lit` calls, therefore the mruby state
|
||||
variable is required. The above macros assume the variable name is `mrb`. If
|
||||
variable is required. The above macros assume the variable name is `mrb`. If
|
||||
its name is not `mrb`, you need to use macros with `_2` suffix, such as
|
||||
`MRB_SYM_2` to specify `mrb_state*` variable.
|
||||
|
||||
|
||||
+2
-2
@@ -17,7 +17,7 @@ You can specify the build configuration file with the
|
||||
`MRUBY_CONFIG` environment variable (or `CONFIG` in short).
|
||||
If the value specified by `MRUBY_CONFIG` is not the path to
|
||||
the configuration file, `build_config/${MRUBY_CONFIG}.rb` is
|
||||
used. So you can specify it as `rake MRUBY_CONFIG=boxing`,
|
||||
used. So you can specify it as `rake MRUBY_CONFIG=boxing`,
|
||||
for example.
|
||||
|
||||
# Build Configuration Contribution
|
||||
@@ -60,7 +60,7 @@ Some configuration macro names are changed for consistency (use `MRB_USE_XXX`
|
||||
| `DISABLE_MIRB_UNDERSCORE` | `MRB_NO_MIRB_UNDERSCORE` |
|
||||
|
||||
- `MRB_USE_FLOAT32` is changed from `MRB_USE_FLOAT` to make sure `float` here
|
||||
means using single precision float, and not the opposite of `MRB_NO_FLOAT`.
|
||||
means using single precision float, and not the opposite of `MRB_NO_FLOAT`.
|
||||
- `MRB_USE_METHOD_T_STRUCT` uses `struct` version of `mrb_method_t`. More
|
||||
portable but consumes more memory. Turned on by default on 32bit platforms.
|
||||
- `MRB_` prefix is added to those without.
|
||||
|
||||
Reference in New Issue
Block a user