diff --git a/README.md b/README.md index f1ed47a65..cc5be3ab8 100644 --- a/README.md +++ b/README.md @@ -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 . We consider you have granted +request to . 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 diff --git a/doc/guides/gc-arena-howto.md b/doc/guides/gc-arena-howto.md index 2a5fa92b4..22cd4ef1e 100644 --- a/doc/guides/gc-arena-howto.md +++ b/doc/guides/gc-arena-howto.md @@ -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)`. diff --git a/doc/guides/link.md b/doc/guides/link.md index 73ecd62a6..861f71365 100644 --- a/doc/guides/link.md +++ b/doc/guides/link.md @@ -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 -`/tools/`. Currently, we support C or C++ source code +`/tools/`. 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`. diff --git a/doc/guides/mrbgems.md b/doc/guides/mrbgems.md index ace9050e1..d631edda4 100644 --- a/doc/guides/mrbgems.md +++ b/doc/guides/mrbgems.md @@ -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 diff --git a/doc/guides/symbol.md b/doc/guides/symbol.md index 77beb3e05..c76420da9 100644 --- a/doc/guides/symbol.md +++ b/doc/guides/symbol.md @@ -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. diff --git a/doc/mruby3.0.md b/doc/mruby3.0.md index 9c006812e..cf9092aa3 100644 --- a/doc/mruby3.0.md +++ b/doc/mruby3.0.md @@ -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.