merman-ffi

C ABI bindings for embedding merman in non-Rust hosts.

merman is a headless Rust implementation of Mermaid diagram parsing, layout, and rendering. It is intended for servers, CLIs, mobile apps, desktop apps, and other environments that need Mermaid output without launching a browser. The main library can produce semantic JSON, layout JSON, SVG, terminal text, and raster formats depending on enabled features.

Start with the main project README for product scope and diagram coverage:

• Repository: https://github.com/Latias94/merman
• Project README: https://github.com/Latias94/merman
• Rust library: https://crates.io/crates/merman
• CLI: https://crates.io/crates/merman-cli
• Coverage status: https://github.com/Latias94/merman/blob/main/docs/alignment/STATUS.md

This crate exposes the low-level stable boundary described by docs/bindings/FFI_PROTOCOL.md. Higher-level generated bindings such as UniFFI should sit above the same behavior, not replace this C ABI.

Build

From the workspace:

cargo build -p merman-ffi --release

The crate builds cdylib, staticlib, and rlib artifacts. Include include/merman.h from C or C-compatible hosts.

Optional features:

cargo build -p merman-ffi --release --features ratex-math
cargo build -p merman-ffi --release --features raster,ratex-math

The first C ABI release candidate exposes SVG, ASCII text, semantic JSON, layout JSON, validation JSON, and binding metadata. Native raster byte outputs are intentionally split into a later ABI lane.

Minimal C Usage

#include "merman.h"

static const uint8_t source[] = "flowchart TD\nA[Hello] --> B[World]";

MermanResult result = merman_render_svg(source, sizeof(source) - 1, NULL, 0);
if (result.code == MERMAN_OK) {
    /* result.data contains UTF-8 SVG bytes. */
}
merman_buffer_free(result.data);

Every non-empty MermanResult.data buffer must be freed exactly once with merman_buffer_free. Do not use free, delete, or a host runtime allocator for buffers returned by Rust.

For repeated calls with the same options, create a reusable engine:

MermanEngineResult engine = merman_engine_new(NULL, 0);
if (engine.code != MERMAN_OK) {
    /* engine.data contains UTF-8 JSON error bytes. */
    merman_buffer_free(engine.data);
    return;
}

MermanResult result = merman_engine_render_svg(engine.engine, source, sizeof(source) - 1);
merman_buffer_free(result.data);
merman_engine_free(engine.engine);

Example

examples/render_svg.c is a small C consumer that renders a flowchart to SVG through the C ABI. examples/render_svg_engine.c shows the reusable engine/context API for repeated calls with shared options.

On macOS or Linux:

cargo build -p merman-ffi --release
cc -I crates/merman-ffi/include \
  crates/merman-ffi/examples/render_svg.c \
  -L target/release -lmerman_ffi \
  -Wl,-rpath,"$PWD/target/release" \
  -o target/merman-ffi-render-svg
target/merman-ffi-render-svg

To compile the reusable-engine example, replace render_svg.c with render_svg_engine.c in the same command.

Entry Points

• merman_abi_version
• merman_package_version
• merman_buffer_struct_size
• merman_result_struct_size
• merman_engine_result_struct_size
• merman_engine_new
• merman_engine_free
• merman_engine_render_svg
• merman_engine_render_ascii
• merman_engine_parse_json
• merman_engine_layout_json
• merman_engine_validate_json
• merman_render_svg
• merman_render_ascii
• merman_parse_json
• merman_layout_json
• merman_validate_json
• merman_supported_diagrams_json
• merman_ascii_supported_diagrams_json
• merman_supported_themes_json
• merman_supported_host_theme_presets_json
• merman_buffer_free

See include/merman.h for declarations and docs/bindings/FFI_PROTOCOL.md for result codes, options JSON, threading, and compatibility rules.

Higher-level platform wrappers:

• Apple SwiftPM: docs/bindings/APPLE_SWIFT.md
• Android JNI/Kotlin: docs/bindings/ANDROID_JNI.md
• Flutter/Dart FFI: docs/bindings/FLUTTER_DART_FFI.md
• Python UniFFI: docs/bindings/PYTHON_UNIFFI.md