blob: bb89470137a872143672cbc20a14e54e3d0e500d (
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
|
# 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 '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'
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());
}
### 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
|
