Configuration

ruby-bindgen uses a YAML configuration file to specify how bindings should be generated. This approach keeps your build configuration versioned and reproducible.

ruby-bindgen rice-bindings.yaml

For end-to-end examples, see C Bindings, C++ Bindings, and CMake Bindings.

Required Options

Relative paths for input and output are resolved from the config file's directory, not the current working directory. This makes configs portable across different machines.

Common Options

These options apply to all formats.

C (FFI) Options

C++ (Rice) Options

CMake Options

Compiler Toolchain

ruby-bindgen uses top-level toolchain keys to configure compiler settings for different platforms:

• clang-cl: - Used when Ruby is built with MSVC (RUBY_PLATFORM contains mswin)
• clang: - Used for all other platforms (Linux, macOS, MinGW)

You only need to include the toolchain sections for platforms you target.

Resolution Flow

flowchart TD
  A["config.yaml location"] --> B["Resolve relative input/output paths"]
  B --> C{"RUBY_PLATFORM contains mswin?"}
  C -->|Yes| D["Use clang-cl section"]
  C -->|No| E["Use clang section"]
  D --> F["Set LIBCLANG from toolchain libclang (if provided)"]
  E --> F
  F --> G["Pass toolchain args to libclang parser"]

Clang Arguments

The args section under each toolchain is crucial for successful parsing. You typically need:

1. System include paths - Standard library headers
2. Library include paths - The library's own headers
3. Language specification - -xc++ for C++ headers, -xc for C headers
4. Language standard - -std=c++17 or similar

Finding System Include Paths

On Linux/macOS:

clang++ -E -x c++ - -v < /dev/null 2>&1 | grep "^ /"

On Windows with MSVC: - Visual Studio include paths (e.g., C:\Program Files\Microsoft Visual Studio\...\include) - Windows SDK include paths (e.g., C:\Program Files (x86)\Windows Kits\10\Include\...) - LLVM/Clang include paths if using clang

Finding Libclang

On Linux:

# Common locations
/usr/lib64/libclang.so           # Fedora, RHEL
/usr/lib/x86_64-linux-gnu/libclang-*.so  # Debian, Ubuntu
/usr/lib/llvm-*/lib/libclang.so  # Multiple LLVM versions

# Find all libclang installations
find /usr -name "libclang*.so" 2>/dev/null

On macOS:

# Homebrew LLVM
/opt/homebrew/opt/llvm/lib/libclang.dylib  # Apple Silicon
/usr/local/opt/llvm/lib/libclang.dylib     # Intel

# Xcode Command Line Tools
/Library/Developer/CommandLineTools/usr/lib/libclang.dylib

On Windows:

# Visual Studio bundled LLVM
C:\Program Files\Microsoft Visual Studio\2022\...\VC\Tools\Llvm\x64\bin\libclang.dll

# Standalone LLVM installation
C:\Program Files\LLVM\bin\libclang.dll

Symbols

The symbols option groups per-symbol actions by type. There are three action groups: skip, versions, and overrides.

Skip

The skip key lists symbols to exclude from bindings. This is useful when:

• Functions have export macros but still aren't available (build configuration issues)
• Functions are internal/private APIs not meant for external use
• Functions cause linker errors due to missing symbols

Symbol names support:

• Simple names: versionMajor - skips all symbols with this name
• Fully qualified names: cv::ocl::PlatformInfo::versionMajor - skips only that specific symbol
• Signatures: cv::Mat_::zeros(int, const int *) - skips only the overload with matching parameter types
• Regex patterns: /pattern/ - skips symbols matching the regex

symbols:
  skip:
    - versionMajor                           # Skips all symbols named "versionMajor"
    - cv::ocl::PlatformInfo::versionMinor    # Skips only this specific method
    - "cv::Mat_::zeros(int, const int *)"    # Skips only this overload (others remain)
    - /cv::dnn::.*Layer::init.*/             # Regex: skips all init* methods on any Layer class

Versions

The versions key wraps symbols in version guards. Each sub-key is the minimum version value, with a list of symbol names underneath.

For Rice (C++), this requires the version_check option to be set. The generator wraps version-specific symbols in #if version_check >= version / #endif preprocessor directives.

format: Rice
version_check: CV_VERSION
symbols:
  versions:
    40100:
      - cv::Foo::baz
    40500:
      - /cv::cuda::.*/

This generates:

#if CV_VERSION >= 40100
  .define_method("baz", &cv::Foo::baz)
#endif

For FFI (C), this requires the version_check option to be set to a Ruby method name. The generator wraps version-specific symbols in if version_check >= version Ruby conditionals and generates a {project}_version.rb skeleton file. The user implements the version detection method — typically by calling the library's own version API. See Version Detection for a full example.

format: FFI
project: proj
version_check: proj_version
symbols:
  skip:
    - PJ_INFO       # manually defined in version file
    - proj_info      # manually defined in version file
  versions:
    60100:
      - proj_normalize_for_visualization
    60200:
      - proj_cleanup

This generates:

if proj_version >= 60100
  attach_function :proj_normalize_for_visualization, ...
end

See Version Guards for the Rice guide and Version Detection for a full FFI example.

Overrides (FFI only)

The overrides key replaces the generated attach_function signature for specific functions. This is useful when ruby-bindgen's type heuristics produce the wrong FFI type — for example, C functions that return int 0/1 for boolean, or use size_t parameters that resolve to :ulong.

Each entry maps a C function name to a signature string that replaces everything after attach_function :ruby_name, :c_name,:

symbols:
  overrides:
    # C returns int 0/1, but Ruby 0 is truthy so must use :bool
    proj_is_crs: "[:pointer], :bool"
    # size_t vs ulong: on 64-bit Windows size_t is 8 bytes but ulong is 4 bytes
    proj_trans_generic: "[:pointer, PjDirection, :pointer, :size_t, :size_t, ...], :size_t"
    # Output buffer: char *s is caller-allocated, return is same pointer
    proj_rtodms2: "[:pointer, :ulong, :double, :int, :int], :pointer"

Overload-Specific Skipping

When a function has multiple overloads but only some cause problems (e.g., linker errors), you can target a specific overload by appending its parameter types in parentheses:

symbols:
  skip:
    - cv::Mat_::zeros                        # Skips ALL overloads of zeros
    - "cv::Mat_::zeros(int, const int *)"    # Skips only zeros(int ndims, const int* sz)

The parameter types must match the canonical clang type spelling exactly (e.g., const int * not const int* or int const *).

Regex Patterns

Regex patterns are enclosed in forward slashes (/pattern/) and are matched against both the simple symbol name and the fully qualified name. This is particularly useful for:

• Matching across versioned inline namespaces (e.g., cv::dnn::dnn4_v20241223::Layer)
• Skipping families of related methods
• Handling template specializations

ruby-bindgen automatically skips:

• Deprecated functions (marked with __attribute__((deprecated)))
• Internal functions (names ending with _)
• Methods returning pointers to incomplete types (pimpl pattern)

Export Macros

The export_macros option filters functions based on the presence of specific macros in the source code. This is useful for libraries that use macros to control symbol visibility.

When specified, only functions whose source text contains at least one of the listed macros will be included in the bindings. This prevents linker errors from trying to wrap internal functions that aren't exported from the shared library.

export_macros:
  - CV_EXPORTS
  - CV_EXPORTS_W

Common Library Macros

Name Mappings

ruby-bindgen applies heuristics to convert C++ names to Ruby names — for example, isEnabled() becomes enabled? and operator() becomes call. These heuristics sometimes guess wrong. The rename_methods and rename_types options let you override the generated names without manual post-generation edits.

Both options use the same pattern syntax as symbols names: plain strings for exact match, /pattern/ for regex.

Type Mappings

Override generated Ruby class names for template instantiations. Supports \1, \2, etc. capture group substitution in regex replacements.

rename_types:
  # OpenCV Matx naming convention: MatxUnsignedChar21 → Matx21b
  - from: /^MatxUnsignedChar(\d+)$/
    to: Matx\1b
  - from: /^MatxUnsignedShort(\d+)$/
    to: Matx\1w
  - from: /^MatxShort(\d+)$/
    to: Matx\1s
  - from: /^MatxInt(\d+)$/
    to: Matx\1i

Without these overrides, Matx<unsigned char, 2, 1> would generate the Ruby class name MatxUnsignedChar21. With the mapping, it becomes Matx21b, matching OpenCV's naming convention.

Method Mappings

Override generated Ruby method names. The from field is a C++ name (simple or fully qualified), the to field is the desired Ruby name.

rename_methods:
  # Exact match by qualified name — grab is not a predicate, it grabs a frame
  - from: cv::VideoCapture::grab
    to: grab
  # Override operator() → [] for element/ROI access
  - from: cv::Mat::operator()
    to: "[]"
  - from: cv::UMat::operator()
    to: "[]"
  # Override operator() → to_size for MatSize (returns a Size, not element access)
  - from: cv::MatSize::operator()
    to: to_size

Without these overrides, ruby-bindgen would generate grab? (bool return, no params triggers predicate heuristic) and call (default operator() mapping).