[439] | 1 | # mruby configuration macros.
|
---|
| 2 |
|
---|
| 3 | ## How to use these macros.
|
---|
| 4 | You can use mrbconfs with following ways:
|
---|
| 5 | * Write them in `mrbconf.h`.
|
---|
| 6 | * Using compiler flags is preferred when building a cross binaries or multiple mruby binaries
|
---|
| 7 | since it's easier to use different mrbconf per each `MRuby::Build`.
|
---|
| 8 | * Most flags can be enabled by just commenting in.
|
---|
| 9 | * Pass them as compiler flags.
|
---|
| 10 | * Make sure you pass the same flags to all compilers since some mrbconf(e.g., `MRB_GC_FIXED_ARENA`)
|
---|
| 11 | changes `struct` layout and cause memory access error when C and other language(e.g., C++) is mixed.
|
---|
| 12 |
|
---|
| 13 | ## stdio setting.
|
---|
| 14 | `MRB_DISABLE_STDIO`
|
---|
| 15 | * When defined `<stdio.h>` functions won't be used.
|
---|
| 16 | * Some features will be disabled when this is enabled:
|
---|
| 17 | * `mrb_irep` load/dump from/to file.
|
---|
| 18 | * Compiling mruby script from file.
|
---|
| 19 | * Printing features in **src/print.c**.
|
---|
| 20 |
|
---|
| 21 | ## Debug macros.
|
---|
| 22 | `MRB_ENABLE_DEBUG_HOOK`
|
---|
| 23 | * When defined code fetch hook and debug OP hook will be enabled.
|
---|
| 24 | * When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`.
|
---|
| 25 | * Fetch hook will be called before any OP.
|
---|
| 26 | * Debug OP hook will be called when dispatching `OP_DEBUG`.
|
---|
| 27 |
|
---|
| 28 | `MRB_DEBUG`
|
---|
| 29 | * When defined `mrb_assert*` macro will be defined with macros from `<assert.h>`.
|
---|
| 30 | * Could be enabled via `enable_debug` method of `MRuby::Build`.
|
---|
| 31 |
|
---|
| 32 | ## Stack configuration
|
---|
| 33 |
|
---|
| 34 | `MRB_STACK_EXTEND_DOUBLING`
|
---|
| 35 | * If defined doubles the stack size when extending it.
|
---|
| 36 | * Else extends stack with `MRB_STACK_GROWTH`.
|
---|
| 37 |
|
---|
| 38 | `MRB_STACK_GROWTH`
|
---|
| 39 | * Default value is `128`.
|
---|
| 40 | * Used in stack extending.
|
---|
| 41 | * Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined.
|
---|
| 42 |
|
---|
| 43 | `MRB_STACK_MAX`
|
---|
| 44 | * Default value is `0x40000 - MRB_STACK_GROWTH`.
|
---|
| 45 | * Raises `RuntimeError` when stack size exceeds this value.
|
---|
| 46 |
|
---|
| 47 | ## Primitive type configuration.
|
---|
| 48 |
|
---|
| 49 | `MRB_USE_FLOAT`
|
---|
| 50 | * When defined single precision floating point type(C type `float`) is used as `mrb_float`.
|
---|
| 51 | * Else double precision floating point type(C type `double`) is used as `mrb_float`.
|
---|
| 52 |
|
---|
| 53 | `MRB_WITHOUT_FLOAT`
|
---|
| 54 | * When defined removes floating point numbers from mruby.
|
---|
| 55 | * It makes mruby easier to handle in "Microcontroller without FPU" and "Kernel Space".
|
---|
| 56 |
|
---|
| 57 | `MRB_INT32`
|
---|
| 58 | * When defined, or `MRB_INT64` are not defined on 32-bit CPU mode, `mrb_int` will be defined as `int32_t`.
|
---|
| 59 | * Conflicts with `MRB_INT64`.
|
---|
| 60 |
|
---|
| 61 | `MRB_INT64`
|
---|
| 62 | * When defined, or `MRB_INT32` are not defined on 64-bit CPU mode, `mrb_int` will be defined as `int64_t`.
|
---|
| 63 | * Conflicts with `MRB_INT32`.
|
---|
| 64 |
|
---|
| 65 | ## Garbage collector configuration.
|
---|
| 66 |
|
---|
| 67 | `MRB_GC_STRESS`
|
---|
| 68 | * When defined full GC is emitted per each `RBasic` allocation.
|
---|
| 69 | * Mainly used in memory manager debugging.
|
---|
| 70 |
|
---|
| 71 | `MRB_GC_TURN_OFF_GENERATIONAL`
|
---|
| 72 | * When defined turns generational GC by default.
|
---|
| 73 |
|
---|
| 74 | `MRB_GC_FIXED_ARENA`
|
---|
| 75 | * When defined used fixed size GC arena.
|
---|
| 76 | * Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`.
|
---|
| 77 | * Useful tracking unnecessary mruby object allocation.
|
---|
| 78 |
|
---|
| 79 | `MRB_GC_ARENA_SIZE`
|
---|
| 80 | * Default value is `100`.
|
---|
| 81 | * Ignored when `MRB_GC_FIXED_ARENA` isn't defined.
|
---|
| 82 | * Defines fixed GC arena size.
|
---|
| 83 |
|
---|
| 84 | `MRB_HEAP_PAGE_SIZE`
|
---|
| 85 | * Defines value is `1024`.
|
---|
| 86 | * Specifies number of `RBasic` per each heap page.
|
---|
| 87 |
|
---|
| 88 | ## Memory pool configuration.
|
---|
| 89 |
|
---|
| 90 | `POOL_ALIGNMENT`
|
---|
| 91 | * Default value is `4`.
|
---|
| 92 | * If you're allocating data types that requires alignment more than default value define the
|
---|
| 93 | largest value of required alignment.
|
---|
| 94 |
|
---|
| 95 | `POOL_PAGE_SIZE`
|
---|
| 96 | * Default value is `16000`.
|
---|
| 97 | * Specifies page size of pool page.
|
---|
| 98 | * Smaller the value is increases memory overhead.
|
---|
| 99 |
|
---|
| 100 | ## State atexit configuration.
|
---|
| 101 |
|
---|
| 102 | `MRB_FIXED_STATE_ATEXIT_STACK`
|
---|
| 103 | * If defined enables fixed size `mrb_state` atexit stack.
|
---|
| 104 | * Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds
|
---|
| 105 | `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value.
|
---|
| 106 |
|
---|
| 107 | `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`
|
---|
| 108 | * Default value is `5`.
|
---|
| 109 | * If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored.
|
---|
| 110 |
|
---|
| 111 | ## `mrb_value` configuration.
|
---|
| 112 |
|
---|
| 113 | `MRB_ENDIAN_BIG`
|
---|
| 114 | * If defined compiles mruby for big endian machines.
|
---|
| 115 | * Used in `MRB_NAN_BOXING`.
|
---|
| 116 | * Some mrbgem use this mrbconf.
|
---|
| 117 |
|
---|
| 118 | `MRB_NAN_BOXING`
|
---|
| 119 | * If defined represent `mrb_value` in boxed `double`.
|
---|
| 120 | * Conflicts with `MRB_USE_FLOAT` and `MRB_WITHOUT_FLOAT`.
|
---|
| 121 |
|
---|
| 122 | `MRB_WORD_BOXING`
|
---|
| 123 | * If defined represent `mrb_value` as a word.
|
---|
| 124 | * If defined `Float` will be a mruby object with `RBasic`.
|
---|
| 125 |
|
---|
| 126 | ## Instance variable configuration.
|
---|
| 127 | `MRB_IV_SEGMENT_SIZE`
|
---|
| 128 | * Default value is `4`.
|
---|
| 129 | * Specifies size of each segment in segment list.
|
---|
| 130 |
|
---|
| 131 | ## Reduce heap memory configuration.
|
---|
| 132 |
|
---|
| 133 | `MRB_USE_LINK_TIME_RO_DATA_P`
|
---|
| 134 | * Only available on ELF platforms.
|
---|
| 135 | * If you specify the address of a read-only section when creating a symbol or string, that string will be used as it is.
|
---|
| 136 | * Heap memory can be saved.
|
---|
| 137 | * Uses `__ehdr_start` and `__init_array_start`.
|
---|
| 138 | * It must be `__ehdr_start < data_addr < __init_array_start`.
|
---|
| 139 |
|
---|
| 140 | `MRB_USE_CUSTOM_RO_DATA_P`
|
---|
| 141 | * Takes precedence over `MRB_USE_LINK_TIME_RO_DATA_P`.
|
---|
| 142 | * Please try if `MRB_USE_LINK_TIME_RO_DATA_P` is not available.
|
---|
| 143 | * The `mrb_ro_data_p()` function is implemented by the user in an arbitrary file.
|
---|
| 144 | * The prototype declaration is `mrb_bool mrb_ro_data_p(const char *ptr)`.
|
---|
| 145 | * Return `TRUE` if `ptr` is in read-only section, otherwise return `FALSE`.
|
---|
| 146 |
|
---|
| 147 | ## Other configuration.
|
---|
| 148 | `MRB_UTF8_STRING`
|
---|
| 149 | * Adds UTF-8 encoding support to character-oriented String instance methods.
|
---|
| 150 | * If it isn't defined, they only support the US-ASCII encoding.
|
---|
| 151 |
|
---|
| 152 | `MRB_FUNCALL_ARGC_MAX`
|
---|
| 153 | * Default value is `16`.
|
---|
| 154 | * Specifies 4th argument(`argc`) max value of `mrb_funcall`.
|
---|
| 155 | * Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`.
|
---|
| 156 |
|
---|
| 157 | `KHASH_DEFAULT_SIZE`
|
---|
| 158 | * Default value is `32`.
|
---|
| 159 | * Specifies default size of khash table bucket.
|
---|
| 160 | * Used in `kh_init_ ## name` function.
|
---|
| 161 |
|
---|
| 162 | `MRB_STR_BUF_MIN_SIZE`
|
---|
| 163 | * Default value is `128`.
|
---|
| 164 | * Specifies initial capacity of `RString` created by `mrb_str_buf_new` function..
|
---|
| 165 |
|
---|
| 166 | `MRB_METHOD_CACHE`
|
---|
| 167 | * Improve performance for method dispatch.
|
---|
| 168 |
|
---|
| 169 | `MRB_METHOD_CACHE_SIZE`
|
---|
| 170 | * Default value is `128`.
|
---|
| 171 | * Ignored if `MRB_METHOD_CACHE` is not defined.
|
---|
| 172 | * Need to be the power of 2.
|
---|
| 173 |
|
---|
| 174 | `MRB_METHOD_T_STRUCT`
|
---|
| 175 | * Use C struct to represent `mrb_method_t`
|
---|
| 176 | * No `MRB_METHOD_T_STRUCT` requires highest 2 bits of function pointers to be zero
|
---|
| 177 | * Define this macro on machines that use higher bits of pointers
|
---|
| 178 |
|
---|
| 179 | `MRB_ENABLE_ALL_SYMBOLS`
|
---|
| 180 | * Make it available `Symbols.all_symbols` in `mrbgems/mruby-symbol-ext`
|
---|
| 181 | * Increase heap memory usage.
|
---|