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
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
|
<!-- summary: About Build-time Configurations -->
# mruby configuration macros
## The configuration file
You can do the build configuration in the build configuration file. The default
configuration file is `build_config/default.rb`.
You can specify your own configuration file by the `MRUBY_CONFIG` environment
variable (you can use `CONFIG` for shorthand for `MRUBY_CONFIG`). If the path
doesn't exist, `build_config/${MRUBY_CONFIG}.rb` is used.
## How to use these macros
Just add the configuration value to the `MRuby::Build#defines` attribute.
This is the same for `MRuby::CrossBuild`.
```ruby
# build_config.rb
MRuby::Build.new do |conf|
...
conf.defines << 'MRB_GC_FIXED_ARENA'
conf.defines << 'MRB_NO_METHOD_CACHE'
...
end
```
**_NOTE_**
- Use common definitions (`conf.defines`) instead of per-compiler definitions (e.g., `conf.cc.defines`) unless there is a special reason not to.
- It is now deprecated to edit the `include/mruby/mrbconf.h` file or give it directly as a compiler flag, as was the case before.
## stdio setting
`MRB_NO_STDIO`
- When defined `<stdio.h>` functions won't be used.
- Some features will be disabled when this is enabled:
- `mrb_irep` load/dump from/to file.
- Compiling mruby script from a file.
- Printing features in **src/print.c**.
## Debug macros
`MRB_USE_DEBUG_HOOK`
- When defined code fetch hook and debug OP hook will be enabled.
- When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`.
- Fetch hook will be called before any OP.
- Debug OP hook will be called when dispatching `OP_DEBUG`.
`MRB_DEBUG`
- When defined `mrb_assert*` macro will be defined with macros from `<assert.h>`.
- Could be enabled via `enable_debug` method of `MRuby::Build`.
## Stack configuration
`MRB_STACK_EXTEND_DOUBLING`
- If defined doubles the stack size when extending it.
- Otherwise extends stack with `MRB_STACK_GROWTH`.
`MRB_STACK_GROWTH`
- Default value is `128`.
- Used in stack extending.
- Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined.
`MRB_STACK_MAX`
- Default value is `0x40000 - MRB_STACK_GROWTH`.
- Raises `RuntimeError` when stack size exceeds this value.
## Primitive type configuration
`MRB_USE_FLOAT32`
- When defined single-precision floating-point type(C type `float`) is used as `mrb_float`.
- Otherwise, double-precision floating-point type(C type `double`) is used as `mrb_float`.
`MRB_NO_FLOAT`
- When defined removes floating-point numbers from mruby.
- It makes mruby easier to handle in "Micro-controller without FPU" and "Kernel Space".
`MRB_INT32`
- When defined, or `MRB_INT64` are not defined on 32-bit CPU mode, `mrb_int` will be defined as `int32_t`.
- Conflicts with `MRB_INT64`.
`MRB_INT64`
- When defined, or `MRB_INT32` are not defined on 64-bit CPU mode, `mrb_int` will be defined as `int64_t`.
- Conflicts with `MRB_INT32`.
## Garbage collector configuration
`MRB_GC_STRESS`
- When defined full GC is emitted per each `RBasic` allocation.
- Mainly used in memory manager debugging.
- If defined at the same time as `MRB_DEBUG`, full GC is emitted also per each heap allocation (`mrb_malloc()` or etc.).
This configuration slows down mruby execution by a factor of 2 to 3 or even more.
`MRB_GC_TURN_OFF_GENERATIONAL`
- When defined turns generational GC off by default.
`MRB_GC_FIXED_ARENA`
- When defined used fixed size GC arena.
- Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`.
- Useful tracking unnecessary mruby object allocation.
`MRB_GC_ARENA_SIZE`
- Default value is `100`.
- Ignored when `MRB_GC_FIXED_ARENA` isn't defined.
- Defines fixed GC arena size.
`MRB_HEAP_PAGE_SIZE`
- Default value is `1024`.
- Specifies number of `RBasic` per each heap page.
- To calculate the number of bytes per heap page, it is "(size of management data per heap page) + (size per object) \* `MRB_HEAP_PAGE_SIZE`".
In mruby 3.1.0, the "size of management data per heap page" is 6 words, also "size per object" is 6 words.
For a 32-bit CPU, `(6 * 4) + (6 * 4) * MRB_HEAP_PAGE_SIZE` gives the bytes of size per heap page.
Conversely, for example, to keep the size per heap page to 4 Ki bytes,
calculate `(4096 - (6 * 4)) / (6 * 4)` to specify `MRB_HEAP_PAGE_SIZE=169`.
## Memory pool configuration
`POOL_ALIGNMENT`
- Default value is `4`.
- If you're allocating data types that requires alignment more than default value define the
largest value of required alignment.
`POOL_PAGE_SIZE`
- Default value is `16000`.
- Specifies page size of pool page.
- Smaller the value is increases memory overhead.
## State atexit configuration
`MRB_FIXED_STATE_ATEXIT_STACK`
- If defined enables fixed size `mrb_state` atexit stack.
- Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds
`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value.
`MRB_FIXED_STATE_ATEXIT_STACK_SIZE`
- Default value is `5`.
- If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored.
## `mrb_value` configuration
`MRB_ENDIAN_BIG`
- If defined compiles mruby for big endian machines.
- Used in `MRB_NAN_BOXING`.
- Some mrbgem use this mrbconf.
`MRB_NAN_BOXING`
- If defined represent `mrb_value` in boxed `double`.
- Conflicts with `MRB_USE_FLOAT32` and `MRB_NO_FLOAT`.
`MRB_WORD_BOXING`
- If defined represent `mrb_value` as a word.
- If defined `Float` will be a mruby object with `RBasic`.
## Reduce heap memory configuration
`MRB_USE_ETEXT_RO_DATA_P`
- Use `etext` and `edata` section addresses defined by the linker to detect read-only data.
- Those addresses are widely available, but not portable, nor standardized.
- This macro is defined by default on User-mode Linux.
`MRB_NO_DEFAULT_RO_DATA_P`
- Define this macro when the default `mrb_ro_data_p()` does not work for any reason.
`MRB_USE_CUSTOM_RO_DATA_P`
- Please try if `MRB_USE_LINK_TIME_RO_DATA_P` is not available.
- The `mrb_ro_data_p()` function is implemented by the user in an arbitrary file.
- The prototype declaration is `mrb_bool mrb_ro_data_p(const char *ptr)`.
- Return `TRUE` if `ptr` is in the read-only section, otherwise return `FALSE`.
## Other configuration
`MRB_MALLOC_TRIM`
- call `malloc_trim(0)` for each `mrb_full_gc()` call
`MRB_UTF8_STRING`
- Adds UTF-8 encoding support to character-oriented String instance methods.
- If it isn't defined, they only support the US-ASCII encoding.
`MRB_STR_LENGTH_MAX`
- The maximum length of strings (default 1MB)
- set this value to zero to skip the check
`MRB_ARY_LENGTH_MAX`
- The maximum length of arrays (default 1MB)
- set this value to zero to skip the check
`MRB_FUNCALL_ARGC_MAX`
- Default value is `16`.
- Specifies 4th argument(`argc`) max value of `mrb_funcall`.
- Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`.
`KHASH_DEFAULT_SIZE`
- Default value is `32`.
- Specifies default size of khash table bucket.
- Used in `kh_init_ ## name` function.
`MRB_NO_METHOD_CACHE`
- Disable method cache to save memory.
`MRB_METHOD_CACHE_SIZE`
- Default value is `256`.
- Ignored if `MRB_NO_METHOD_CACHE` is defined.
- Need to be the power of 2.
`MRB_USE_ALL_SYMBOLS`
- Make it available `Symbol.all_symbols` in `mrbgems/mruby-symbol-ext`
- Increase heap memory usage.
`MRB_USE_VM_SWITCH_DISPATCH`
- Turn on switch dispatch in VM loop
|
