Merge pull request #5084 from mruby/mruby3

Mruby3

2 files changed, 78 insertions, 41 deletions

diff --git a/doc/guides/compile.md b/doc/guides/compile.md
index d7937bb2e..233c3e594 100644
--- a/doc/guides/compile.md
+++ b/doc/guides/compile.md
@@ -14,37 +14,53 @@ To compile mruby out of the source code you need the following tools:
 
 Note that `bison` bundled with MacOS is too old to compile `mruby`.
 Try `brew install bison` and follow the instuction shown to update
-the `$PATH` to compile `mruby`.
+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)
+* 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)
 
-## Usage
+## Build
+
+To compile `mruby`, just call `rake` inside of the mruby source
+root. To generate and execute the test tools call `rake test`. To
+clean all build files call `rake clean`. To see full command line on
+build, call `rake -v`.
+
+If you want to compile for the specific configuration, specify
+`MRUBY_TARGET` or `TARGET` environment variable, e.g
+
+```sh
+rake TAGRET=host
+```
+
+The default target is `host`.  The compilation target desciption files
+(with `.rb` suffix) are contained in the `target` directory.
+
+A build description file contains the build configuration of mruby and
+looks like the following for example:
 
-Inside of the root directory of the mruby source a file exists
-called *build_config.rb*. This file contains the build configuration
-of mruby and looks like this for example:
 ```ruby
 MRuby::Build.new do |conf|
   toolchain :gcc
 end
 ```
 
-All tools necessary to compile mruby can be set or modified here. In case
-you want to maintain an additional *build_config.rb* you can define a
-customized path using the *$MRUBY_CONFIG* environment variable.
-
-To compile just call `rake` inside of the mruby source root. To
-generate and execute the test tools call `rake test`. To clean
-all build files call `rake clean`. To see full command line on
-build, call `rake -v`.
+All tools necessary to compile mruby can be set or modified here. In
+case you want to try different configuration, you can create a new
+configuration file under `target` and specify the configuration using
+the `MRUBY_TARGET` environment variable.
 
 ## Build Configuration
 
-Inside of the *build_config.rb* the following options can be configured
-based on your environment.
+To create a new configuration, copy the existing configuration in the
+`target` directory, and modify it. We wish you submit a pull-request,
+once you created a new configuration for a new platform.
+
+Inside of the configuration file, the following options can be
+configured based on your environment.
 
 ### Toolchains
 
@@ -88,15 +104,12 @@ in `ANDROID_STANDALONE_TOOLCHAIN`.
 ### Binaries
 
 It is possible to select which tools should be compiled during the compilation
-process. The following tools can be selected:
-* mruby (mruby interpreter)
-* mirb (mruby interactive shell)
+process. For example, 
 
-To select them declare conf.gem as follows:
-```ruby
-conf.gem "#{root}/mrbgems/mruby-bin-mruby"
-conf.gem "#{root}/mrbgems/mruby-bin-mirb"
-```
+* `mruby`
+* `mirb`
+
+The configuration are done via `mrbgems`. See `Mrbgems` section.
 
 ### File Separator
 
@@ -209,17 +222,33 @@ end
 
 ### Mrbgems
 
-Integrate GEMs in the build process.
+`mruby` comes with the (sort of) packaging system named `mrbgems`. To
+specify `gem`, you can use `conf.gem` in the configuration file.
+
 ```ruby
-# Integrate GEM with additional configuration
-conf.gem 'path/to/gem' do |g|
-  g.cc.flags << ...
-end
+# Integrate a bundled Gem you see in `mrbgems` directory
+conf.gem :core => 'mruby-something'
+
+# Integrate a Gem from GitHub
+conf.gem :github => 'someone/mruby-another'
 
-# Integrate GEM without additional configuration
-conf.gem 'path/to/another/gem'
+# Integrate a mruby binary Gem
+conf.gem :core => 'mruby-bin-mruby'
+
+# Integrate a interactive mruby binary Gem
+conf.gem :core => 'mruby-bin-mirb'
+
+# Integrate GemBox (set of Gems)
+conf.gembox "default"
 ```
 
+A GemBox is a set of Gems defined in `mrbgems/default.gembox` for example.
+It's just a set of `mrbgem` configurations.
+
+There is a `RubyGem` (gem for CRuby) named `mgem` that help you to
+manage `mrbgems`. Try `gem install mgem`. `mgem` can show you the list
+of registered `mrbgems`.
+
 See doc/mrbgems/README.md for more option about mrbgems.
 
 ### Mrbtest
@@ -327,6 +356,10 @@ root directory. The structure of this directory will look like this:
 
 	+- build
 	   |
+	   +-  presym         <- List of preallocated symbolx
+       |
+	   +-  presym.inc     <- C source file for preallocated symbols
+       |
 	   +-  host
 	       |
 	       +- bin          <- Binaries (mirb, mrbc and mruby)
@@ -379,6 +412,10 @@ like this:
 
 	+- build
 	   |
+	   +-  presym         <- List of preallocated symbolx
+       |
+	   +-  presym.inc     <- C source file for preallocated symbols
+	   |
 	   +-  host
 	   |   |
 	   |   +- bin           <- Native Binaries
diff --git a/doc/guides/mrbconf.md b/doc/guides/mrbconf.md
index 1e1a5afcf..c95634604 100644
--- a/doc/guides/mrbconf.md
+++ b/doc/guides/mrbconf.md
@@ -46,11 +46,11 @@ You can use mrbconfs with following ways:
 
 ## Primitive type configuration.
 
-`MRB_USE_FLOAT`
+`MRB_USE_FLOAT32`
 * When defined single precision floating point type(C type `float`) is used as `mrb_float`.
-* Else double precision floating point type(C type `double`) is used as `mrb_float`.
+* Otherwise double precision floating point type(C type `double`) is used as `mrb_float`.
 
-`MRB_WITHOUT_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".
 
@@ -117,7 +117,7 @@ largest value of required alignment.
 
 `MRB_NAN_BOXING`
 * If defined represent `mrb_value` in boxed `double`.
-* Conflicts with `MRB_USE_FLOAT` and `MRB_WITHOUT_FLOAT`.
+* Conflicts with `MRB_USE_FLOAT32` and `MRB_NO_FLOAT`.
 
 `MRB_WORD_BOXING`
 * If defined represent `mrb_value` as a word.
@@ -163,17 +163,17 @@ largest value of required alignment.
 * Default value is `128`.
 * Specifies initial capacity of `RString` created by `mrb_str_buf_new` function..
 
-`MRB_METHOD_CACHE`
-* Improve performance for method dispatch.
+`MRB_NO_METHOD_CACHE`
+* Disable method cache to save memory.
 
 `MRB_METHOD_CACHE_SIZE`
-* Default value is `128`.
-* Ignored if `MRB_METHOD_CACHE` is not defined.
+* Default value is `256`.
+* Ignored if `MRB_NO_METHOD_CACHE` is defined.
 * Need to be the power of 2.
 
-`MRB_METHOD_T_STRUCT`
+`MRB_USE_METHOD_T_STRUCT`
 * Use C struct to represent `mrb_method_t`
-* No `MRB_METHOD_T_STRUCT` requires highest 2 bits of function pointers to be zero
+* 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_ENABLE_ALL_SYMBOLS`