getting_started.md

Getting Started with FFI Bindings

This guide walks you through generating Ruby FFI bindings for a C library.

1. Create a configuration file

Create a file named ffi-bindings.yaml:

project: mylib
input: ./include
output: ./lib/generated
format: FFI

match:
  - "**/*.h"

library_names:
  - mylib

clang:
  args:
    - -I./include
    - -xc

Key options:

• project — name used for the project file (mylib_ffi.rb) and the Ruby module
• input — directory containing header files
• output — where generated Ruby files are written
• library_names — shared library names to load at runtime (e.g., mylib for libmylib.so)
• match — glob patterns selecting which headers to process
• clang.args — compiler arguments; -xc tells clang to parse as C

Paths are relative to the config file's directory, not the working directory.

See Configuration for all options, including library versioning, symbol filtering, and version guards.

2. Generate bindings

ruby-bindgen ffi-bindings.yaml

This produces a project file, one Ruby file per matched header, and optionally a version stub file. See FFI Output for details.

3. Use the bindings

require_relative 'lib/generated/mylib_ffi'

result = Mylib.my_function(42, "hello")

The project file (mylib_ffi.rb) loads the native library and requires all content files. You only need to require the project file.