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.

# 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 1.5x growth (minimum MRB_STACK_GROWTH).

MRB_STACK_GROWTH

Default value is 128.
Minimum stack growth size when 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.
On 32-bit platforms, MRB_INT64 requires MRB_NO_BOXING because heap-allocated RInteger needs 8-byte alignment that the GC heap may not guarantee with word or NaN boxing.

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.

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 (natural unit of data for the processor).
Default boxing mode when none is specified.
On 64-bit platforms, floats are inlined using rotation encoding.
On 32-bit platforms, floats are heap-allocated as RFloat objects.

MRB_NO_BOXING

If defined represent mrb_value as a C struct (occupies 2 words).
Most portable but least memory-efficient representation.
Required for MRB_INT64 on 32-bit platforms.
Default for host-debug configuration.

MRB_WORDBOX_NO_INLINE_FLOAT

If defined disables inline float values in word boxing.
All floats are heap-allocated as RFloat objects.
Automatically defined on 32-bit platforms (64-bit double cannot fit in a 32-bit word).
Only meaningful with MRB_WORD_BOXING.

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.
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

Define to provide your own mrb_ro_data_p() implementation.
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_USE_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 1048576).
Set this value to zero to skip the check.

MRB_ARY_LENGTH_MAX

The maximum length of arrays (default 131072).
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_INITIAL_SIZE

Default value is 32.
Specifies initial 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.
Otherwise, computed goto (direct threading) is used when supported by the compiler.

MRB_SYMBOL_LINEAR_THRESHOLD

Default value is 256.
Threshold for switching symbol table from linear search to hash table.

Tuning profiles

Predefined profiles adjust several macros together for specific deployment targets. Define one of the following:

MRB_CONSTRAINED_BASELINE_PROFILE

For micro controllers.
Enables MRB_NO_METHOD_CACHE, reduces KHASH_INITIAL_SIZE to 16, and MRB_HEAP_PAGE_SIZE to 256.

MRB_BASELINE_PROFILE

Default mruby profile. No additional changes.

MRB_MAIN_PROFILE

For desktop computers or workstations.
Increases MRB_METHOD_CACHE_SIZE to 1024 and MRB_HEAP_PAGE_SIZE to 4096.

MRB_HIGH_PROFILE

For long-lived server processes.
Increases MRB_METHOD_CACHE_SIZE to 4096 and MRB_HEAP_PAGE_SIZE to 4096.