Merge pull request #680 from bovi/doc-rake

Adapter mrbgems documentation to rake system

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
 
@@ -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