Amalgamation

Amalgamation combines all mruby source files into a single mruby.c and mruby.h for easy embedding, similar to SQLite's distribution model.

Benefits

Simple integration: Just two files to add to your project
Single compilation unit: Enables better compiler optimization
No build system required: Compile directly with any C compiler
Portable: No external dependencies beyond standard C library (but see Platform-Dependent Gems below)

Generating Amalgamation

rake amalgam

Output files are generated in build/<target>/amalgam/:

mruby.h - All headers concatenated in dependency order
mruby.c - All sources concatenated (core + gems + mrblib)

With Custom Configuration

The amalgamation includes gems specified in your build configuration:

MRUBY_CONFIG=build_config/minimal.rb rake amalgam

Using the Amalgamation

Basic Usage

#include "mruby.h"

int main(void) {
  mrb_state *mrb = mrb_open();
  mrb_load_string(mrb, "puts 'Hello from mruby!'");
  mrb_close(mrb);
  return 0;
}

Compiling

gcc -I./build/host/amalgam your_app.c ./build/host/amalgam/mruby.c -o your_app -lm

For optimized builds:

gcc -O2 -DNDEBUG -I./build/host/amalgam your_app.c ./build/host/amalgam/mruby.c -o your_app -lm

Gem Compatibility

Known Working Gems

The following gems work with amalgamation:

mruby-compiler - Required for mrb_load_string
mruby-eval - eval, Binding
mruby-array-ext, mruby-string-ext, mruby-hash-ext
mruby-numeric-ext, mruby-range-ext, mruby-symbol-ext
mruby-proc-ext, mruby-kernel-ext, mruby-object-ext, mruby-class-ext
mruby-enum-ext, mruby-compar-ext
mruby-error, mruby-math, mruby-struct
mruby-bigint, mruby-rational, mruby-complex
mruby-io (with hal-posix-io)
mruby-task (with hal-posix-task)

Platform-Dependent Gems

Gems that use a HAL (Hardware Abstraction Layer) include platform-specific code in the amalgamation. For example, if mruby-io selects hal-posix-io on Linux, the generated mruby.c contains POSIX-specific code and cannot be compiled on Windows.

If you need amalgamated files for multiple platforms, generate them separately for each target platform (or cross-build configuration).

Excluded Gems

Binary gems (mruby-bin-*) are automatically excluded as they contain their own main() function. The amalgamation produces a library, not an executable.

Example Configuration

A minimal configuration for amalgamation:

# build_config/amalgam.rb
MRuby::Build.new do |conf|
  conf.toolchain :gcc

  conf.gem core: 'mruby-compiler'
  conf.gem core: 'mruby-error'
  conf.gem core: 'mruby-eval'
  conf.gem core: 'mruby-array-ext'
  conf.gem core: 'mruby-string-ext'
  conf.gem core: 'mruby-hash-ext'
  conf.gem core: 'mruby-io'
end

Generate with:

MRUBY_CONFIG=build_config/amalgam.rb rake amalgam

Output Sizes

Typical sizes depend on included gems:

mruby.h: 200-500 KB
mruby.c: 2-4 MB

Technical Details

Header Processing

Include guards are stripped to allow concatenation
Headers are ordered by dependency (foundation types first)
Internal includes are commented out (already in mruby.h)

Source Processing

Sources are concatenated in proper initialization order
X-macro headers (like mruby/ops.h) are inlined at each use
Local includes (.cstub files) are automatically inlined
Generated files (mrblib.c, gem_init.c) are included

Gem Defines

Gems that add preprocessor defines affecting core structures are automatically detected and included at the top of mruby.h. Supported patterns: MRB_USE_*, MRB_UTF8_*, HAVE_MRUBY_*.

Build Order

Core sources (src/*.c)
Gem sources (mrbgems/*/src/*.c or core/*.c)
Generated mrblib (build/*/mrblib/mrblib.c)
Gem initialization (build/*/mrbgems/gem_init.c)