admin/mruby-mruby
1
0
Fork 0
mirror of https://github.com/mruby/mruby synced 2026-06-08 16:11:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1227 from bovi/patch-2

Browse Source 
Cosmetic improvements of mrbgems documentation
This commit is contained in:
Yukihiro "Matz" Matsumoto
2013-05-01 18:09:40 -07:00
parent 6f6f0b24d1 1f45b85a0b
commit b3cdcfe27b
1 changed files with 17 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/mrbgems/README.md
+17 -17
View File
@@ -6,7 +6,7 @@ standardised way into mruby.
## Usage
By default mrbgems is currently deactivated. As soon as you add a GEM to your
build configuration (*build_config.rb*), mrbgems will be activated and the
build configuration (i.e. *build_config.rb*), mrbgems will be activated and the
extension integrated.
To add a GEM into the *build_config.rb* add the following line for example:
@@ -25,41 +25,41 @@ A remote GIT repository location for a GEM is also supported:
conf.gem :bitbucket => 'mruby/mrbgems-example', :branch => 'master'
NOTE: ':bitbucket' option supports only git. Hg is unsupported in this version.
NOTE: `:bitbucket` option supports only git. Hg is unsupported in this version.
## GemBox
There are instances when you wish to add a collection of gems into mruby at
once, or be able to substitute gems based on configuration, without having to
add each gem to the *build_config.rb* file. A packaged collection of mrbgems
is called a Gembox. A Gembox is a file that contains a list of gems to load
is called a GemBox. A GemBox is a file that contains a list of gems to load
into mruby, in the same format as if you were adding them to *build_config.rb*
via `config.gem`, but wrapped in an ```Mruby::GemBox``` object. Gemboxes are
loaded into mruby via `config.gembox boxname`.
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*:
MRuby::GemBox.new do |conf|
conf.gem "#{root}/mrbgems/mruby-time"
conf.gem :github => 'masuidrive/mrbgems-example'
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 to be
picked up by mruby.
To use this example Gembox, we save it as 'custom.box' 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 our *build_config.rb* file inside
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.
There are two Gemboxes that ship with mruby: [default](mrbgems/default.gembox)
and [full-core](mrbgems/full-core). The [default](mrbgems/default.gembox) Gembox
contains several core components of mruby, and [full-core](mrbgems/full-core)
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.
## GEM Structure
@@ -80,7 +80,7 @@ The maximal GEM structure looks like this:
The folder *mrblib* contains pure Ruby files to extend mruby. The folder *src*
contains C files to extend mruby. The folder *test* contains C and pure Ruby files
for testing purposes which will be used by ```mrbtest```. *mrbgem.rake* contains
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.
@@ -96,7 +96,7 @@ GEM direcotry. A typical GEM specification could look like this for example:
The mrbgems build process will use this specification to compile Object and Ruby
files. The compilation results will be add to *lib/libmruby.a*. This file is used
by tools like ```mruby``` and ```mirb``` to empower the GEM functionality.
by tools like `mruby` and `mirb` to empower the GEM functionality.
In case your GEM has more complex build requirements you can use
the following options additionally inside of your GEM specification:
@@ -120,7 +120,7 @@ integrate C libraries into mruby.
### Pre-Conditions
mrbgems expects that you have implemented a C method called
```mrb_YOURGEMNAME_gem_init(mrb_state)```. ```YOURGEMNAME``` will be replaced
`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:
@@ -133,7 +133,7 @@ initialisation method could look like this:
### Finalize
mrbgems expects that you have implemented a C method called
```mrb_YOURGEMNAME_gem_final(mrb_state)```. ```YOURGEMNAME``` will be replaced
`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
finalizer method could look like this: