diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/mrbgems/README.md | 179 | ||||
| -rw-r--r-- | doc/mrbgems/c_and_ruby_extension_example/Makefile | 12 | ||||
| -rw-r--r-- | doc/mrbgems/c_and_ruby_extension_example/README.md | 4 | ||||
| -rw-r--r-- | doc/mrbgems/c_and_ruby_extension_example/mrblib/example.rb | 5 | ||||
| -rw-r--r-- | doc/mrbgems/c_and_ruby_extension_example/src/example.c | 17 | ||||
| -rw-r--r-- | doc/mrbgems/c_and_ruby_extension_example/test/example.rb | 7 | ||||
| -rw-r--r-- | doc/mrbgems/c_extension_example/Makefile | 10 | ||||
| -rw-r--r-- | doc/mrbgems/c_extension_example/README.md | 4 | ||||
| -rw-r--r-- | doc/mrbgems/c_extension_example/src/example.c | 17 | ||||
| -rw-r--r-- | doc/mrbgems/c_extension_example/test/example.rb | 3 | ||||
| -rw-r--r-- | doc/mrbgems/ruby_extension_example/Makefile | 9 | ||||
| -rw-r--r-- | doc/mrbgems/ruby_extension_example/README.md | 4 | ||||
| -rw-r--r-- | doc/mrbgems/ruby_extension_example/mrblib/example.rb | 5 | ||||
| -rw-r--r-- | doc/mrbgems/ruby_extension_example/test/example.rb | 3 |
14 files changed, 279 insertions, 0 deletions
diff --git a/doc/mrbgems/README.md b/doc/mrbgems/README.md new file mode 100644 index 000000000..c11e8a05f --- /dev/null +++ b/doc/mrbgems/README.md @@ -0,0 +1,179 @@ +# mrbgems + +mrbgems is a library manager to integrate C and Ruby extension in an easy and +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. + +To activate you have to make the following changes: +* set *ENABLE_GEMS* to *true* in *$(MRUBY_ROOT)/Makefile* +* define *ENABLE_GEMS* in *$(MRUBY_ROOT)/include/mrbconf.h* +* activate GEMs in *$(MRUBY_ROOT)/mrbgems/GEMS.active* + +Every activated GEM has to be listed with his absolute path in *GEMS.active*. It +is possible to point to an alternative activate file: +* set *ACTIVE_GEMS* to your customized GEM list in *$(MRUBY_ROOT)/Makefile* + +## GEM Structure + +The maximal GEM structure looks like this: + +``` ++- GEM_NAME <- Name of GEM + | + +- mrblib/ <- Source for Ruby extension + | + +- src/ <- Source for C extension + | + +- test/ <- Test code (Ruby) + | + +- Makefile <- Makefile for GEM + | + +- 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 *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. + +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. + +## 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: + +``` +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()); +} +``` + +mrbgems will also use the *gem-clean* make target to clean up your GEM. Implement +this target with the necessary rules! + +### Example + +``` ++- c_extension_example/ + | + +- src/ + | | + | +- example.c <- C extension source + | + +- test/ + | | + | +- example.rb <- Test code for C extension + | + +- Makefile <- Build rules for C extension + | + +- 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* +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! + +### Example + +``` ++- ruby_extension_example/ + | + +- mrblib/ + | | + | +- example.rb <- Ruby extension source + | + +- test/ + | | + | +- example.rb <- Test code for Ruby extension + | + +- Makefile + | + +- README.md +``` + +## 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. + +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. + +### Example + +``` ++- c_and_ruby_extension_example/ + | + +- mrblib/ + | | + | +- example.rb <- Ruby extension source + | + +- src/ + | | + | +- example.c <- C extension source + | + +- test/ + | | + | +- example.rb <- Test code for C and Ruby extension + | + +- Makefile + | + +- README.md diff --git a/doc/mrbgems/c_and_ruby_extension_example/Makefile b/doc/mrbgems/c_and_ruby_extension_example/Makefile new file mode 100644 index 000000000..57912a936 --- /dev/null +++ b/doc/mrbgems/c_and_ruby_extension_example/Makefile @@ -0,0 +1,12 @@ +GEM := c_and_ruby_extension_example + +include $(MAKEFILE_4_GEM) + +GEM_C_FILES := $(wildcard $(SRC_DIR)/*.c) +GEM_OBJECTS := $(patsubst %.c, %.o, $(GEM_C_FILES)) + +GEM_RB_FILES := $(wildcard $(MRB_DIR)/*.rb) + +gem-all : $(GEM_OBJECTS) gem-c-and-rb-files + +gem-clean : gem-clean-c-and-rb-files diff --git a/doc/mrbgems/c_and_ruby_extension_example/README.md b/doc/mrbgems/c_and_ruby_extension_example/README.md new file mode 100644 index 000000000..0b428b0b6 --- /dev/null +++ b/doc/mrbgems/c_and_ruby_extension_example/README.md @@ -0,0 +1,4 @@ +C and Ruby Extension Example +========= + +This is an example gem which implements a C and Ruby extension. diff --git a/doc/mrbgems/c_and_ruby_extension_example/mrblib/example.rb b/doc/mrbgems/c_and_ruby_extension_example/mrblib/example.rb new file mode 100644 index 000000000..0c2d3c7d1 --- /dev/null +++ b/doc/mrbgems/c_and_ruby_extension_example/mrblib/example.rb @@ -0,0 +1,5 @@ +class RubyExtension + def CRubyExtension.ruby_method + puts "A Ruby Extension" + end +end diff --git a/doc/mrbgems/c_and_ruby_extension_example/src/example.c b/doc/mrbgems/c_and_ruby_extension_example/src/example.c new file mode 100644 index 000000000..178514ffe --- /dev/null +++ b/doc/mrbgems/c_and_ruby_extension_example/src/example.c @@ -0,0 +1,17 @@ +#include <mruby.h> +#include <stdio.h> + +static struct RClass *_class_cextension; + +static mrb_value +mrb_c_method(mrb_state *mrb, mrb_value self) +{ + puts("A C Extension"); + return self; +} + +void +mrb_c_and_ruby_extension_example_gem_init(mrb_state* mrb) { + _class_cextension = mrb_define_module(mrb, "CRubyExtension"); + mrb_define_class_method(mrb, _class_cextension, "c_method", mrb_c_method, ARGS_NONE()); +} diff --git a/doc/mrbgems/c_and_ruby_extension_example/test/example.rb b/doc/mrbgems/c_and_ruby_extension_example/test/example.rb new file mode 100644 index 000000000..fffad710f --- /dev/null +++ b/doc/mrbgems/c_and_ruby_extension_example/test/example.rb @@ -0,0 +1,7 @@ +assert('C and Ruby Extension Example 1') do + CRubyExtension.respond_to? :c_method +end + +assert('C and Ruby Extension Example 2') do + CRubyExtension.respond_to? :ruby_method +end diff --git a/doc/mrbgems/c_extension_example/Makefile b/doc/mrbgems/c_extension_example/Makefile new file mode 100644 index 000000000..339669970 --- /dev/null +++ b/doc/mrbgems/c_extension_example/Makefile @@ -0,0 +1,10 @@ +GEM := c_extension_example + +include $(MAKEFILE_4_GEM) + +GEM_C_FILES := $(wildcard $(SRC_DIR)/*.c) +GEM_OBJECTS := $(patsubst %.c, %.o, $(GEM_C_FILES)) + +gem-all : $(GEM_OBJECTS) gem-c-files + +gem-clean : gem-clean-c-files diff --git a/doc/mrbgems/c_extension_example/README.md b/doc/mrbgems/c_extension_example/README.md new file mode 100644 index 000000000..3803c2065 --- /dev/null +++ b/doc/mrbgems/c_extension_example/README.md @@ -0,0 +1,4 @@ +C Extension Example +========= + +This is an example gem which implements a C extension. diff --git a/doc/mrbgems/c_extension_example/src/example.c b/doc/mrbgems/c_extension_example/src/example.c new file mode 100644 index 000000000..9f0b07839 --- /dev/null +++ b/doc/mrbgems/c_extension_example/src/example.c @@ -0,0 +1,17 @@ +#include <mruby.h> +#include <stdio.h> + +static struct RClass *_class_cextension; + +static mrb_value +mrb_c_method(mrb_state *mrb, mrb_value self) +{ + puts("A C Extension"); + return self; +} + +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()); +} diff --git a/doc/mrbgems/c_extension_example/test/example.rb b/doc/mrbgems/c_extension_example/test/example.rb new file mode 100644 index 000000000..367d18029 --- /dev/null +++ b/doc/mrbgems/c_extension_example/test/example.rb @@ -0,0 +1,3 @@ +assert('C Extension Example') do + CExtension.respond_to? :c_method +end diff --git a/doc/mrbgems/ruby_extension_example/Makefile b/doc/mrbgems/ruby_extension_example/Makefile new file mode 100644 index 000000000..9c5026744 --- /dev/null +++ b/doc/mrbgems/ruby_extension_example/Makefile @@ -0,0 +1,9 @@ +GEM := ruby_extension_example + +include $(MAKEFILE_4_GEM) + +GEM_RB_FILES := $(wildcard $(MRB_DIR)/*.rb) + +gem-all : gem-rb-files + +gem-clean : gem-clean-rb-files diff --git a/doc/mrbgems/ruby_extension_example/README.md b/doc/mrbgems/ruby_extension_example/README.md new file mode 100644 index 000000000..906a0d8f2 --- /dev/null +++ b/doc/mrbgems/ruby_extension_example/README.md @@ -0,0 +1,4 @@ +Pure Ruby Extension Example +========= + +This is an example gem which implements a pure Ruby extension. diff --git a/doc/mrbgems/ruby_extension_example/mrblib/example.rb b/doc/mrbgems/ruby_extension_example/mrblib/example.rb new file mode 100644 index 000000000..b07a2b580 --- /dev/null +++ b/doc/mrbgems/ruby_extension_example/mrblib/example.rb @@ -0,0 +1,5 @@ +class RubyExtension + def RubyExtension.ruby_method + puts "A Ruby Extension" + end +end diff --git a/doc/mrbgems/ruby_extension_example/test/example.rb b/doc/mrbgems/ruby_extension_example/test/example.rb new file mode 100644 index 000000000..0c1b63469 --- /dev/null +++ b/doc/mrbgems/ruby_extension_example/test/example.rb @@ -0,0 +1,3 @@ +assert('Ruby Extension Example') do + RubyExtension.respond_to? :ruby_method +end |