third-party/mruby/doc/guides/mrbconf.md

   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.