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_INT16`
  54 * When defined `int16_t` will be defined as `mrb_int`.
  55 * Conflicts with `MRB_INT64`.
  56
  57 `MRB_INT64`
  58 * When defined `int64_t` will be defined as `mrb_int`.
  59 * Conflicts with `MRB_INT16`.
  60 * When `MRB_INT16` or `MRB_INT64` isn't defined `int`(most of the times 32-bit integer)
  61 will be defined as `mrb_int`.
  62
  63 ## Garbage collector configuration.
  64
  65 `MRB_GC_STRESS`
  66 * When defined full GC is emitted per each `RBasic` allocation.
  67 * Mainly used in memory manager debugging.
  68
  69 `MRB_GC_TURN_OFF_GENERATIONAL`
  70 * When defined turns generational GC by default.
  71
  72 `MRB_GC_FIXED_ARENA`
  73 * When defined used fixed size GC arena.
  74 * Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`.
  75 * Useful tracking unnecessary mruby object allocation.
  76
  77 `MRB_GC_ARENA_SIZE`
  78 * Default value is `100`.
  79 * Ignored when `MRB_GC_FIXED_ARENA` isn't defined.
  80 * Defines fixed GC arena size.
  81
  82 `MRB_HEAP_PAGE_SIZE`
  83 * Defines value is `1024`.
  84 * Specifies number of `RBasic` per each heap page.
  85
  86 ## Memory pool configuration.
  87
  88 `POOL_ALIGNMENT`
  89 * Default value is `4`.
  90 * If you're allocating data types that requires alignment more than default value define the
  91 largest value of required alignment.
  92
  93 `POOL_PAGE_SIZE`
  94 * Default value is `16000`.
  95 * Specifies page size of pool page.
  96 * Smaller the value is increases memory overhead.
  97
  98 ## State atexit configuration.
  99
 100 `MRB_FIXED_STATE_ATEXIT_STACK`
 101 * If defined enables fixed size `mrb_state` atexit stack.
 102 * Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds
 103 `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value.
 104
 105 `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`
 106 * Default value is `5`.
 107 * If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored.
 108
 109 ## `mrb_value` configuration.
 110
 111 `MRB_ENDIAN_BIG`
 112 * If defined compiles mruby for big endian machines.
 113 * Used in `MRB_NAN_BOXING`.
 114 * Some mrbgem use this mrbconf.
 115
 116 `MRB_NAN_BOXING`
 117 * If defined represent `mrb_value` in boxed `double`.
 118 * Conflicts with `MRB_USE_FLOAT`.
 119
 120 `MRB_WORD_BOXING`
 121 * If defined represent `mrb_value` as a word.
 122 * If defined `Float` will be a mruby object with `RBasic`.
 123
 124 ## Instance variable configuration.
 125 `MRB_IV_SEGMENT_SIZE`
 126 * Default value is `4`.
 127 * Specifies size of each segment in segment list.
 128
 129 ## Other configuration.
 130 `MRB_UTF8_STRING`
 131 * Adds UTF-8 encoding support to character-oriented String instance methods.
 132 * If it isn't defined, they only support the US-ASCII encoding.
 133
 134 `MRB_FUNCALL_ARGC_MAX`
 135 * Default value is `16`.
 136 * Specifies 4th argument(`argc`) max value of `mrb_funcall`.
 137 * Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`.
 138
 139 `KHASH_DEFAULT_SIZE`
 140 * Default value is `32`.
 141 * Specifies default size of khash table bucket.
 142 * Used in `kh_init_ ## name` function.
 143
 144 `MRB_STR_BUF_MIN_SIZE`
 145 * Default value is `128`.
 146 * Specifies initial capacity of `RString` created by `mrb_str_buf_new` function..