blob: 6d5a023bc628ea67a2f579acbe8c0e861e8454f3 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
# 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 the
build configuration (build_config.rb), mrbgems will be activated and the
extension will be integrated.
To add a GEM into the build_config.rb add the following line:
```
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'
```
## 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
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 expects a file called *mrbgem.rake* inside of your GEM directory. A
typical file could for example look like this:
```
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.
### 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. 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) {
struct RClass *class_cextension = mrb_define_module(mrb, "CExtension");
mrb_define_class_method(mrb, class_cextension, "c_method", mrb_c_method, ARGS_NONE());
}
```
### 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
|
