ruby-bindgen 1.0.0

data/docs/cpp/templates.md

@@ -0,0 +1,114 @@
+# Templates
+
+`ruby-bindgen` generates bindings for C++ class templates, handling specializations, base class chains, and file organization automatically. For details on how Rice wraps class templates, see the Rice [Class Templates](https://ruby-rice.github.io/4.x/bindings/class_templates/) documentation.
+
+## Template Classes and Specializations
+
+`ruby-bindgen` generates bindings for template class instantiations created via `typedef` or `using` statements:
+
+```cpp
+template<typename T>
+class Point
+{
+    T x, y;
+};
+
+typedef Point<int> Point2i;
+using Point2f = Point<float>;
+```
+
+Generated bindings correctly handle:
+
+- Fully qualified template arguments (`cv::Point<int>` not `Point<int>`)
+- Base class inheritance chains for templates
+- Auto-generation of base class bindings when no typedef exists
+
+## Template Argument Qualification
+
+Unqualified type names in template arguments are automatically qualified:
+
+```cpp
+// Input: std::map<String, DictValue>::iterator
+// Output: std::map<cv::String, cv::dnn::DictValue>::iterator
+```
+
+## Template Base Classes
+
+When a class inherits from a template instantiation, the base class binding is auto-generated if no typedef exists:
+
+```cpp
+class PlaneWarper : public WarperBase<PlaneProjector>
+{
+};
+// Auto-generates WarperBasePlaneProjector binding
+```
+
+## Inheritance Chain Resolution
+
+For template typedefs with base classes, the entire inheritance chain is resolved and generated in the correct order.
+
+### Cross-File Duplicate Instantiations
+
+When a template typedef in one header inherits from a template defined in another header, `ruby-bindgen` will re-instantiate the ancestor chain in the derived file even if those ancestors were already instantiated in the base file. For example, if `types.hpp` has `typedef Scalar_<double> Scalar` and `Scalar_` inherits from `Vec<double, 4>` which inherits from `Matx<double, 4, 1>`, the generated `types-rb.cpp` will include instantiation calls for all three — even though `Vec4d` and `Matx41d` were already emitted in `matx-rb.cpp`.
+
+Rice handles this gracefully at runtime (re-registering an already-registered type is a no-op), so the duplicate instantiations are harmless but redundant. If this causes issues, you can remove the duplicate lines from the generated file by hand or use a [refinement file](customizing.md) to control instantiation order.
+
+## Template Instantiate Files (.ipp)
+
+When a header contains class templates with specializations (via `typedef` or `using`), `ruby-bindgen` generates reusable `_instantiate` template functions. These are placed in a separate `.ipp` file to enable reuse without duplicate symbol errors.
+
+**Example**: For `templates.hpp` containing:
+
+```cpp
+template<typename T>
+class Matrix
+{
+    ...
+};
+
+typedef Matrix<float> Matrixf;
+```
+
+`ruby-bindgen` generates:
+
+**templates-rb.ipp** (template instantiate functions):
+```cpp
+#include <templates.hpp>
+#include "templates-rb.hpp"
+
+using namespace Rice;
+
+template<typename T>
+inline Rice::Data_Type<Matrix<T>> Matrix_instantiate(Rice::Module parent, const char* name)
+{
+  return Rice::define_class_under<Matrix<T>>(parent, name).
+    define_constructor(Constructor<Matrix<T>>()).
+    define_attr("data", &Matrix<T>::data);
+}
+```
+
+**templates-rb.cpp** (Init function only):
+```cpp
+#include "templates-rb.ipp"
+
+void Init_Templates()
+{
+  Rice::Data_Type<Matrix<float>> rb_cMatrixf =
+    Matrix_instantiate<float>(Rice::Module(rb_cObject), "Matrixf");
+}
+```
+
+### Reusing Instantiate Functions
+
+The `.ipp` separation enables [refinement files](customizing.md) to reuse `_instantiate` functions without causing duplicate `Init_` symbol errors:
+
+```cpp
+// mat_refinements.cpp - Custom extensions
+#include "mat-rb.ipp"  // Gets _instantiate functions, NOT Init_Core_Mat
+
+void Init_Mat_Refinements()
+{
+  Rice::Data_Type<cv::Mat_<double>> rb_cMat1d =
+    Mat__instantiate<double>(rb_mCv, "Mat1d");
+}
+```

data/docs/examples.md

@@ -0,0 +1,133 @@
+# Examples
+
+## Reference projects
+
+Three published gems use `ruby-bindgen` and are good places to read working
+configuration, layout, and CI when starting your own bindings project.
+
+| Project                                                                 | Format     | Size       | When to use as a reference                                                                                                          |
+|-------------------------------------------------------------------------|------------|------------|-------------------------------------------------------------------------------------------------------------------------------------|
+| [BitmapPlusPlus-ruby](https://ruby-rice.github.io/BitmapPlusPlus-ruby/) | Rice (C++) | ~1 file    | Wrapping a small, header-only C++ library. The cleanest end-to-end gem layout (ext/, lib/, sig/, test/, docs/, CMakePresets.json). |
+| [proj4rb](https://cfis.github.io/proj4rb/)                              | FFI (C)    | medium     | Wrapping a C library via FFI rather than a compiled extension. Shows library loading, version pinning, and Ruby-side wrappers.     |
+| [opencv-ruby](https://github.com/cfis/opencv-ruby)                      | Rice (C++) | very large | Wrapping a large, complex C++ library that needs heavy customization, CUDA guards, and post-regeneration manual edits.            |
+
+For learning, start with **BitmapPlusPlus-ruby** for C++ or **proj4rb** for C.
+Read **opencv-ruby** later, as a study of how to scale the same approach to
+1,000+ classes and 10,000+ method bindings.
+
+## Minimal config snippets
+
+Minimal end-to-end examples for each output format.
+
+## Rice (C++)
+
+`rice-bindings.yaml`:
+
+```yaml
+project: sample_ext
+input: ./include
+output: ./ext/generated
+format: Rice
+
+match:
+  - "**/*.hpp"
+
+clang:
+  args:
+    - -I./include
+    - -std=c++17
+    - -xc++
+```
+
+Run:
+
+```bash
+ruby-bindgen rice-bindings.yaml
+```
+
+Output:
+- One `*-rb.cpp` and `*-rb.hpp` per header
+- Optional `*-rb.ipp` files when template `_instantiate` functions are generated
+- Project files when `project` is set (`sample_ext-rb.cpp`, `sample_ext-rb.hpp`)
+
+## FFI (C)
+
+`ffi-bindings.yaml`:
+
+```yaml
+project: mylib
+input: ./include
+output: ./lib/generated
+format: FFI
+
+match:
+  - "**/*.h"
+
+library_names:
+  - mylib
+library_versions:
+  - "2"
+  - "1"
+
+clang:
+  args:
+    - -I./include
+    - -xc
+```
+
+Run:
+
+```bash
+ruby-bindgen ffi-bindings.yaml
+```
+
+Output:
+- A project loader file (`mylib_ffi.rb`) with `require 'ffi'`, `ffi_lib`, and `require_relative` calls
+- One Ruby content file per header with enums, structs, callbacks, and `attach_function` calls
+
+## CMake (for Rice output)
+
+**Important:** CMake generation must run after Rice generation because it scans the output directory for `*-rb.cpp` files.
+
+`rice-bindings.yaml`:
+
+```yaml
+project: sample_ext
+input: ./include
+output: ./ext/generated
+format: Rice
+match:
+  - "**/*.hpp"
+clang:
+  args:
+    - -I./include
+    - -std=c++17
+    - -xc++
+```
+
+`cmake-bindings.yaml`:
+
+```yaml
+project: sample_ext
+output: ./ext/generated
+format: CMake
+# input defaults to output for CMake and scans ./ext/generated for *-rb.cpp
+
+include_dirs:
+  - "${CMAKE_CURRENT_SOURCE_DIR}/../include"
+```
+
+Run:
+
+```bash
+ruby-bindgen rice-bindings.yaml
+ruby-bindgen cmake-bindings.yaml
+```
+
+Then build:
+
+```bash
+cd ./ext/generated
+cmake --preset linux-debug
+cmake --build build/linux-debug
+```

data/docs/index.md

@@ -0,0 +1,133 @@
+# ruby-bindgen
+
+Wrapping C and C++ libraries by hand is a long, arduous task. For large, complex libraries it can take months. 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.
+
+`ruby-bindgen` and its ecosystem solve this problem by automating binding generation. For simpler libraries, it can generate ready-to-use bindings. For more complex libraries, it can also generate bindings but some [customizations](#customization) may be needed.
+
+As an example, there are older, hand-crafted Ruby [bindings](https://github.com/ruby-opencv/ruby-opencv) for [OpenCV](https://opencv.org/). However, they are based on the C API which was subsequently removed by the OpenCV project. `ruby-bindgen` was used to create new OpenCV [bindings](https://github.com/cfis/opencv-ruby) based on the new C++ API. The bindings wrap over [1,000](https://cfis.github.io/opencv-ruby/) C++ classes and almost [10,000](https://cfis.github.io/opencv-ruby/) method calls. Imagine having to do that by hand!
+
+## Ecosystem
+`ruby-bindgen` is part of the C/C++ to Ruby toolchain.
+
+```mermaid
+flowchart TD
+  H["C/C++ headers"] --> CL["ffi-clang"]
+  CL --> RB["ruby-bindgen"]
+  RB --> F["C (ffi)"]
+  RB --> R["C++ (Rice)"]
+  RB --> C["Build (CMake)"]
+
+  click CL "https://github.com/ioquatix/ffi-clang" "ffi-clang"
+  click RB "https://github.com/ruby-rice/ruby-bindgen" "ruby-bindgen"
+  click R "https://github.com/ruby-rice/rice" "Rice"
+  click F "https://github.com/ffi/ffi" "FFI"
+  click C "https://cmake.org/" "CMake"
+```
+
+The components of the toolchain include:
+
+- [ffi-clang](https://github.com/ioquatix/ffi-clang) - exposes [libclang](https://clang.llvm.org/) parsing APIs to Ruby.
+- [ruby-bindgen](https://github.com/ruby-rice/ruby-bindgen) - generates bindings.
+- [FFI](https://github.com/ffi/ffi) - enables direct C library calls from Ruby without compiling a C extension.
+- [Rice](https://github.com/ruby-rice/rice) - handles C++/Ruby type conversion and native extension integration.
+- [CMake](https://cmake.org/) - builds generated Rice wrappers into loadable extension binaries.
+
+## Prerequisites
+
+- Ruby 3.2 or later
+- libclang (provided by LLVM/Clang)
+
+## Installation
+
+To install `ruby-bindgen` run the following command:
+
+```console
+gem install ruby-bindgen
+```
+
+## Getting Started
+
+`ruby-bindgen` is driven by a [configuration](configuration.md) file. To get started, first decide what type of library you are wrapping:
+
+```mermaid
+flowchart TD
+  A{"C or C++?"}
+  A -->|C| B["FFI"]
+  A -->|C++| C["Rice"]
+  C --> D{"CMake or<br/>extconf.rb?"}
+  D -->|CMake| E["CMake"]
+  D -->|extconf.rb| F["Done"]
+  B --> F
+  E --> F
+
+  click B "c/c_bindings.md" "C Bindings"
+  click C "cpp/cpp_bindings.md" "C++ Bindings"
+  click E "cmake/cmake_bindings.md" "CMake Bindings"
+  click D "https://ruby-rice.github.io/4.x/packaging/extconf/" "Rice extconf.rb packaging"
+```
+
+If a library provides both C and C++ APIs, use the C API! It is usually simpler to wrap and maintain and does not require users to compile extensions.
+
+Once you have decided the format, create a simple [configuration](configuration.md) file and set its `format` field to `FFI`, `Rice` or `CMake`.
+
+- `output` is always required
+- `input` is required for `FFI` and `Rice`; for `CMake` it defaults to `output`
+- `project` is required for `FFI` and optional for `Rice` and `CMake`
+
+For example, a minimal Rice configuration looks like:
+
+```yaml
+project: my_extension
+input: /path/to/headers
+output: /path/to/output
+format: Rice
+
+match:
+  - "**/*.hpp"   # use "**/*.h" for C headers in FFI configs
+
+clang:
+  args:
+    - -I/path/to/includes
+    - -xc++      # omit for C libraries
+```
+See [Configuration](configuration.md) for all options.
+
+For much more details, jump to the documentation page for each format:
+
+| Format    | Next Step                           |
+|-----------|-------------------------------------|
+| **FFI**   | [C Bindings](c/c_bindings.md)       |
+| **Rice**  | [C++ Bindings](cpp/cpp_bindings.md)     |
+| **CMake** | [CMake Bindings](cmake/cmake_bindings.md) |
+
+Finally generate bindings by running the command:
+
+```bash
+ruby-bindgen /path/to/bindings.yaml
+```
+
+## Naming Conventions
+
+`ruby-bindgen` follows Ruby naming conventions for both C and C++ bindings:
+
+- Class/Module names: `UpperCamelCase`
+- Constants: `UPPER_CASE`
+- Methods/Functions: `snake_case`
+- Enum values: `snake_case` symbols (FFI) or scoped constants (Rice)
+
+In addition, methods that return boolean values have `?` appended to their names and `is_` removed if present. For example, `is_open` becomes `open?`.
+
+## Customization
+
+Out of the box, `ruby-bindgen` applies sensible defaults and heuristics. For most libraries you will need to fine-tune the output. The [configuration](configuration.md) file provides several knobs:
+
+- **[Symbol filtering](configuration.md#symbols)** — skip functions, classes, enums, typedefs, unions, or variables by name or regex pattern. Useful for internal APIs, linker-error symbols, or platform-specific code.
+- **[Symbol overrides](configuration.md#overrides-ffi-only)** (FFI) — replace a generated function signature when the heuristics pick the wrong type (e.g., `int` → `:bool`, `ulong` → `:size_t`).
+- **[Version guards](configuration.md#versions)** — wrap symbols in `#if VERSION >= N` preprocessor guards so bindings compile against multiple library versions.
+- **[Name mappings](configuration.md#name-mappings)** — override generated Ruby class and method names with exact strings or regex patterns with capture-group substitution.
+- **[Export macros](configuration.md#export-macros)** — only include functions marked with specific visibility macros (e.g., `CV_EXPORTS`), preventing linker errors from internal symbols.
+- **[Module naming](configuration.md#c-ffi-options)** (FFI) — set the Ruby module name, including nested modules like `Proj::Api`.
+
+## Packaging
+
+For Rice (C++) bindings, see the Rice [Packaging](https://ruby-rice.github.io/4.x/packaging/packaging/) documentation for how to package your extension as a gem.

data/docs/prior_art.md

@@ -0,0 +1,37 @@
+# Prior Art
+
+This page lists related projects and adjacent tools that influenced, overlap with, or can complement `ruby-bindgen`.
+
+## C/C++
+
+### SWIG
+
+- Project: [SWIG](https://www.swig.org/)
+- Scope: Multi-language binding generator for C and C++
+- Notes: Generates bindings for many languages including Ruby, Python, Java, and Go. Uses its own interface definition files rather than parsing headers directly. The most established tool in this space — active since 1996.
+
+### ffi_gen
+
+- Project: [ffi_gen](https://github.com/ffi/ffi_gen)
+- Scope: Generate Ruby FFI wrappers for C APIs
+- Notes: Has not been updated in over a decade and includes custom libclang bindings versus using [ffi-clang](https://github.com/ioquatix/ffi-clang).
+
+### rbind
+
+- Project: [rbind](https://github.com/D-Alex/rbind)
+- Scope: C++ binding generator with a custom parser approach
+- Notes: Has not been updated in four years and is coupled to OpenCV
+
+## Rust
+
+### Magnus
+
+- Project: [magnus](https://github.com/matsadler/magnus)
+- Scope: Rust crate for Ruby bindings
+- Notes: Not a direct Ruby generator alternative for C/C++, but useful as a design reference for Ruby-native APIs from another language.
+
+### rb-sys
+
+- Project: [rb-sys](https://github.com/oxidize-rb/rb-sys)
+- Scope: Rust bindings for the Ruby C API
+- Notes: Provides low-level Rust bindings to Ruby, auto-generated from `ruby.h` using rust-bindgen.

data/docs/troubleshooting.md

@@ -0,0 +1,243 @@
+# Troubleshooting
+
+Common failures and how to fix them. Section headings match the exact
+error string `ruby-bindgen` prints, so you can search for the message
+verbatim.
+
+## Pipeline and Failure Points
+
+```mermaid
+flowchart LR
+  A["config.yaml"] --> B["ruby-bindgen"]
+  B --> C["libclang parse"]
+  C --> D["generated bindings"]
+  D --> E["compile/link (Rice/CMake)"]
+  D --> F["runtime load (FFI)"]
+
+  X1["Fail: bad path / missing dirs"] -.-> A
+  X2["Fail: libclang not found"] -.-> C
+  X3["Fail: missing include args"] -.-> C
+  X4["Fail: empty output due to filters"] -.-> D
+  X5["Fail: linker missing symbols"] -.-> E
+  X6["Fail: shared library not found"] -.-> F
+```
+
+For the full backtrace on any of these errors, set `BINDGEN_DEBUG=1`.
+
+## `Error: Config file not found: <path>`
+
+Cause:
+- Wrong path passed to `ruby-bindgen`
+
+Fix:
+```bash
+ruby-bindgen /absolute/path/to/config.yaml
+```
+
+## `Error: Config must specify 'output'`
+
+Cause:
+- The YAML file is missing the required top-level `output:` key.
+
+Fix:
+- Add `output: /path/to/output/dir` (the directory generated bindings are written to).
+
+## `Error: Config must specify 'format'`
+
+Cause:
+- The YAML file is missing the required top-level `format:` key.
+
+Fix:
+- Add `format: Rice` (C++ via Rice), `format: FFI` (C via FFI), or `format: CMake` (CMake build files).
+
+## `Error: Format must be 'FFI', 'Rice', or 'CMake', got: <value>`
+
+Cause:
+- `format:` is set to something other than the three accepted values. Match is case-sensitive.
+
+Fix:
+- Use exactly `Rice`, `FFI`, or `CMake`.
+
+## `Error: Input path must be a directory: <path>`
+
+Cause:
+- `input:` points to a missing path or file (not a directory).
+
+Fix:
+- Set `input:` to an existing directory containing headers. For `format: CMake`, `input:` defaults to `output:` (the directory containing the generated `*-rb.cpp` files).
+
+## `Error: Output path must be a directory: <path>`
+
+Cause:
+- `output:` directory does not exist.
+
+Fix:
+```bash
+mkdir -p /path/to/output
+ruby-bindgen config.yaml
+```
+
+## `Error: Project name must be a valid C/C++ identifier (hyphens allowed): <name>`
+
+Cause:
+- `project:` contains characters other than letters, digits, underscore, or hyphen, or starts with a digit.
+
+Fix:
+- Use a name like `my_extension` or `my-extension`. Hyphens are normalized to underscores in generated C++ identifiers.
+
+## `Error: Rice include header not found: <path>`
+
+Cause:
+- `include:` (under a Rice config) names a header that does not exist under `output:`.
+
+Fix:
+- Confirm the file path is relative to `output:` and that the header is present before running. Without it, every generated `*-rb.hpp` would `#include` a missing file and the C++ build would fail far from the cause.
+
+## `Error: libclang library not found: <path>`
+
+Cause:
+- `clang.libclang:` (or `clang-cl.libclang:`) explicitly points to a missing shared library.
+
+Fix:
+- Either correct the path or remove the `libclang:` key and rely on `ffi-clang`'s default discovery.
+
+## `Error: clang args must be a YAML list, got: String`
+
+Cause:
+- `clang.args:` (or `clang-cl.args:`) is written as a single string instead of a YAML sequence.
+
+Fix:
+```yaml
+clang:
+  args:
+    - -I/usr/include
+    - -std=c++17
+    - -xc++
+```
+
+## `libclang` runtime load failures
+
+Symptoms:
+- FFI load error for libclang
+- Parser startup fails before processing files
+
+Fix:
+- Set the toolchain `libclang` path in config (`clang:` or `clang-cl:`)
+- Verify the shared library exists and matches your architecture
+
+Example:
+
+```yaml
+clang:
+  libclang: /usr/lib/llvm-17/lib/libclang.so
+  args:
+    - -I/usr/lib/clang/17/include
+    - -xc++
+```
+
+## Parse errors for standard/library types
+
+Symptoms:
+- Many unknown-type diagnostics
+- Generated files missing expected classes/functions
+
+Cause:
+- Missing include paths or language flags in `clang.args`
+
+Fix:
+- Add system and project include paths
+- Add `-xc++` for C++ headers (or `-xc` for C)
+- Add `-std=c++17` (or your required standard)
+
+## Empty or incomplete generated output
+
+Cause:
+- `match` glob too narrow
+- `skip` glob too broad
+- `export_macros` filters out everything
+
+Fix:
+- Validate `match`/`skip` patterns
+- Temporarily remove `export_macros` and re-run to confirm filtering
+
+## C++ compile failures after generation
+
+Common causes:
+- Missing includes in generated files
+- Default argument edge cases
+- Symbols declared in headers but not exported by the library
+
+Fix:
+- Use `symbols.skip` for problematic APIs, including overload-specific signatures when needed
+- Add refinement files for custom behavior
+- See [Updating Bindings](updating_bindings.md) for durable maintenance workflows
+
+## CMake generation produced empty `target_sources`
+
+Cause:
+- No `*-rb.cpp` files in `output` yet
+
+Fix:
+- Run `format: Rice` generation first
+- Then run `format: CMake`
+
+## FFI runtime cannot load shared library
+
+Cause:
+- `library_names` / `library_versions` do not match installed artifacts
+
+Fix:
+- Set `library_names` to base names
+- Add likely version suffixes to `library_versions`
+- If the library is outside the standard loader path, use `library_search_path` and set the corresponding environment variable at runtime
+- Confirm installation path is on loader search path
+
+## Windows-specific
+
+ruby-bindgen runs on Windows under both MSVC (mswin Ruby builds) and MinGW.
+The toolchain is auto-detected via `RUBY_PLATFORM` — `mswin` uses the
+`clang-cl:` config block, everything else uses `clang:`.
+
+### Choosing MSVC vs MinGW
+
+- **MSVC (`mswin`)** — recommended if you need to link against vcpkg or
+  other MSVC-built dependencies. Uses `clang-cl` (Clang's MSVC-compatible
+  driver) for header parsing.
+- **MinGW** — uses regular `clang` and works with Unix-style include paths.
+  Easier setup if the library is already buildable with MinGW.
+
+### libclang load failure on Windows
+
+Symptoms:
+- `Error: libclang library not found: ...`
+- FFI load error at startup
+
+Fix:
+- Visual Studio bundles libclang at
+  `C:\Program Files\Microsoft Visual Studio\<edition>\<year>\VC\Tools\Llvm\x64\bin\libclang.dll`.
+  Either install the "Clang/LLVM tools" component in the VS installer or
+  install LLVM standalone and set `clang-cl.libclang:` to its `libclang.dll`.
+- For MinGW Ruby, install LLVM via `pacman -S mingw-w64-clang-x86_64-clang`
+  (or the appropriate variant) and set `clang.libclang:` to the resulting
+  `libclang.dll`.
+
+### Path separators
+
+Use forward slashes (`/`) in YAML config paths even on Windows. The
+inputter normalizes backslashes internally, but forward slashes avoid
+YAML escape issues.
+
+### vcpkg integration (MSVC)
+
+If your library is installed via vcpkg, point `clang-cl.args:` at the
+vcpkg include directory and `library_search_path:` at the bin directory:
+
+```yaml
+clang-cl:
+  libclang: C:/Program Files/Microsoft Visual Studio/2022/Community/VC/Tools/Llvm/x64/bin/libclang.dll
+  args:
+    - -IC:/vcpkg/installed/x64-windows/include
+    - -std:c++17
+
+library_search_path: PATH
+```