diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/guides/compile.md | 146 | ||||
| -rw-r--r-- | doc/guides/mrbgems.md | 112 | ||||
| -rw-r--r-- | doc/mruby3.md | 2 |
3 files changed, 136 insertions, 124 deletions
diff --git a/doc/guides/compile.md b/doc/guides/compile.md index a8e35b65c..eba0c87ff 100644 --- a/doc/guides/compile.md +++ b/doc/guides/compile.md @@ -10,19 +10,20 @@ 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`) -* Parser generator (`bison`) -* Ruby 2.0 or later (e.g. `ruby` or `jruby`) +* Ruby 2.5 or later (e.g. `ruby` or `jruby`) + +Optional: + +* Git (to update mruby source and integrate mrbgems easier) +* C++ compiler (to use mrbgems which include `*.cpp`, `*.cxx`, `*.cc`) +* Bison (to compile `mrbgems/mruby-compiler/core/parse.y`) +* gperf (to compile `mrbgems/mruby-compiler/core/keywords`) Note that `bison` bundled with MacOS is too old to compile `mruby`. Try `brew install bison` and follow the instruction shown to update 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) - ## Build To compile `mruby` with the default build configuration, just invoke `rake` @@ -32,7 +33,7 @@ line on build, call `rake -v`. You can specify your own configuration file by the `MRUBY_CONFIG` environment variable (you can use `CONFIG` for shorthand for `MRUBY_CONFIG`). If the path -doesn't exist, *build_config/${MRUBY_CONFIG}.rb* is used. The default +doesn't exist, `build_config/${MRUBY_CONFIG}.rb` is used. The default configuration is defined in the `build_config/default.rb` file. Those build configuration files contain the build configuration of mruby, for @@ -48,7 +49,7 @@ All tools necessary to compile mruby can be set or modified here. ## Build Configuration -We wish you submit a pull-request to *build_config/**PLATFORM**.rb*, once you +We wish you submit a pull-request to `build_config/PLATFORM.rb`, once you created a new configuration for a new platform. Inside of the configuration file, the following options can be @@ -228,7 +229,7 @@ end ### Preallocated Symbols -By far, preallocate symbols are highly compatible with the previous versions, so +By far, preallocated symbols are highly compatible with the previous versions, so we expect you won't see any problem with them. But just in case you face any issue, you can disable preallocated symbols by specifying `conf.disable_presym`. @@ -279,7 +280,7 @@ conf.build_mrbtest_lib_only ### Bintest Tests for mrbgem tools using CRuby. -To have bintests place \*.rb scripts to `bintest/` directory of mrbgems. +To have bintests place `*.rb` scripts to `bintest/` directory of mrbgems. See `mruby-bin-*/bintest/*.rb` if you need examples. If you want a temporary files use `tempfile` module of CRuby instead of `/tmp/`. @@ -354,7 +355,7 @@ end ``` All configuration options of `MRuby::Build` can also be used in -`MRuby::CrossBuild`. You can find examples under the *build_config* +`MRuby::CrossBuild`. You can find examples under the `build_config` directory. ### Mrbtest in Cross-Compilation @@ -375,49 +376,42 @@ end ## Build process -During the build process the directory *build* will be created in the +During the build process the directory `build` will be created in the root directory. The structure of this directory will look like this: +- build | +- host | + +- LEGAL <- License description + | +- bin <- Binaries (mirb, mrbc and mruby) | +- lib <- Libraries (libmruby.a and libmruby_core.a) | - +- mrblib + +- mrbc <- Minimal mrbc place | - +- src + +- mrbgems <- Compilation result from mrbgems | - +- test <- mrbtest tool + +- mrblib <- Compilation result from mrblib | - +- tools - | - +- mirb - | - +- mrbc - | - +- mruby + +- src <- Compilation result from C sources 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 -result will be stored in *build/host/src/y.tab.c*) -* compile *build/host/src/y.tab.c* to *build/host/src/y.tab.o* -* create *build/host/lib/libmruby_core.a* out of all object files (C only) -* create `build/host/bin/mrbc` by compiling *tools/mrbc/mrbc.c* and -linking with *build/host/lib/libmruby_core.a* -* create *build/host/mrblib/mrblib.c* by compiling all \*.rb files -under *mrblib* with `build/host/bin/mrbc` -* compile *build/host/mrblib/mrblib.c* to *build/host/mrblib/mrblib.o* -* create *build/host/lib/libmruby.a* out of all object files (C and Ruby) -* create `build/host/bin/mruby` by compiling *mrbgems/mruby-bin-mruby/tools/mruby/mruby.c* and -linking with *build/host/lib/libmruby.a* -* create `build/host/bin/mirb` by compiling *mrbgems/mruby-bin-mirb/tools/mirb/mirb.c* and -linking with *build/host/lib/libmruby.a* +* compile minimal `mrbc` from `src` and `mrblib` sources + * compile all files under `src` (object files will be stored in `build/host/mrbc/src`) + * compile `mruby-compiler` gem + * create `build/host/mrbc/lib/libmruby_core.a` out of all object files (C only) + * create `build/host/mrbc/bin/mrbc` via `mruby-bin-mrbc` gem +* compile all files under `src` and store result in `build/host/src` +* create `build/host/mrblib/mrblib.c` by compiling all `*.rb` files under `mrblib` with `build/host/mrbc/bin/mrbc` +* compile `build/host/mrblib/mrblib.c` to `build/host/mrblib/mrblib.o` +* create `build/host/lib/libmruby.a` out of all object files (C and Ruby) +* compile (normal) mrbgems specified in the configuration file +* create `build/host/lib/libmruby.a` from object files from gems and `libmruby_core.a` +* create binary commands according to binary gems (e.g. `mirb` and `mruby`) +* copy binaries under `build/host/bin` to `bin` directory ``` _____ _____ ______ ____ ____ _____ _____ ____ @@ -428,7 +422,7 @@ linking with *build/host/lib/libmruby.a* ### Cross-Compilation -In case of a cross-compilation to *i386* the *build* directory structure looks +In case of a cross-compilation to `i386` the `build` directory structure looks like this: +- build @@ -439,63 +433,41 @@ like this: | | | +- lib <- Native Libraries | | - | +- mrblib + | +- mrbgems | | | +- src - | | - | +- test <- Native mrbtest tool - | | - | +- tools - | | - | +- mirb - | | - | +- mrbc - | | - | +- mruby + | +- i386 | +- bin <- Cross-compiled Binaries | + +- include <- Header Directory + | +- lib <- Cross-compiled Libraries | + +- mrbgems + | +- mrblib | +- src - | - +- test <- Cross-compiled mrbtest tool - | - +- tools - | - +- mirb - | - +- mrbc - | - +- mruby An extra directory is created for the target platform. In case you -compile for *i386* a directory called *i386* is created under the +compile for `i386` a directory called `i386` is created under the 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 -result will be stored in *build/i386/src/y.tab.c*) -* cross-compile *build/i386/src/y.tab.c* to *build/i386/src/y.tab.o* -* create *build/i386/mrblib/mrblib.c* by compiling all \*.rb files -under *mrblib* with the native `build/host/bin/mrbc` -* cross-compile *build/host/mrblib/mrblib.c* to *build/host/mrblib/mrblib.o* -* create *build/i386/lib/libmruby.a* out of all object files (C and Ruby) -* create `build/i386/bin/mruby` by cross-compiling *mrbgems/mruby-bin-mruby/tools/mruby/mruby.c* and -linking with *build/i386/lib/libmruby.a* -* create `build/i386/bin/mirb` by cross-compiling *mrbgems/mruby-bin-mirb/tools/mirb/mirb.c* and -linking with *build/i386/lib/libmruby.a* -* create *build/i386/lib/libmruby_core.a* out of all object files (C only) -* create `build/i386/bin/mrbc` by cross-compiling *tools/mrbc/mrbc.c* and -linking with *build/i386/lib/libmruby_core.a* +compilation by compiling all *native* libraries and binaries, except +for we don't have `host/mrbc` directory (`host` directory itself works +as placeholder for `mrbc`). Afterwards the cross compilation process +proceeds like this: + +* cross-compile all files under `src` and store result in `build/i386/src` +* create `build/i386/lib/libmruby_core.a` out of C object files +* create `build/i386/mrblib/mrblib.c` by compiling all `*.rb` files under `mrblib` with native `build/host/bin/mrbc` +* cross-compile `build/i386/mrblib/mrblib.c` to `build/i386/mrblib/mrblib.o` +* create `build/i386/lib/libmruby.a` from object files from gems and `libmruby_core.a` +* create binary commands according to binary gems (e.g. `mirb` and `mruby`) +* copy binaries under `build/host/bin` to `bin` directory ``` _______________________________________________________________ @@ -526,24 +498,23 @@ feature due to the reason that there are functions (e.g. stdio) which can't be disabled for the main build. ```ruby -MRuby::CrossBuild.new('Minimal') do |conf| +MRuby::CrossBuild.new('minimal') do |conf| toolchain :gcc conf.cc.defines = %w(MRB_NO_STDIO) - conf.bins = [] end ``` -This configuration defines a cross compile build called 'Minimal' which +This configuration defines a cross compile build called 'minimal' which is using the GCC and compiles for the host machine. It also disables -all usages of stdio and doesn't compile any binaries (e.g. mrbc). +all usages of stdio and doesn't compile any binaries (e.g. `mrbc`). ## Test Environment mruby's build process includes a test environment. In case you start the testing of mruby, a native binary called `mrbtest` will be generated and executed. -This binary contains all test cases which are defined under *test/t*. In case -of a cross-compilation an additional cross-compiled *mrbtest* binary is +This binary contains all test cases which are defined under `test/t`. In case +of a cross-compilation an additional cross-compiled `mrbtest` binary is generated. You can copy this binary and run on your target system. ## Embedding `mruby` in Your Application @@ -562,6 +533,7 @@ Usage: mruby-config [switches] --ldflags-before-libs print flags passed to linker before linked libraries --libs print linked libraries --libmruby-path print libmruby path + --help print this help ``` For example, when you have a C source file (`c.c`) and try to diff --git a/doc/guides/mrbgems.md b/doc/guides/mrbgems.md index 5ad00a5f2..5a6396e97 100644 --- a/doc/guides/mrbgems.md +++ b/doc/guides/mrbgems.md @@ -1,12 +1,13 @@ # mrbgems mrbgems is a library manager to integrate C and Ruby extension in an easy and -standardised way into mruby. +standardised way into mruby. Conventionally, each mrbgem name is prefixed by +`mruby-`, e.g. `mruby-time` for a gem that provides `Time` class functionality. ## Usage 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: +a gem, add the following line to your build configuration file, for example: ```ruby conf.gem '/path/to/your/gem/dir' @@ -69,7 +70,7 @@ 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 loaded into mruby via `config.gembox 'boxname'`. -Below we have created a GemBox containing *mruby-time* and *mrbgems-example*: +Below we have created a GemBox containing `mruby-time` and `mrbgems-example`: ```ruby MRuby::GemBox.new do |conf| @@ -79,10 +80,10 @@ end ``` 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 to be +must be saved with a `.gembox` extension inside the `mrbgems` directory to to be picked up by mruby. -To use this example GemBox, we save it as `custom.gembox` inside the *mrbgems* +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: @@ -90,8 +91,8 @@ the build block: 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. +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. @@ -103,7 +104,7 @@ conf.gembox "#{ENV["HOME"]}/mygemboxes/custom" There are two GemBoxes that ship with mruby: [default](../../mrbgems/default.gembox) and [full-core](../../mrbgems/full-core.gembox). The [default](../../mrbgems/default.gembox) GemBox contains several core components of mruby, and [full-core](../../mrbgems/full-core.gembox) -contains every gem found in the *mrbgems* directory. +contains every gem found in the `mrbgems` directory. ## GEM Structure @@ -111,27 +112,29 @@ The maximal GEM structure looks like this: +- GEM_NAME <- Name of GEM | + +- README.md <- Readme for GEM + | + +- mrbgem.rake <- GEM Specification + | +- include/ <- Header for Ruby extension (will exported) | +- mrblib/ <- Source for Ruby extension | +- src/ <- Source for C extension | - +- test/ <- Test code (Ruby) - | - +- mrbgem.rake <- GEM Specification + +- tools/ <- Source for Executable (in C) | - +- README.md <- Readme for GEM + +- test/ <- Test code (Ruby) -The folder *mrblib* contains pure Ruby files to extend mruby. The folder *src* -contains C/C++ files to extend mruby. The folder *include* contains C/C++ header -files. The folder *test* contains C/C++ and pure Ruby files for testing purposes -which will be used by `mrbtest`. *mrbgem.rake* contains the specification -to compile C and Ruby files. *README.md* is a short description of your GEM. +The folder `mrblib` contains pure Ruby files to extend mruby. The folder `src` +contains C/C++ files to extend mruby. The folder `include` contains C/C++ header +files. The folder `test` contains C/C++ and pure Ruby files for testing purposes +which will be used by `mrbtest`. `mrbgem.rake` contains the specification +to compile C and Ruby files. `README.md` is a short description of your GEM. ## Build process -mrbgems expects a specification file called *mrbgem.rake* inside of your +mrbgems expects a specification file called `mrbgem.rake` inside of your GEM directory. A typical GEM specification could look like this for example: ```ruby @@ -143,7 +146,7 @@ end ``` The mrbgems build process will use this specification to compile Object and Ruby -files. The compilation results will be added to *lib/libmruby.a*. This file exposes +files. The compilation results will be added to `lib/libmruby.a`. This file exposes the GEM functionality to tools like `mruby` and `mirb`. The following properties can be set inside of your `MRuby::Gem::Specification` for @@ -265,7 +268,7 @@ integrate C libraries into mruby. 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 +by the name of your GEM. If you call your GEM `c_extension_example`, your initialisation method could look like this: ```C @@ -280,7 +283,7 @@ mrb_c_extension_example_gem_init(mrb_state* mrb) { mrbgems expects that you have implemented a C method called `mrb_YOURGEMNAME_gem_final(mrb_state)`. `YOURGEMNAME` will be replaced -by the name of your GEM. If you call your GEM *c_extension_example*, your +by the name of your GEM. If you call your GEM `c_extension_example`, your finalizer method could look like this: ```C @@ -294,6 +297,8 @@ mrb_c_extension_example_gem_final(mrb_state* mrb) { +- c_extension_example/ | + +- README.md (Optional) + | +- src/ | | | +- example.c <- C extension source @@ -303,13 +308,11 @@ mrb_c_extension_example_gem_final(mrb_state* mrb) { | +- example.rb <- Test code for C extension | +- mrbgem.rake <- GEM specification - | - +- README.md ## Ruby Extension 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* +classes or add new ones in this way. Put all Ruby files into the `mrblib` folder. ### Pre-Conditions @@ -320,25 +323,25 @@ none +- ruby_extension_example/ | + +- README.md (Optional) + | +- mrblib/ | | - | +- example.rb <- Ruby extension source + | +- example.rb <- Ruby extension source | +- test/ | | - | +- example.rb <- Test code for Ruby extension + | +- example.rb <- Test code for Ruby extension | - +- mrbgem.rake <- GEM specification - | - +- README.md + +- mrbgem.rake <- GEM specification ## C and Ruby Extension mruby can be extended with C and Ruby at the same time. It is possible to override existing classes or add new ones in this way. Put all Ruby files -into the *mrblib* folder and all C files into the *src* folder. +into the `mrblib` folder and all C files into the `src` folder. -mruby codes under *mrblib* directory would be executed after gem init C +mruby codes under `mrblib` directory would be executed after gem init C function is called. Make sure *mruby script* depends on *C code* and *C code* doesn't depend on *mruby script*. @@ -350,18 +353,55 @@ See C and Ruby example. +- c_and_ruby_extension_example/ | + +- README.md (Optional) + | +- mrblib/ | | - | +- example.rb <- Ruby extension source + | +- example.rb <- Ruby extension source | +- src/ | | - | +- example.c <- C extension source + | +- example.c <- C extension source | +- test/ | | - | +- example.rb <- Test code for C and Ruby extension + | +- example.rb <- Test code for C and Ruby extension | - +- mrbgem.rake <- GEM specification + +- mrbgem.rake <- GEM specification + +## 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`, +e.g. `mruby-bin-mirb` and `mruby-bin-strip`. + +To specify the name of executable, you need to specify `spec.bins` in the +`mrbgem.rake`. The entry point `main()` should be in the C source file under +`tools/<bin>/*.c` where `<bin>` is a name of the executable. C files under the +`<bin>` directory are compiled and linked to the executable, but not included in +`libmruby.a`, whereas files under `mrblib` and `src` are. + +It is strongly recommended not to include `mrblib` and `src` directories in the +binary gems, to separate normal gems and binary gems. + +### Example + + +- mruby-bin-example/ + | + +- README.md (Optional) + | + +- bintest/ + | | + | +- example.rb <- Test code for binary gem + | + +- mrbgem.rake <- Gem specification + | + +- mrblib/ <- Source for Ruby extension (Optional) + | + +- src/ <- Source for C extension (Optional) | - +- README.md + +- tools/ + | + +- example/ <- Executable name directory + | + +- example.c <- Source for Executable (includes main) diff --git a/doc/mruby3.md b/doc/mruby3.md index ebd2673d5..b17f3d526 100644 --- a/doc/mruby3.md +++ b/doc/mruby3.md @@ -160,4 +160,4 @@ For better and faster random number generation. Preallocated symbols are interned at compile-time. They can be accessed via symbols macros (e.g. `MRB_SYM()`). -See [Symbols](https://github.com/mruby/mruby/blob/master/doc/guides/symbol.md). +See [Symbols](./guides/symbol.md). |