feat(CI): add a GitHub Action to lint the Markdown
Run on pull request only
Using
Lint Markdown for rules:
MD009/no-trailing-spaces
MD012/no-multiple-blanks
MD022/blanks-around-headings
MD031/blanks-around-fences
MD032/blanks-around-lists
ADD
.markdownlint.yml
+MD001: false
+MD003: false
+MD004: false
+MD005: false
+MD007: false
+MD010: false
+MD011: false
+MD013: false
+MD014: false
+MD024: false
+MD025: false
+MD026: false
+MD034: false
+MD040: false
+MD041: false
+MD046: false

MODIFY
doc/guides/compile.md
doc/guides/compile.md
@@ -6,6 +6,7 @@ binaries.
## Prerequisites
To compile mruby out of the source code you need the following tools:
+
* C Compiler (e.g. `gcc` or `clang`)
* Linker (e.g. `gcc` or `clang`)
* Archive utility (e.g. `ar`)
@@ -18,6 +19,7 @@ the `$PATH` to compile `mruby`. We also encourage to upgrade `ruby`
on MacOS in similar manner.
Optional:
+
* git (to update mruby source and integrate mrbgems easier)
* C++ compiler (to use GEMs which include \*.cpp, \*.cxx, \*.cc)
* Assembler (to use GEMs which include \*.asm)
@@ -61,6 +63,7 @@ configure the build environment for specific compiler infrastructures.
#### GCC
Toolchain configuration for the GNU C Compiler.
+
```ruby
toolchain :gcc
```
@@ -69,6 +72,7 @@ toolchain :gcc
Toolchain configuration for the LLVM C Compiler clang. Mainly equal to the
GCC toolchain.
+
```ruby
toolchain :clang
```
@@ -78,6 +82,7 @@ toolchain :clang
Toolchain configuration for Visual Studio on Windows. If you use the
[Visual Studio Command Prompt](https://msdn.microsoft.com/en-us/library/ms229859\(v=vs.110\).aspx),
you normally do not have to specify this manually, since it gets automatically detected by our build process.
+
```ruby
toolchain :visualcpp
```
@@ -85,6 +90,7 @@ toolchain :visualcpp
#### Android
Toolchain configuration for Android.
+
```ruby
toolchain :android
```
@@ -106,6 +112,7 @@ The configuration are done via `mrbgems`. See `Mrbgems` section.
Some environments require a different file separator character. It is possible to
set the character via `conf.file_separator`.
+
```ruby
conf.file_separator = '/'
```
@@ -113,6 +120,7 @@ conf.file_separator = '/'
### C Compiler
Configuration of the C compiler binary, flags and include paths.
+
```ruby
conf.cc do |cc|
cc.command = ...
@@ -128,6 +136,7 @@ end
C Compiler has header searcher to detect installed library.
If you need a include path of header file use `search_header_path`:
+
```ruby
# Searches ```iconv.h```.
# If found it will return include path of the header file.
@@ -136,6 +145,7 @@ fail 'iconv.h not found' unless conf.cc.search_header_path 'iconv.h'
```
If you need a full file name of header file use `search_header`:
+
```ruby
# Searches ```iconv.h```.
# If found it will return full path of the header file.
@@ -149,6 +159,7 @@ When you are using GCC toolchain (including clang toolchain since its base is gc
it will use compiler specific include paths too. (For example `/usr/local/include`, `/usr/include`)
If you need a special header search paths define a singleton method `header_search_paths` to C compiler:
+
```ruby
def conf.cc.header_search_paths
['/opt/local/include'] + include_paths
@@ -158,6 +169,7 @@ end
### Linker
Configuration of the Linker binary, flags and library paths.
+
```ruby
conf.linker do |linker|
linker.command = ...
@@ -175,6 +187,7 @@ end
### Archiver
Configuration of the Archiver binary and flags.
+
```ruby
conf.archiver do |archiver|
archiver.command = ...
@@ -185,6 +198,7 @@ end
### Parser Generator
Configuration of the Parser Generator binary and flags.
+
```ruby
conf.yacc do |yacc|
yacc.command = ...
@@ -195,6 +209,7 @@ end
### GPerf
Configuration of the GPerf binary and flags.
+
```ruby
conf.gperf do |gperf|
gperf.command = ...
@@ -203,6 +218,7 @@ end
```
### File Extensions
+
```ruby
conf.exts do |exts|
exts.object = ...
@@ -247,6 +263,7 @@ See doc/mrbgems/README.md for more option about mrbgems.
Configuration Mrbtest build process.
If you want mrbtest.a only, You should set `conf.build_mrbtest_lib_only`
+
```ruby
conf.build_mrbtest_lib_only
```
@@ -259,6 +276,7 @@ See `mruby-bin-*/bintest/*.rb` if you need examples.
If you want a temporary files use `tempfile` module of CRuby instead of `/tmp/`.
You can enable it with following:
+
```ruby
conf.enable_bintest
```
@@ -277,6 +295,7 @@ files are compiled by C++ compiler.
When you mix C++ code, C++ exception would be enabled automatically.
If you need to enable C++ exception explicitly add the following:
+
```ruby
conf.enable_cxx_exception
```
@@ -286,20 +305,24 @@ conf.enable_cxx_exception
If your compiler does not support C++ and you want to ensure
you don't use mrbgem written in C++, you can explicitly disable
C++ exception, add following:
+
```ruby
conf.disable_cxx_exception
```
+
and you will get an error when you try to use C++ gem.
Note that it must be called before `enable_cxx_exception` or `gem` method.
### Debugging mode
To enable debugging mode add the following:
+
```ruby
conf.enable_debug
```
When debugging mode is enabled
+
* Macro `MRB_DEBUG` would be defined.
* Which means `mrb_assert()` macro is enabled.
* Debug information of irep would be generated by `mrbc`.
@@ -330,6 +353,7 @@ directory.
In cross compilation, you can run `mrbtest` on emulator if
you have it by changing configuration of test runner.
+
```ruby
conf.test_runner do |t|
t.command = ... # set emulator. this value must be non nil or false
@@ -369,6 +393,7 @@ root directory. The structure of this directory will look like this:
+- mruby
The compilation workflow will look like this:
+
* compile all files under *src* (object files will be stored
in *build/host/src*)
* generate parser grammar out of *src/parse.y* (generated
@@ -446,6 +471,7 @@ build directory.
The cross compilation workflow starts in the same way as the normal
compilation by compiling all *native* libraries and binaries.
Afterwards the cross compilation process proceeds like this:
+
* cross-compile all files under *src* (object files will be stored
in *build/i386/src*)
* generate parser grammar out of *src/parse.y* (generated

MODIFY
doc/guides/debugger.md
doc/guides/debugger.md
@@ -220,6 +220,7 @@ Example:
```
Enabling all breakpoints
+
```
(foo.rb:1) enable 1 3
```

MODIFY
doc/guides/mrbconf.md
doc/guides/mrbconf.md
# mruby configuration macros.
## How to use these macros.
+
You can use mrbconfs with following ways:
+
* Write them in `mrbconf.h`.
* Using compiler flags is preferred when building a cross binaries or multiple mruby binaries
since it's easier to use different mrbconf per each `MRuby::Build`.
@@ -11,7 +13,9 @@ You can use mrbconfs with following ways:
changes `struct` layout and cause memory access error when C and other language(e.g., C++) is mixed.
## stdio setting.
+
`MRB_NO_STDIO`
+
* When defined `<stdio.h>` functions won't be used.
* Some features will be disabled when this is enabled:
* `mrb_irep` load/dump from/to file.
@@ -19,80 +23,97 @@ You can use mrbconfs with following ways:
* Printing features in **src/print.c**.
## Debug macros.
+
`MRB_USE_DEBUG_HOOK`
+
* When defined code fetch hook and debug OP hook will be enabled.
* When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`.
* Fetch hook will be called before any OP.
* Debug OP hook will be called when dispatching `OP_DEBUG`.
`MRB_DEBUG`
+
* When defined `mrb_assert*` macro will be defined with macros from `<assert.h>`.
* Could be enabled via `enable_debug` method of `MRuby::Build`.
## Stack configuration
`MRB_STACK_EXTEND_DOUBLING`
+
* If defined doubles the stack size when extending it.
* Else extends stack with `MRB_STACK_GROWTH`.
`MRB_STACK_GROWTH`
+
* Default value is `128`.
* Used in stack extending.
* Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined.
`MRB_STACK_MAX`
+
* Default value is `0x40000 - MRB_STACK_GROWTH`.
* Raises `RuntimeError` when stack size exceeds this value.
## Primitive type configuration.
`MRB_USE_FLOAT32`
+
* When defined single precision floating point type(C type `float`) is used as `mrb_float`.
* Otherwise double precision floating point type(C type `double`) is used as `mrb_float`.
`MRB_NO_FLOAT`
+
* When defined removes floating point numbers from mruby.
* It makes mruby easier to handle in "Microcontroller without FPU" and "Kernel Space".
`MRB_INT32`
+
* When defined, or `MRB_INT64` are not defined on 32-bit CPU mode, `mrb_int` will be defined as `int32_t`.
* Conflicts with `MRB_INT64`.
`MRB_INT64`
+
* When defined, or `MRB_INT32` are not defined on 64-bit CPU mode, `mrb_int` will be defined as `int64_t`.
* Conflicts with `MRB_INT32`.
## Garbage collector configuration.
`MRB_GC_STRESS`
+
* When defined full GC is emitted per each `RBasic` allocation.
* Mainly used in memory manager debugging.
`MRB_GC_TURN_OFF_GENERATIONAL`
+
* When defined turns generational GC by default.
`MRB_GC_FIXED_ARENA`
+
* When defined used fixed size GC arena.
* Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`.
* Useful tracking unnecessary mruby object allocation.
`MRB_GC_ARENA_SIZE`
+
* Default value is `100`.
* Ignored when `MRB_GC_FIXED_ARENA` isn't defined.
* Defines fixed GC arena size.
`MRB_HEAP_PAGE_SIZE`
+
* Defines value is `1024`.
* Specifies number of `RBasic` per each heap page.
## Memory pool configuration.
`POOL_ALIGNMENT`
+
* Default value is `4`.
* If you're allocating data types that requires alignment more than default value define the
largest value of required alignment.
`POOL_PAGE_SIZE`
+
* Default value is `16000`.
* Specifies page size of pool page.
* Smaller the value is increases memory overhead.
@@ -100,32 +121,38 @@ largest value of required alignment.
## State atexit configuration.
`MRB_FIXED_STATE_ATEXIT_STACK`
+
* If defined enables fixed size `mrb_state` atexit stack.
* Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds
`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value.
`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`
+
* Default value is `5`.
* If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored.
## `mrb_value` configuration.
`MRB_ENDIAN_BIG`
+
* If defined compiles mruby for big endian machines.
* Used in `MRB_NAN_BOXING`.
* Some mrbgem use this mrbconf.
`MRB_NAN_BOXING`
+
* If defined represent `mrb_value` in boxed `double`.
* Conflicts with `MRB_USE_FLOAT32` and `MRB_NO_FLOAT`.
`MRB_WORD_BOXING`
+
* If defined represent `mrb_value` as a word.
* If defined `Float` will be a mruby object with `RBasic`.
## Reduce heap memory configuration.
`MRB_USE_LINK_TIME_RO_DATA_P`
+
* Only available on ELF platforms.
* If you specify the address of a read-only section when creating a symbol or string, that string will be used as it is.
* Heap memory can be saved.
@@ -133,6 +160,7 @@ largest value of required alignment.
* It must be `__ehdr_start < data_addr < __init_array_start`.
`MRB_USE_CUSTOM_RO_DATA_P`
+
* Takes precedence over `MRB_USE_LINK_TIME_RO_DATA_P`.
* Please try if `MRB_USE_LINK_TIME_RO_DATA_P` is not available.
* The `mrb_ro_data_p()` function is implemented by the user in an arbitrary file.
@@ -140,33 +168,41 @@ largest value of required alignment.
* Return `TRUE` if `ptr` is in read-only section, otherwise return `FALSE`.
## Other configuration.
+
`MRB_UTF8_STRING`
+
* Adds UTF-8 encoding support to character-oriented String instance methods.
* If it isn't defined, they only support the US-ASCII encoding.
`MRB_FUNCALL_ARGC_MAX`
+
* Default value is `16`.
* Specifies 4th argument(`argc`) max value of `mrb_funcall`.
* Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`.
`KHASH_DEFAULT_SIZE`
+
* Default value is `32`.
* Specifies default size of khash table bucket.
* Used in `kh_init_ ## name` function.
`MRB_NO_METHOD_CACHE`
+
* Disable method cache to save memory.
`MRB_METHOD_CACHE_SIZE`
+
* Default value is `256`.
* Ignored if `MRB_NO_METHOD_CACHE` is defined.
* Need to be the power of 2.
`MRB_USE_METHOD_T_STRUCT`
+
* Use C struct to represent `mrb_method_t`
* No `MRB_USE_METHOD_T_STRUCT` requires highest 2 bits of function pointers to be zero
* Define this macro on machines that use higher bits of pointers
`MRB_USE_ALL_SYMBOLS`
+
* Make it available `Symbol.all_symbols` in `mrbgems/mruby-symbol-ext`
* Increase heap memory usage.

MODIFY
doc/guides/mrbgems.md
doc/guides/mrbgems.md
@@ -25,6 +25,7 @@ In that case,
* otherwise, it is relative from the directory where your build configuration is.
A remote GIT repository location for a GEM is also supported:
+
```ruby
conf.gem :git => 'https://github.com/masuidrive/mrbgems-example.git', :branch => 'master'
conf.gem :github => 'masuidrive/mrbgems-example', :branch => 'master'
@@ -32,17 +33,20 @@ conf.gem :bitbucket => 'mruby/mrbgems-example', :branch => 'master'
```
You can specify the sub directory of the repository with `:path` option:
+
```ruby
conf.gem github: 'mruby/mruby', path: 'mrbgems/mruby-socket'
```
To use mrbgem from [mgem-list](https://github.com/mruby/mgem-list) use `:mgem` option:
+
```ruby
conf.gem :mgem => 'mruby-yaml'
conf.gem :mgem => 'yaml' # 'mruby-' prefix could be omitted
```
For specifying commit hash to checkout use `:checksum_hash` option:
+
```ruby
conf.gem mgem: 'mruby-redis', checksum_hash: '3446d19fc4a3f9697b5ddbf2a904f301c42f2f4e'
```
@@ -66,6 +70,7 @@ 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*:
+
```ruby
MRuby::GemBox.new do |conf|
conf.gem "#{root}/mrbgems/mruby-time"
@@ -80,14 +85,17 @@ picked up by mruby.
To use this example GemBox, we save it as `custom.gembox` inside the *mrbgems*
directory in mruby, and add the following to your build configuration file inside
the build block:
+
```ruby
conf.gembox 'custom'
```
+
This will cause the *custom* GemBox to be read in during the build process,
adding *mruby-time* and *mrbgems-example* to the build.
If you want, you can put GemBox outside of mruby directory. In that case you must
specify an absolute path like below.
+
```ruby
conf.gembox "#{ENV["HOME"]}/mygemboxes/custom"
```
@@ -125,6 +133,7 @@ to compile C and Ruby files. *README.md* is a short description of your GEM.
mrbgems expects a specification file called *mrbgem.rake* inside of your
GEM directory. A typical GEM specification could look like this for example:
+
```ruby
MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec|
spec.license = 'MIT'
@@ -154,6 +163,7 @@ The `license` and `author` properties are required in every GEM!
In case your GEM is depending on other GEMs please use
`spec.add_dependency(gem, *requirements[, default_get_info])` like:
+
```ruby
MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec|
spec.license = 'MIT'
@@ -177,6 +187,7 @@ end
The version requirements and default gem information are optional.
Version requirement supports following operators:
+
* '=': is equal
* '!=': is not equal
* '>': is greater
@@ -197,10 +208,12 @@ When a special version of dependency is required,
use `MRuby::Build#gem` in the build configuration to override default gem.
If you have conflicting GEMs use the following method:
+
* `spec.add_conflict(gem, *requirements)`
* The `requirements` argument is same as in `add_dependency` method.
like following code:
+
```ruby
MRuby::Gem::Specification.new 'some-regexp-binding' do |spec|
spec.license = 'BSD'
@@ -243,7 +256,6 @@ For example: when B depends to C and A depends to B, A will get include paths ex
Exported include_paths are automatically appended to GEM local include_paths by rake.
You can use `spec.export_include_paths` accessor if you want more complex build.
-
## C Extension
mruby can be extended with C. This is possible by using the C API to
@@ -255,6 +267,7 @@ mrbgems expects that you have implemented a C method called
`mrb_YOURGEMNAME_gem_init(mrb_state)`. `YOURGEMNAME` will be replaced
by the name of your GEM. If you call your GEM *c_extension_example*, your
initialisation method could look like this:
+
```C
void
mrb_c_extension_example_gem_init(mrb_state* mrb) {
@@ -299,7 +312,6 @@ mruby can be extended with pure Ruby. It is possible to override existing
classes or add new ones in this way. Put all Ruby files into the *mrblib*
folder.
-
### Pre-Conditions
none

MODIFY
doc/limitations.md
doc/limitations.md
@@ -13,7 +13,6 @@ This document is collecting these limitations.
This document does not contain a complete list of limitations.
Please help to improve it by submitting your findings.
-
## `1/2` gives `0.5`
Since mruby does not have `Bignum`, bigger integers are represented
@@ -72,6 +71,7 @@ rescue => e
raise e
end
```
+
## Fiber execution can't cross C function boundary
mruby's `Fiber` is implemented in a similar way to Lua's co-routine. This
@@ -290,6 +290,7 @@ Ruby outputs `falsy`. mruby outputs `truthy`.
def m(a,(b,c),d); p [a,b,c,d]; end
m(1,[2,3],4) # => [1,2,3,4]
```
+
Destructured arguments (`b` and `c` in above example) cannot be accessed
from the default expression of optional arguments and keyword arguments,
since actual assignment is done after the evaluation of those default

MODIFY
mrbgems/mruby-io/README.md
mrbgems/mruby-io/README.md
@@ -4,6 +4,7 @@ mruby-io
`IO` and `File` classes for mruby
## Installation
+
Add the line below to your build configuration.
```
@@ -13,6 +14,7 @@ Add the line below to your build configuration.
## Implemented methods
### IO
+
- https://doc.ruby-lang.org/ja/1.9.3/class/IO.html
| method | mruby-io | memo |
@@ -97,6 +99,7 @@ Add the line below to your build configuration.
| IO#write_nonblock | | |
### File
+
- https://doc.ruby-lang.org/ja/1.9.3/class/File.html
| method | mruby-io | memo |
@@ -167,7 +170,6 @@ Add the line below to your build configuration.
| File#size | | |
| File#truncate | | |
-
## License
Copyright (c) 2013 Internet Initiative Japan Inc.

MODIFY
mrbgems/mruby-pack/README.md
mrbgems/mruby-pack/README.md
@@ -3,8 +3,8 @@ mruby-pack (pack / unpack)
mruby-pack provides `Array#pack` and `String#unpack` for mruby.
-
## Installation
+
Add the line below into your build configuration:
```
@@ -13,8 +13,8 @@ Add the line below into your build configuration:
There is no dependency on other mrbgems.
-
## Supported template string
+
- A : arbitrary binary string (space padded, count is width)
- a : arbitrary binary string (null padded, count is width)
- C : 8-bit unsigned (unsigned char)
@@ -44,8 +44,6 @@ There is no dependency on other mrbgems.
- x : null byte
- Z : same as "a", except that null is added with *
-
-
## License
Copyright (c) 2012 Internet Initiative Japan Inc.
@@ -68,4 +66,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
-

MODIFY
mrbgems/mruby-sleep/README.md
mrbgems/mruby-sleep/README.md
# Sleep Module for mruby
+
mruby sleep module
## install by mrbgems
+
- add conf.gem line to your build configuration.
```ruby
@@ -21,8 +23,7 @@ usleep(10000)
```
# License
+
under the MIT License:
* https://www.opensource.org/licenses/mit-license.php
-
-

MODIFY
mrbgems/mruby-socket/README.md
mrbgems/mruby-socket/README.md
@@ -4,8 +4,8 @@ mruby-socket
"mruby-socket" mrbgem provides BSD socket interface for mruby.
API is compatible with CRuby's "socket" library.
-
## Example
+
```sh
% vi kame.rb
s = TCPSocket.open("www.kame.net", 80)
@@ -20,18 +20,19 @@ Date: Tue, 21 May 2013 04:31:30 GMT
```
## Requirement
+
- [mruby-io](https://github.com/mruby/mruby/tree/master/mrbgems/mruby-io) mrbgem
- [iij/mruby-mtest](https://github.com/iij/mruby-mtest) mrgbem to run tests
- system must have RFC3493 basic socket interface
- and some POSIX API...
## TODO
+
- add missing methods
- write more tests
- fix possible descriptor leakage (see XXX comments)
- `UNIXSocket#recv_io` `UNIXSocket#send_io`
-
## License
Copyright (c) 2013 Internet Initiative Japan Inc.

MODIFY
mrbgems/mruby-test/README.md
mrbgems/mruby-test/README.md
@@ -4,4 +4,3 @@ Running Tests
To run the tests, execute the following from the project's root directory.
$ make test
-

feat(CI): add a GitHub Action to lint the Markdown

Run on pull request only
Using https://www.npmjs.com/package/markdownlint-cli
Lint Markdown for rules:
- MD009/no-trailing-spaces
- MD012/no-multiple-blanks
- MD022/blanks-around-headings
- MD031/blanks-around-fences
- MD032/blanks-around-lists