diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/mrbgems/README.md | 118 |
1 files changed, 57 insertions, 61 deletions
diff --git a/doc/mrbgems/README.md b/doc/mrbgems/README.md index 0eaaad6bf..6d5a023bc 100644 --- a/doc/mrbgems/README.md +++ b/doc/mrbgems/README.md @@ -5,21 +5,28 @@ standardised way into mruby. ## Usage -By default mrbgems is currently deactivated. As long as mrbgems is deactivated -there is no overhead inside of the mruby interpreter. +By default mrbgems is currently deactivated. As soon as you add a GEM to the +build configuration (build_config.rb), mrbgems will be activated and the +extension will be integrated. -To activate you have to make the following changes: -* set ```ENABLE_GEMS``` to ```true``` in *$(MRUBY_ROOT)/Makefile* -* activate GEMs in *$(MRUBY_ROOT)/mrbgems/GEMS.active* +To add a GEM into the build_config.rb add the following line: -Notice that we do not need to comment out ```DISABLE_GEMS``` -in *$(MRUBY_ROOT)/include/mrbconf.h*, since this flag will now be included as -a command line flag in *$(MRUBY_ROOT)/Rakefile*. +``` +conf.gem '/path/to/your/gem/dir' +``` + +You can also use a relative path which would be relative from the mruby root: + +``` +conf.gem 'doc/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' +``` -Every activated GEM has to be listed in *GEMS.active*. You have to point to -the GEM directory absolute or relative (based on *mrbgems/g*). It is possible -to point to an alternative activate file: -* set ```ACTIVE_GEMS``` to your customized GEM list in *$(MRUBY_ROOT)/Makefile* ## GEM Structure @@ -28,70 +35,74 @@ The maximal GEM structure looks like this: ``` +- GEM_NAME <- Name of GEM | - +- include/ <- Header files for C extension - | +- mrblib/ <- Source for Ruby extension | +- src/ <- Source for C extension | +- test/ <- Test code (Ruby) | - +- Makefile <- Makefile for GEM + +- mrbgem.rake <- GEM Specification | +- 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 pure Ruby files -for testing purposes which will be used by ```mrbtest```. The *Makefile* contains -rules to build a *mrb-GEMNAME-gem.a* file inside of the GEM directory. Which +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 +rules to build a *libmrb-GEMNAME-gem.a* file inside of the GEM directory. Which will be used for integration into the normal mruby build process. *README.md* is a short description of your GEM. ## Build process -mrbgems will call ```make``` to build and *make clean* to clean your GEM. You -have to build a *mrb-GEMNAME-gem.a* file during this build process. How you -are going to do this is up to you. +mrbgems expects a file called *mrbgem.rake* inside of your GEM directory. A +typical file could for example look like this: -To make your build process more easier and more standardized we suggest -to include *mrbgems/Makefile4gem* which defines some helper rules. In -case you include this Makefile you have to define specific pre-defined -rules like ```gem-all``` for the build process and ```gem-clean``` for -the clean process. There are additional helper rules for specific GEM -examples below. +``` +MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec| + spec.license = 'MIT' + spec.authors = 'mruby developers' +end +``` + +The mrbgems build process will use this file to create a archive file +*libmrb-GEMNAME-gem.a* during the build process. This file will be used +by tools like *mruby* and *mirb* to integrate the GEM functionality. + +In case your GEM has more complex build requirements you can empower +the following options additionally inside of your GEM specification: + +* spec.cflags (flags for the C compiler) +* spec.mruby_cflags (flags for the C compiler) +* spec.mruby_ldflags (flags for the linker) +* spec.mruby_libs (Libraries to include) +* spec.mruby_includes (Directories for include) +* spec.rbfiles (Ruby files to compile) +* spec.objs +* spec.test_rbfiles (Ruby test files for integration into mrbtest) +* spec.test_objs +* spec.test_preload (Initialization files for mrbtest) ## C Extension mruby can be extended with C. It is possible by using the C API to integrate C libraries into mruby. -The *Makefile* is used for building a C extension. You should -define ```GEM``` (GEM name), ```GEM_C_FILES``` (all C files) and -```GEM_OBJECTS``` (all Object files). Pay also attention that your -*Makefile* has to build the object files. You can use -```gem-c-files``` to build a *mrb-GEMNAME-gem.a* out of your -Object code and use ```gem-clean-c-files``` to clean the object files. - ### Pre-Conditions mrbgems expects that you have implemented a C method called ```mrb_YOURGEMNAME_gem_init(mrb_state)```. ```YOURGEMNAME``` will be replaced -by the name of you GEM. The directory name of your GEM is considered also -as the name! If you call your GEM directory *c_extension_example*, your -initialisation method could look like this: +by the name of you GEM. If you call your GEM directory *c_extension_example*, +your initialisation method could look like this: ``` void mrb_c_extension_example_gem_init(mrb_state* mrb) { - _class_cextension = mrb_define_module(mrb, "CExtension"); - mrb_define_class_method(mrb, _class_cextension, "c_method", mrb_c_method, ARGS_NONE()); + struct RClass *class_cextension = mrb_define_module(mrb, "CExtension"); + mrb_define_class_method(mrb, class_cextension, "c_method", mrb_c_method, ARGS_NONE()); } ``` -mrbgems will also use the *gem-clean* make target to clean up your GEM. Implement -this target with the necessary rules! - ### Example ``` @@ -105,7 +116,7 @@ this target with the necessary rules! | | | +- example.rb <- Test code for C extension | - +- Makefile <- Build rules for C extension + +- mrbgem.rake <- GEM specification | +- README.md ``` @@ -116,17 +127,9 @@ 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. -The *Makefile* is used for building a Ruby extension. You should define -```GEM``` (GEM name) and *GEM_RB_FILES* (all Ruby files). You can use -```gem-rb-files``` to build a *mrb-GEMNAME-gem.a* out of your Ruby code and use -```gem-clean-rb-files``` to clean the generated C files. - ### Pre-Conditions -mrbgems will automatically call the ```gem-all``` make target of your GEM. - -mrbgems will also use the ```gem-clean``` make target to clean up your GEM. Implement -this target with the necessary rules! +none ### Example @@ -141,7 +144,7 @@ this target with the necessary rules! | | | +- example.rb <- Test code for Ruby extension | - +- Makefile + +- mrbgem.rake <- GEM specification | +- README.md ``` @@ -152,13 +155,6 @@ 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. -The *Makefile* is used for building a C and Ruby extension. You should -define ```GEM``` (GEM name), ```GEM_C_FILES``` (all C files), -```GEM_OBJECTS``` (all Object files) and ```GEM_RB_FILES``` (all Ruby -files). You can use ```gem-c-and-rb-files``` to build a -*mrb-GEMNAME-gem.a* out of your Object and Ruby code. Use -```gem-clean-c-and-rb-files``` to clean the generated C files. - ### Pre-Conditions See C and Ruby example. @@ -180,6 +176,6 @@ See C and Ruby example. | | | +- example.rb <- Test code for C and Ruby extension | - +- Makefile + +- mrbgem.rake <- GEM specification | +- README.md |