diff options
Diffstat (limited to 'doc/mrbgems/README.md')
| -rw-r--r-- | doc/mrbgems/README.md | 151 |
1 files changed, 97 insertions, 54 deletions
diff --git a/doc/mrbgems/README.md b/doc/mrbgems/README.md index 7ac225730..040687333 100644 --- a/doc/mrbgems/README.md +++ b/doc/mrbgems/README.md @@ -10,20 +10,21 @@ 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: - - conf.gem '/path/to/your/gem/dir' +```ruby +conf.gem '/path/to/your/gem/dir' +``` You can also use a relative path which would be relative from the mruby root: - - conf.gem 'examples/mrbgems/ruby_extension_example' +```ruby +conf.gem 'examples/mrbgems/ruby_extension_example' +``` A remote GIT repository location for a GEM is also supported: - - conf.gem :git => 'https://github.com/masuidrive/mrbgems-example.git', :branch => 'master' - - conf.gem :github => 'masuidrive/mrbgems-example', :branch => 'master' - - conf.gem :bitbucket => 'mruby/mrbgems-example', :branch => 'master' +```ruby +conf.gem :git => 'https://github.com/masuidrive/mrbgems-example.git', :branch => 'master' +conf.gem :github => 'masuidrive/mrbgems-example', :branch => 'master' +conf.gem :bitbucket => 'mruby/mrbgems-example', :branch => 'master' +``` To pull all gems from remote GIT repository on build, call ```./minirake -p```, or ```./minirake --pull-gems```. @@ -41,11 +42,12 @@ 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*: - - MRuby::GemBox.new do |conf| - conf.gem "#{root}/mrbgems/mruby-time" - conf.gem :github => 'masuidrive/mrbgems-example' - end +```ruby +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 must be saved with a *.gembox* extension inside the *mrbgems* directory to to be @@ -54,16 +56,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 our *build_config.rb* file inside the build block: - - conf.gembox 'custom' - +```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 absolute path like below. - - conf.gembox "#{ENV["HOME"]}/mygemboxes/custom" +specify an absolute path like below. +```ruby +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 @@ -76,6 +79,8 @@ The maximal GEM structure looks like this: +- GEM_NAME <- Name of GEM | + +- include/ <- Header for Ruby extension (will exported) + | +- mrblib/ <- Source for Ruby extension | +- src/ <- Source for C extension @@ -87,20 +92,22 @@ The maximal GEM structure looks like this: +- README.md <- Readme for GEM 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 -the specification to compile C and Ruby files. *README.md* is a short description -of your GEM. +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 GEM directory. A typical GEM specification could look like this for example: - - MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| - spec.license = 'MIT' - spec.author = 'mruby developers' - end +```ruby +MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| + spec.license = 'MIT' + spec.author = 'mruby developers' + spec.summary = 'Example mrbgem using C and ruby' +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 @@ -113,29 +120,32 @@ information purpose: * `spec.author` or `spec.authors` (Developer name or a list of them) * `spec.version` (Current version) * `spec.description` (Detailed description) -* `spec.summary` (Short summary) +* `spec.summary` + * One line short description of mrbgem. + * Printed in build summary of rake when set. * `spec.homepage` (Homepage) * `spec.requirements` (External requirements as information for user) -The license and author properties are required in every GEM! +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' + spec.author = 'mruby developers' - MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| - spec.license = 'MIT' - spec.author = 'mruby developers' + # Add GEM dependency mruby-parser. + # The version must be between 1.0.0 and 1.5.2 . + spec.add_dependency('mruby-parser', '>= 1.0.0', '<= 1.5.2') - # Add GEM dependency mruby-parser. - # The version must be between 1.0.0 and 1.5.2 . - spec.add_dependency('mruby-parser', '>= 1.0.0', '<= 1.5.2') + # Use any version of mruby-uv from github. + spec.add_dependency('mruby-uv', '>= 0.0.0', :github => 'mattn/mruby-uv') - # Use any version of mruby-uv from github. - spec.add_dependency('mruby-uv', '>= 0.0.0', :github => 'mattn/mruby-uv') - - # Use latest mruby-onig-regexp from github. (version requirements can be ignored) - spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp') - end + # Use latest mruby-onig-regexp from github. (version requirements can be ignored) + spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp') +end +``` The version requirements and default gem information are optional. @@ -159,6 +169,23 @@ Its format is same as argument of method `MRuby::Build#gem`, expect that it can' When a special version of depedency is required, use `MRuby::Build#gem` in *build_config.rb* 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' + spec.author = 'John Doe' + + spec.add_conflict 'mruby-onig-regexp', '> 0.0.0' + spec.add_conflict 'mruby-hs-regexp' + spec.add_conflict 'mruby-pcre-regexp' + spec.add_conflict 'mruby-regexp-pcre' +end +``` + In case your GEM has more complex build requirements you can use the following options additionally inside of your GEM specification: @@ -173,6 +200,19 @@ the following options additionally inside of your GEM specification: * `spec.test_objs` (Object test files for integration into mrbtest) * `spec.test_preload` (Initialization files for mrbtest) +### include_paths and depencency + +Your GEM can export include paths to another GEMs that depends on your GEM. +By default, `/...absolute path.../{GEM_NAME}/include` will be exported. +So it is recommended not to put GEM's local header files on include/. + +These exports are retroactive. +For example: when B depends to C and A depends to B, A will get include paths exported by C. + +Exported include_paths are automatically appended to GEM local include_paths by Minirake. +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 @@ -184,12 +224,13 @@ 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: - - void - mrb_c_extension_example_gem_init(mrb_state* mrb) { - struct RClass *class_cextension = mrb_define_module(mrb, "CExtension"); - mrb_define_class_method(mrb, class_cextension, "c_method", mrb_c_method, MRB_ARGS_NONE()); - } +```C +void +mrb_c_extension_example_gem_init(mrb_state* mrb) { + struct RClass *class_cextension = mrb_define_module(mrb, "CExtension"); + mrb_define_class_method(mrb, class_cextension, "c_method", mrb_c_method, MRB_ARGS_NONE()); +} +``` ### Finalize @@ -198,10 +239,12 @@ mrbgems expects that you have implemented a C method called by the name of your GEM. If you call your GEM *c_extension_example*, your finalizer method could look like this: - void - mrb_c_extension_example_gem_final(mrb_state* mrb) { - free(someone); - } +```C +void +mrb_c_extension_example_gem_final(mrb_state* mrb) { + free(someone); +} +``` ### Example |