ruby-bindgen 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f6c7ab91006aee7a6926a5e8539984035e810270aa1acead7a85cf84421a7509
+  data.tar.gz: e6da98262ed5f7c588caf9e20d174613fd90b8bafecdfe02d0490321371d6cf5
+SHA512:
+  metadata.gz: a879be6c008ce0067f92e842837d57c8129316431baf059e9c608c4a646ded3e97825ff7738bd43bee559dfe6199a2b9366ecaac32aca1b03d35eaad408138e3
+  data.tar.gz: 8466219b1802377f9149f416c5836f0801daed0c0107eeb9b1ad242d7df8d94ce5037c54498756813c6a97bdfe5e2b5966642b9ed1fa80627ba576f332291a1d

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## 1.0.0 (2026-05-10)
+
+First public release.
+
+ruby-bindgen generates Rice C++ bindings, raw FFI bindings, and CMake build files
+for Ruby extensions wrapping C and C++ libraries. It is driven by libclang and
+configured via YAML.

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (C) 2024 Charlie Savage
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

data/README.md

@@ -0,0 +1,68 @@
+# ruby-bindgen
+
+`ruby-bindgen` generates Ruby bindings from C and C++ header files. It can even generate a CMake build system if needed. It has been battle-tested against large C/C++ libraries such as Proj and OpenCV.
+
+Traditionally, wrapping large C and C++ libraries for use in Ruby has been a long, arduous task, especially for large, complex libraries . As a result, many C/C++ libraries are either never exposed to Ruby or their bindings quickly become outdated, especially in scientific and technical domains.
+
+For much more information, read the extensive [documentation](https://ruby-rice.github.io/ruby-bindgen/).
+
+## Quick Start
+
+Create a config file (`rice-bindings.yaml`):
+
+```yaml
+project: my_extension
+input: ./include
+output: ./ext/generated
+format: Rice
+
+match:
+  - "**/*.hpp"
+
+clang:
+  args:
+    - -I./include
+    - -std=c++17
+    - -xc++
+```
+
+Generate bindings:
+
+```bash
+ruby-bindgen rice-bindings.yaml
+```
+
+This produces `.cpp`, `.hpp`, and `.ipp` files ready to compile as a Ruby extension.
+
+Relative paths (`./include`, `./ext/generated`, `-I./include`) are resolved relative to the config file's directory, so you can run `ruby-bindgen` from anywhere.
+
+## Install
+
+```console
+gem install ruby-bindgen
+```
+
+## Requirements
+
+- Ruby 3.2+
+- libclang from LLVM/Clang 17 or newer
+
+## Documentation
+
+Full documentation is at [ruby-rice.github.io/ruby-bindgen](https://ruby-rice.github.io/ruby-bindgen/).
+
+- [C++ (Rice) Getting Started](https://ruby-rice.github.io/ruby-bindgen/cpp/getting_started/)
+- [C (FFI) Getting Started](https://ruby-rice.github.io/ruby-bindgen/c/getting_started/)
+- [Configuration Reference](https://ruby-rice.github.io/ruby-bindgen/configuration/)
+
+## Real-world bindings
+
+These projects use `ruby-bindgen` to generate their Ruby bindings:
+
+- [BitmapPlusPlus-ruby](https://github.com/ruby-rice/BitmapPlusPlus-ruby) — C++ bitmap library, fully automated end-to-end example.
+- [proj4rb](https://github.com/cfis/proj4rb) — bindings for the PROJ cartographic projections C library.
+- [opencv-ruby](https://github.com/cfis/opencv-ruby) — bindings for OpenCV (thousands of classes, tens of thousands of methods).
+
+## License
+
+BSD-2-Clause

data/Rakefile

@@ -0,0 +1,8 @@
+# encoding: utf-8
+
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+
+require "minitest/test_task"
+Minitest::TestTask.create

data/bin/ruby-bindgen

@@ -0,0 +1,133 @@
+#! /usr/bin/env ruby
+
+require 'ruby-bindgen/config'
+require 'ruby-bindgen/version'
+
+module RubyBindgen
+  class Cmd
+    attr_reader :config
+
+    def initialize
+      parse_args
+      @config = RubyBindgen::Config.new(@config_path)
+      require 'ruby-bindgen'
+      validate_config
+    end
+
+    def parse_args
+      if ARGV.empty? || ARGV[0] == '-h' || ARGV[0] == '--help'
+        puts usage
+        exit(ARGV.empty? ? 1 : 0)
+      end
+
+      if ARGV[0] == '-v' || ARGV[0] == '--version'
+        puts "ruby-bindgen #{RubyBindgen::VERSION}"
+        exit 0
+      end
+
+      @config_path = ARGV[0]
+
+      unless File.exist?(@config_path)
+        raise "Config file not found: #{@config_path}"
+      end
+    end
+
+    def usage
+      <<~USAGE
+        ruby-bindgen
+
+        Usage: ruby-bindgen <config.yaml>
+
+        Generates Ruby bindings for C and C++ libraries using a YAML configuration file.
+
+        See documentation for config file format: https://github.com/ruby-rice/ruby-bindgen/blob/main/docs/configuration.md
+
+        Options:
+          -h, --help       Show this help message
+          -v, --version    Print the ruby-bindgen version and exit
+      USAGE
+    end
+
+    def validate_config
+      raise "Config must specify 'output'" unless @config[:output]
+      raise "Config must specify 'format'" unless @config[:format]
+
+      unless %w[FFI Rice CMake].include?(@config[:format])
+        raise "Format must be 'FFI', 'Rice', or 'CMake', got: #{@config[:format]}"
+      end
+
+      # Input defaults to output for CMake (scans generated files in output dir)
+      @config[:input] ||= @config[:output]
+
+      unless File.directory?(@config[:input])
+        raise "Input path must be a directory: #{@config[:input]}"
+      end
+
+      unless File.directory?(@config[:output])
+        raise "Output path must be a directory: #{@config[:output]}"
+      end
+
+      # Validate project name (if provided). Hyphens are allowed and normalized to underscores.
+      if @config[:project] && !@config[:project].match?(/\A[A-Za-z_][A-Za-z0-9_-]*\z/)
+        raise "Project name must be a valid C/C++ identifier (hyphens allowed): #{@config[:project]}"
+      end
+
+      # User-supplied Rice include header must exist under the output directory
+      # at config time. If it is missing, every generated -rb.hpp file would
+      # emit `#include "..."` for a nonexistent header and the C++ build would
+      # fail with a confusing 'file not found' error far from the cause.
+      if @config[:format] == "Rice" && @config[:include]
+        include_path = File.join(@config[:output], @config[:include])
+        unless File.exist?(include_path)
+          raise "Rice include header not found: #{include_path}"
+        end
+      end
+
+      # Validate libclang shared library if specified.
+      if @config[:libclang] && !File.exist?(@config[:libclang])
+        raise "libclang library not found: #{@config[:libclang]}"
+      end
+
+      # clang/clang-cl args must be an array, not a string.
+      if @config[:clang_args] && !@config[:clang_args].is_a?(Array)
+        raise "clang args must be a YAML list, got: #{@config[:clang_args].class}"
+      end
+    end
+
+    def run
+      input = @config[:input]
+      default_match = @config[:format] == "CMake" ? ["**/*-rb.cpp"] : ["**/*.{h,hpp}"]
+      match_patterns = @config[:match] || default_match
+      skip_patterns = @config[:skip] || []
+
+      inputter = RubyBindgen::Inputter.new(input, match_patterns, skip_patterns)
+      outputter = RubyBindgen::Outputter.new(@config[:output])
+
+      generator_klass = RubyBindgen::Generators.const_get(@config[:format])
+      generator = generator_klass.new(inputter, outputter, @config)
+      generator.generate
+    end
+  end
+end
+
+debug = ENV['BINDGEN_DEBUG']
+
+begin
+  cmd = RubyBindgen::Cmd.new
+rescue => e
+  # Setup-time errors (missing/invalid config, bad arguments). Treat as user
+  # errors and skip the backtrace unless BINDGEN_DEBUG is set.
+  STDERR.puts "Error: #{e.message}"
+  STDERR.puts e.backtrace if debug
+  exit 1
+end
+
+begin
+  cmd.run
+rescue => e
+  # Runtime errors during generation. Print the backtrace because these
+  # usually indicate a bug worth reporting.
+  STDERR.puts "Error: #{e.message}"
+  STDERR.puts e.backtrace
+  exit 1
+end

data/docs/architecture.md

@@ -0,0 +1,238 @@
+# Architecture
+
+`ruby-bindgen` uses [libclang](https://clang.llvm.org/doxygen/group__CINDEX.html), via [ffi-clang](https://github.com/ioquatix/ffi-clang), to parse C and C++ header files.
+
+Libclang represents the [Abstract Syntax Tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) as a hierarchy of cursors. Each cursor is a node representing a declaration, statement, or expression. For example, parsing this header:
+
+```cpp
+namespace cv {
+  class Mat {
+    Mat(int rows, int cols, int type);
+    int rows;
+    bool empty() const;
+  };
+}
+```
+
+Produces a cursor tree like:
+
+```
+namespace (cv)
+  └── class_decl (Mat)
+        ├── constructor (Mat)
+        │     ├── parm_decl (rows)
+        │     ├── parm_decl (cols)
+        │     └── parm_decl (type)
+        ├── field_decl (rows)
+        └── cxx_method (empty)
+```
+
+For C and C++ bindings, `ruby-bindgen` uses a [visitor pattern](https://en.wikipedia.org/wiki/Visitor_pattern)-style traversal to walk this tree. Each cursor kind is dispatched to a corresponding `visit_*` method (e.g., `visit_class_decl`, `visit_cxx_method`), which generates binding code via ERB templates.
+
+``` mermaid
+flowchart TD
+    subgraph Input
+        H["C/C++ headers"]
+        Y["bindings.yaml"]
+    end
+
+    subgraph Parsing
+        FC["ffi-clang"]
+        AST["AST"]
+        FC --> AST
+    end
+
+    subgraph "Code Generation"
+        V1["Generator"]
+        ERB1["ERB templates"]
+        V1 --> ERB1
+    end
+
+    subgraph Output
+        F["Rice/FFI files"]
+    end
+
+    H --> FC
+    Y --> V1
+    AST --> V1
+    ERB1 --> F
+```
+
+For CMake bindings, `ruby-bindgen` runs as a second pass, scanning the output directory for previously generated `*-rb.cpp` files.
+
+``` mermaid
+flowchart TD
+    subgraph Input
+        Y["cmake-bindings.yaml"]
+        S["*-rb.cpp"]
+    end
+
+    subgraph "Code Generation"
+        V2["CMake generator"]
+        ERB2["ERB templates"]
+        V2 --> ERB2
+    end
+
+    subgraph Output
+        F["CMakeLists.txt / CMakePresets.json"]
+    end
+
+    Y --> V2
+    S --> V2
+    ERB2 --> F
+```
+
+## Source Layout
+
+The [key classes](#key-classes) live under `lib/ruby-bindgen/`. Each output format (Rice, FFI, CMake) has its own directory under `generators/` containing both the generator implementation and its ERB templates.
+
+```
+lib/ruby-bindgen/
+├── config.rb                    # YAML config loading
+├── inputter.rb                  # Header file discovery
+├── outputter.rb                 # File writing with cleanup
+├── parser.rb                    # ffi-clang AST parsing
+├── name_mapper.rb               # Exact/regex name remapping
+├── namer.rb                     # C++ → Ruby name conversion
+├── symbols.rb                   # skip / version / override matching
+├── symbol_entry.rb              # Per-symbol skip/version/override record
+├── symbol_candidates.rb         # Candidate name generation for lookup
+├── type_pointer_formatter.rb    # Pointer type formatting helpers
+├── version.rb
+├── refinements/                 # Extensions to ffi-clang and stdlib classes
+│   ├── cursor.rb                # Cursor: ruby_name, cruby_name, anonymous_definer, namer
+│   └── string.rb                # String: camelize, underscore, upcase_first
+└── generators/
+    ├── generator.rb             # Base class shared by generators
+    ├── rice/                    # C++ Rice binding generator
+    │   ├── rice.rb              # Main C++ generator (AST visitor); the helpers
+    │   │                        # below are nested under Rice (e.g.
+    │   │                        # RubyBindgen::Generators::Rice::TypeSpeller).
+    │   ├── type_speller.rb      # Reconstructs qualified C++ type names
+    │   ├── type_index.rb        # Index of typedefs and template instantiations
+    │   ├── signature_builder.rb # Builds Rice method signatures
+    │   ├── template_resolver.rb # Class template resolution
+    │   ├── iterator_collector.rb# Detects begin/end iterator pairs
+    │   ├── function_pointer.rb  # Function pointer typedef handling
+    │   ├── reference_qualifier.rb# Reference / const qualifiers
+    │   └── *.erb                # ERB templates
+    ├── ffi/                     # C FFI binding generator
+    │   ├── ffi.rb               # Main C generator
+    │   └── *.erb                # ERB templates
+    └── cmake/                   # CMake build file generator
+        ├── cmake.rb             # Main CMake generator
+        ├── guard.rb             # Per-target build guards
+        └── *.erb                # ERB templates
+```
+
+Most generator methods delegate to ERB templates for code generation. Each template receives the current cursor and any generator state as local variables, and outputs a string of generated code.
+
+For example, the Rice generator's `cxx_method.erb` template generates a `define_method` call:
+
+```cpp
+define_method<%= signature %>("<%= name %>", &<%= qualified_parent %>::<%= cursor.spelling %>,
+  <%= all_args.join(", ") %>)
+```
+
+## Key Classes
+
+### Config
+
+The `Config` class loads the YAML configuration file and resolves platform-specific settings. It detects whether to use `clang:` or `clang-cl:` based on `RUBY_PLATFORM` (`mswin` uses `clang-cl:`; Linux, macOS, and MinGW use `clang:`), resolves relative paths against the config file's directory, and provides hash-like access to all configuration values.
+
+### Inputter
+
+The `Inputter` class discovers header files to process. Given a base directory and glob patterns from the config (`match:` and `skip:`), it iterates over matching files and yields both absolute and relative paths.
+
+### Parser
+
+The `Parser` class wraps ffi-clang's `Index` and drives the processing loop:
+
+```ruby
+def generate(visitor)
+  visitor.visit_start
+
+  inputter.each do |path, relative_path|
+    translation_unit = @index.parse_translation_unit(path, clang_args, [],
+      [:detailed_preprocessing_record, :skip_function_bodies])
+    visitor.visit_translation_unit(translation_unit, path, relative_path)
+  end
+
+  visitor.visit_end
+end
+```
+
+For each header file, it calls `parse_translation_unit`, which returns a translation unit object. Visitors access the root cursor via `translation_unit.cursor`.
+
+Parse options include `:skip_function_bodies` (we only need declarations, not implementations) and `:detailed_preprocessing_record` (to see preprocessor directives).
+The parser also checks diagnostics after each translation unit and raises on fatal/error diagnostics.
+
+### Outputter
+
+The `Outputter` class writes generated files to the output directory. It tracks all written paths and applies whitespace cleanup (removing excessive blank lines and blank lines before closing braces) to keep the output tidy.
+
+### Namer
+
+The `Namer` class converts C++ names to Ruby conventions:
+
+- `CamelCase` class names stay as-is (Ruby classes are CamelCase)
+- `camelCase` and `PascalCase` method names become `snake_case`
+- `isFoo()` / `is_foo()` become `foo?` (any `bool`-returning method whose name starts with `is`, plus any zero-arg `bool`-returning method, gets the `?` suffix)
+- C++ operators map to Ruby operators (`operator+` → `+`, `operator==` → `==`)
+- `operator[]` maps to both `[]` and `[]=` (if the return type is a reference)
+- `operator()` maps to `call`
+- Conversion operators like `operator int()` map to `to_i`, `operator string()` to `to_s`
+- C variable names for Rice classes use the `rb_c` prefix (e.g., `rb_cCvMat`)
+
+## Extensions to ffi-clang and stdlib
+
+The `lib/ruby-bindgen/refinements/` directory holds open monkey-patches that
+extend ffi-clang and Ruby's `String`. They are loaded globally — not actual
+Ruby refinements — so any code that loads `ruby-bindgen` sees the additions.
+
+- **Cursor** (`refinements/cursor.rb`) — adds `ruby_name`, `cruby_name`,
+  `anonymous_definer`, and a class-level `namer` accessor that the generators
+  set during `generate`.
+- **String** (`refinements/string.rb`) — adds `camelize`, `underscore`, and
+  `upcase_first` for name conversion.
+
+Reconstructing qualified C++ type names is handled by the `TypeSpeller` class
+(`lib/ruby-bindgen/generators/rice/type_speller.rb`), which calls
+`FFI::Clang::Type#fully_qualified_name` (provided directly by ffi-clang ≥
+0.16) and post-processes the result. See [Type Spelling](type_spelling.md).
+
+## Rice Generator Details
+
+The Rice generator is the largest part of the codebase because C++ has the most features to handle. Some notable aspects:
+
+### Traversal
+
+The generator traverses the AST recursively. Each cursor kind is dispatched to a `visit_*` method (e.g., `visit_class_decl`, `visit_cxx_method`) which checks whether the cursor should be skipped and, if not, renders an ERB template to generate the binding code.
+
+### Filtering
+
+Before generating code for a cursor, the visitor applies several filters. See [filtering](cpp/filtering.md) for details.
+
+### Template Handling
+
+C++ class templates require special treatment. See [templates](cpp/templates.md) for details.
+
+### Type Spelling
+
+Reconstructing correct C++ type names from libclang's type information is one of the trickiest parts of the codebase. The `TypeSpeller` class (`lib/ruby-bindgen/generators/rice/type_speller.rb`) handles:
+
+- Namespace qualification (`cv::Mat` not `Mat`)
+- Template argument qualification (`std::vector<cv::Point>` not `std::vector<Point>`)
+- Typedef resolution (knowing when to use the alias vs the underlying type)
+- Dependent types in templates (adding `typename` where required)
+- Elaborated types (`enum Foo` vs `Foo`)
+
+### Default Arguments
+
+Libclang provides limited information about default argument values. `ruby-bindgen` extracts default values from the source text and wraps them in `static_cast` with fully qualified types to ensure they compile in the generated context:
+
+```cpp
+// Original: void resize(int size, const Scalar& value = Scalar())
+// Generated:
+Arg("value") = static_cast<const cv::Scalar&>(cv::Scalar())
+```

data/docs/c/c_bindings.md

@@ -0,0 +1,65 @@
+# C Bindings
+
+`ruby-bindgen` generates Ruby files that use the [FFI](https://github.com/ffi/ffi) gem to call C library functions. FFI allows Ruby to directly load and call functions from C shared libraries without writing a C extension. This means:
+
+- **No compilation step** - Ruby loads the library at runtime
+- **Easier distribution** - No need to compile native code for each platform
+- **Simpler development** - No C code to write or debug
+
+If a library provides a C API then use it!
+
+## Supported Features
+
+`ruby-bindgen` supports the following FFI features:
+
+- [Functions](https://github.com/ffi/ffi/wiki/Basic-Usage) via `attach_function`, including variadic functions (`:varargs`). Functions taking `va_list` parameters are skipped since `va_list` cannot be constructed from Ruby.
+- [Structs](https://github.com/ffi/ffi/wiki/Structs) map to `FFI::Struct`
+- Unions map to `FFI::Union`
+- [Enums](https://github.com/ffi/ffi/wiki/Enums) map to FFI enum types
+- [Callbacks](https://github.com/ffi/ffi/wiki/Callbacks) for function pointer types
+- [Typedefs](https://github.com/ffi/ffi/wiki/Types) are preserved
+- Forward declarations map to opaque pointer types
+- Global variables via [`attach_variable`](https://www.rubydoc.info/gems/ffi/FFI/Library#attach_variable-instance_method)
+- Constants from `const` variables (see [Constants and Macros](constants.md))
+
+## Getting Started
+
+See [Getting Started](getting_started.md) for a step-by-step guide to creating your first FFI bindings.
+
+## Output
+
+See [FFI Output](output.md) for details on the generated files.
+
+## Examples
+
+The test suite includes bindings generated from some popular C libraries:
+
+| Library         | Description                       |
+|-----------------|-----------------------------------|
+| [PROJ](https://proj.org/)     | Coordinate transformation library |
+| [SQLite](https://sqlite.org/)   | Database engine                   |
+| [libclang](https://clang.llvm.org/) | C/C++ parsing library             |
+
+See [test/headers/c](https://github.com/ruby-rice/ruby-bindgen/tree/main/test/headers/c) for the input headers and [test/bindings/c](https://github.com/ruby-rice/ruby-bindgen/tree/main/test/bindings/c) for the generated Ruby bindings.
+
+## Ruby Wrapper Classes
+
+Since C is procedural rather than object-oriented, you may wish to wrap the generated FFI bindings in Ruby classes to provide a more idiomatic API:
+
+```ruby
+require_relative 'generated/mylib_ffi'
+
+class MyLibWrapper
+  def initialize
+    @handle = Mylib.create_handle()
+  end
+
+  def process(data)
+    Mylib.process_data(@handle, data)
+  end
+
+  def close
+    Mylib.destroy_handle(@handle)
+  end
+end
+```

data/docs/c/constants.md

@@ -0,0 +1,21 @@
+# Constants and Macros
+
+`ruby-bindgen` generates Ruby constants from top-level `const` variables with literal initializers:
+
+```c
+const int CONST_INT = 10;
+static const int STATIC_CONST_INT = 20;
+const double CONST_DOUBLE = 3.14;
+```
+
+Generates:
+
+```ruby
+CONST_INT = 10
+STATIC_CONST_INT = 20
+CONST_DOUBLE = 3.14
+```
+
+## Macros
+
+Macros are not added to bindings because their values are baked in at generation time and thus not read at runtime. This easily causes confusion. For example, a version macro like `PROJ_VERSION_MAJOR` would reflect whichever library version was used to generate bindings, not the version actually being used on your machine.

data/docs/c/customizing.md

@@ -0,0 +1,19 @@
+# Customizing
+
+`ruby-bindgen` can customize the generated bindings in several ways:
+
+- [`symbols: skip:`](../configuration.md#skip) — exclude specific functions, structs, enums, or typedefs by name or regex pattern
+- [`symbols: overrides:`](../configuration.md#overrides-ffi-only) — replace the generated signature for specific functions when the heuristics pick the wrong FFI type
+- [`export_macros`](../configuration.md#export-macros) — only include functions marked with specific visibility macros
+- [`rename_types`](../configuration.md#name-mappings) — override generated Ruby module/class names
+- [`rename_methods`](../configuration.md#name-mappings) — override generated Ruby method names
+
+## Module Name
+
+By default, the generated Ruby module is named after the header file (e.g., `proj.h` → `module Proj`). Use the [`module`](../configuration.md#c-ffi-options) option to override this, including nested modules:
+
+```yaml
+module: Proj::Api
+```
+
+This generates properly nested `module Proj` / `module Api` with correct indentation.

data/docs/c/filtering.md

@@ -0,0 +1,24 @@
+# Filtering
+
+`ruby-bindgen` provides several mechanisms to control which symbols are included in the generated bindings.
+
+## Export Macros
+
+Many libraries use macros to control which functions are exported. `ruby-bindgen` can honor these macros so that only exported functions are included in the generated bindings. See [`export_macros`](../configuration.md#export-macros) for details.
+
+## Skipping Symbols
+
+Sometimes you need to exclude specific symbols from the generated bindings — for example, internal APIs, symbols that cause linker errors, or platform-specific functions. `ruby-bindgen` supports skipping by name, qualified name, or regex pattern. See [`symbols.skip`](../configuration.md#skip) for details.
+
+## Version Guards
+
+When a library evolves across versions, some symbols are only available in newer releases. `ruby-bindgen` can wrap these symbols in version guards so the same bindings compile against multiple library versions. See [`symbols.versions`](../configuration.md#versions) for details.
+
+## Automatic Skipping
+
+The following are automatically skipped:
+
+- **Deprecated**: Functions marked with `__attribute__((deprecated))` or `[[deprecated]]`
+- **va_list**: Functions taking `va_list` parameters (cannot be constructed from Ruby; use the variadic `...` version instead)
+- **Private/Protected**: Non-public members
+- **System headers**: Declarations from system include paths

data/docs/c/getting_started.md

@@ -0,0 +1,56 @@
+# 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`:
+
+```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](../configuration.md) for all options, including [library versioning](../configuration.md#c-ffi-options), [symbol filtering](../configuration.md#symbols), and [version guards](../configuration.md#versions).
+
+## 2. Generate bindings
+
+```bash
+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](output.md) for details.
+
+## 3. Use the bindings
+
+```ruby
+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.