mirror of
https://github.com/mruby/mruby
synced 2026-06-08 16:11:16 +00:00
Yukihiro "Matz" Matsumoto
3e5e84e391
The HAL was integrated into mruby-task/ports/{posix,win}/ in
be6413f0d8 and the function names were updated in 610ff67906, but
the docs and one header still described the old separate-gem layout:
- mrbgems/mruby-task/README.md described hal-posix-task and
hal-win-task as separate gems, used the pre-rename function
names (mrb_task_hal_*), and omitted mrb_hal_task_sleep_us.
Rewrote the HAL section to match the current ports/ model.
- mrbgems/mruby-task/include/task.h had three orphan declarations
(mrb_task_hal_init / _final / _idle_cpu) from before the
rename. Removed; the real declarations are in task_hal.h.
- mrbgems/mruby-task/include/task_hal.h had a comment referring
to the removed hal-* gems.
- doc/guides/amalgamation.md listed hal-posix-io and hal-posix-task
as platform-specific gems alongside mruby-io and mruby-task; both
are now ports under the parent gem.
Reported by Asmod4n in #6825.
Co-authored-by: Claude <noreply@anthropic.com>
154 lines
4.0 KiB
Markdown
154 lines
4.0 KiB
Markdown
<!-- summary: About Amalgamation (Single-File Build) -->
|
|
|
|
# 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](#platform-dependent-gems) below)
|
|
|
|
## Generating Amalgamation
|
|
|
|
```console
|
|
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:
|
|
|
|
```console
|
|
MRUBY_CONFIG=build_config/minimal.rb rake amalgam
|
|
```
|
|
|
|
## Using the Amalgamation
|
|
|
|
### Basic Usage
|
|
|
|
```c
|
|
#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
|
|
|
|
```console
|
|
gcc -I./build/host/amalgam your_app.c ./build/host/amalgam/mruby.c -o your_app -lm
|
|
```
|
|
|
|
For optimized builds:
|
|
|
|
```console
|
|
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 the active `ports/<name>/` HAL)
|
|
- `mruby-task` (with the active `ports/<name>/` HAL)
|
|
|
|
### Platform-Dependent Gems
|
|
|
|
Gems that use a HAL (Hardware Abstraction Layer) include
|
|
platform-specific code in the amalgamation. For example, if
|
|
`mruby-io` selects its POSIX port 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:
|
|
|
|
```ruby
|
|
# 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:
|
|
|
|
```console
|
|
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
|
|
|
|
1. Core sources (`src/*.c`)
|
|
2. Gem sources (`mrbgems/*/src/*.c` or `core/*.c`)
|
|
3. Generated mrblib (`build/*/mrblib/mrblib.c`)
|
|
4. Gem initialization (`build/*/mrbgems/gem_init.c`)
|