mruby-mruby/doc/mrbgems/README.md

# 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 soon as you add a GEM to your
build configuration (*build_config.rb*), mrbgems will be activated and the
extension integrated.

To add a GEM into the build_config.rb add the following line for example:

	conf.gem '/path/to/your/gem/dir'

You can also use a relative path which would be relative from the mruby root:

	conf.gem 'examples/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'

	conf.gem :github => 'masuidrive/mrbgems-example', :branch => 'master'


## 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)
	   |
	   +- 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 C and pure Ruby files
for testing purposes which will be used by ```mrbtest```. *mrbgem.rake* contains
the specification to compile C and Ruby files. *README.md* is a short description
of your GEM.

## Build process

mrbgems expects a specifcation file called *mrbgem.rake* inside of your
GEM direcotry. A typical GEM specification could look like this for example:

	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 specification to compile Object and Ruby
files. The compilation results will be add to *lib/libmruby.a*. This file is used
by tools like ```mruby``` and ```mirb``` to empower the GEM functionality.

In case your GEM has more complex build requirements you can use
the following options additionally inside of your GEM specification:

* spec.cflags (C compiler flags for this GEM)
* spec.mruby_cflags (global C compiler flags for everything)
* spec.mruby_ldflags (global linker flags for everything)
* spec.mruby_libs (global libraries for everything)
* spec.mruby_includes (global includes for everything)
* spec.rbfiles (Ruby files to compile)
* spec.objs (Object files to compile)
* spec.test_rbfiles (Ruby test files for integration into mrbtest)
* spec.test_objs (Object test files for integration into mrbtest)
* spec.test_preload (Initialization files for mrbtest)

## C Extension

mruby can be extended with C. This is possible by using the C API to
integrate C libraries into mruby.

### 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 your GEM. If you call your GEM *c_extension_example*, your
initialisation method could look like this:

	void
	mrb_c_extension_example_gem_init(mrb_state* mrb) {
	  struct RClass *class_cextension = mrb_define_module(mrb, "CExtension");
	  mrb_define_class_method(mrb, class_cextension, "c_method", mrb_c_method, ARGS_NONE());
	}

### Finalize

mrbgems expects that you have implemented a C method called
```mrb_YOURGEMNAME_gem_final(mrb_state)```. ```YOURGEMNAME``` will be replaced
by the name of your GEM. If you call your GEM *c_extension_example*, your
finalizer method could look like this:

	void
	mrb_c_extension_example_gem_final(mrb_state* mrb) {
	  free(someone);
	}

### Example

	+- c_extension_example/
	   |
	   +- src/
	   |  |
	   |  +- example.c         <- C extension source
	   |
	   +- test/
	   |  |
	   |  +- example.rb        <- Test code for C extension
	   |
	   +- mrbgem.rake          <- GEM specification
	   |
	   +- 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.

### Pre-Conditions

none

### Example

	+- ruby_extension_example/
	   |
	   +- mrblib/
	   |  |
	   |  +- example.rb        <- Ruby extension source
	   |
	   +- test/
	   |  |
	   |  +- example.rb        <- Test code for Ruby extension
	   |
	   +- mrbgem.rake          <- GEM specification
	   |
	   +- 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.

### 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
	   |
	   +- mrbgem.rake          <- GEM specification
	   |
	   +- README.md