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

Adapter mrbgems documentation to rake system

Browse Source
This commit is contained in:
Daniel Bovensiepen
2013-01-03 11:58:17 +08:00
parent 65901c3dbd
commit b347bcac61
1 changed files with 57 additions and 61 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/mrbgems/README.md
+57 -61
View File
@@ -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
@@ -27,8 +34,6 @@ The maximal GEM structure looks like this:
```
+- GEM_NAME <- Name of GEM
|
+- include/ <- Header files for C extension
|
+- mrblib/ <- Source for Ruby extension
|
@@ -36,62 +41,68 @@ The maximal GEM structure looks like this:
|
+- 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