9 files changed, 178 insertions, 0 deletions
diff --git a/doc/mrbgems/README.md b/doc/mrbgems/README.md
new file mode 100644
index 000000000..7eef38222
--- /dev/null
+++ b/doc/mrbgems/README.md
@@ -0,0 +1,123 @@
+# mrbgems
+
+mrbgems is a library manager to integrate C and Ruby extension in an easy and
+standardised way into mruby.
+
+## 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 all C files and integrates them into the normal mruby
+build process. *README.md* is a short description of your Gem.
+
+All Gems have to be located under *$(MRUBY_ROOT)/mrbgems/g/*.
+
+## C Extension
+
+mruby can be extended with C. It is possible by using the C API to integrate C
+libraries into mruby. You need to use the folder *src* for all C files. Pay
+attention that your *Makefile* has to build the source and also add the object
+files to libmruby.a
+
+### Pre-Conditions
+
+mrbgems will automatically call the *gem-all* make target of your Gem. Make
+sure that you build all files in this target and that you add your object
+files to libmruby.a
+
+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. At the moment only one directory layer is supported. So don't
+use a deeper structure for now!
+
+The *Makefile* is not used for building a Ruby extension. But you still
+should maintain this file so that during the build process the progress
+can be visualized. If you want to do additional things during the build
+process of your Ruby extension you can use the *Makefile* too.
+
+### Example
+
+```
++- ruby_extension_example/
+   |
+   +- mrblib/
+   |  |
+   |  +- example.rb        <- Ruby extension source
+   |
+   +- test/
+   |  |
+   |  +- example.rb        <- Test code for Ruby extension
+   |
+   +- Makefile
+   |
+   +- README.md
+```
+
+## Current Limitations
+
+The following limitations are currently existing:
+
+* Gem _MUST NOT_ have a *src* folder in case it doesn't have a 
+  C extension
+* Gem _MUST NOT_ have a *mrblib* folder in case it doesn't have a 
+  Ruby extension
+* Only Ruby files in the root directory of *mrblib* will be integrated
+* C files in the directory of *src* are overriding object files with
+  the same name.
+
+If you have ideas how to fix these issues without implementing to much
+complexity into the code please provide your code or idea.
diff --git a/doc/mrbgems/c_extension_example/Makefile b/doc/mrbgems/c_extension_example/Makefile
new file mode 100644
index 000000000..b245e9696
--- /dev/null
+++ b/doc/mrbgems/c_extension_example/Makefile
@@ -0,0 +1,12 @@
+include ../../Makefile4gem
+
+GEM := c_extension_example
+
+GEM_C_FILES := $(wildcard $(SRC_DIR)/*.c)
+GEM_OBJECTS := $(patsubst %.c, %.o, $(GEM_C_FILES))
+
+gem-all : $(GEM_OBJECTS)
+	$(AR) rs $(LIBR) $<
+
+gem-clean :
+	-$(RM) $(GEM_OBJECTS)
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..7ebec4f09
--- /dev/null
+++ b/doc/mrbgems/ruby_extension_example/Makefile
@@ -0,0 +1,7 @@
+include ../../Makefile4gem
+
+GEM := ruby_extension_example
+
+gem-all :
+
+gem-clean :
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