blob: 480e034a540c977f20a24b6740fad3ad1cbff7ff (
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
|
# 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 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.
All GEMs have to be located under *$(MRUBY_ROOT)/mrbgems/g/*.
## Build process
mrbgems will call *make* to build and *make clean* to clean your GEM. You
have to create *gem.a* file during the build process. How you are going
to do this is you decision.
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 *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
define *GEM* (GEM name) and *GEM_RB_FILES* (all Ruby files). You can use
*gem-rb-files* to build a *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 *gem.a* out of your Object and Ruby code
and 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
|
