ruby-bindgen 1.0.0

data/docs/cpp/customizing.md

@@ -0,0 +1,124 @@
+# Customizing Bindings
+
+`ruby-bindgen` tries its best to generate compilable Rice code. It has been battle tested against [OpenCV](https://github.com/opencv/opencv), which is a large, complex C++ API with over a thousand classes and ten thousand methods.
+
+However, complex libraries may require some customization. Customizations fall into three categories:
+
+* Configuration
+* Refinements
+* Fixes
+
+## Configuration
+
+Some issues are best solved via the [configuration](../configuration.md) file rather than editing generated code:
+
+- [Symbol filtering](../configuration.md#skip): Skip functions that cause linker errors or aren’t meant for external use by name or regex pattern
+- [Version guards](../configuration.md#versions): Wrap symbols in `#if VERSION >= N` guards so bindings compile against multiple library versions
+- [Export macros](../configuration.md#export-macros): Limit bindings to exported symbols, preventing linker errors from internal functions
+- [Name mappings](../configuration.md#name-mappings): Override generated Ruby class and method names with exact strings or regex patterns
+
+## Refinements
+
+Ruby classes are open, meaning you can reopen an existing class and add methods to it. Refinements take advantage of this to extend generated bindings with additional functionality. Note that this is not the same as Ruby's built-in [refinements](https://docs.ruby-lang.org/en/master/syntax/refinements_rdoc.html), which are scoped. These additions are global.
+
+Common reasons to add refinements include:
+
+| Addition                | What It Adds                                             |
+|-------------------------|----------------------------------------------------------|
+| Expected methods        | `inspect`, `to_s`                                        |
+| Modules                 | `include_module(rb_mComparable)`, `define_method("<=>")` |
+| Template instantiations | `Mat<unsigned char>`                                     |
+| Type conversions        | `to_*`                                                   |
+| Exceptions              | Custom exception class hierarchy                         |
+| Custom type handling    | `Type<T>`, `From_Ruby<T>`, and `To_Ruby<T>`              |
+| Custom STL names        | `define_vector<cv::Vec3b>(...)`                          |
+| Non-member operators    | `+`, `-`, `*`, `/`, `==`                                 |
+| Iteration               | Add `std::iterator_traits`                               |
+| Method renames          | `rb_alias` to rename methods to match Ruby idioms        |
+
+Just like in Ruby, you can take advantage of Ruby’s open classes to add new functionality.
+
+To do this, create a directory to contain additions. The directory can be named anything, but a suggested convention is to name it `refinements`. Here is an example layout:
+
+```
+ext/
+├── generated/            # Generated files (output: ./ext/generated)
+│   ├── matrix-rb.hpp
+│   ├── matrix-rb.cpp
+│   ├── matrix-rb.ipp
+│   └── my_extension-rb.cpp
+├── include/
+│   └── matrix.hpp
+├── refinements/          # Manual additions (never overwritten)
+│   ├── CMakeLists.txt
+│   ├── matrix_refinements.hpp
+│   ├── matrix_refinements.cpp
+│   └── ...
+```
+
+Create a new file in `refinements/` for each generated Rice file you want to extend. For example, if you want to add functionality to `matrix-rb.cpp`, create `refinements/matrix_refinements.hpp` and `refinements/matrix_refinements.cpp`. Define a new init function such as `Init_Matrix_Refinements` in those files.
+
+Next add the `.cpp` file to `refinements/CMakeLists.txt`:
+   ```cmake
+   target_sources(${CMAKE_PROJECT_NAME} PRIVATE
+     "matrix_refinements.cpp")
+   ```
+Then in the generated `generated/my_extension-rb.cpp` file, include the refinement header and call `Init_Matrix_Refinements()`.
+
+Using refinements has a lot of advantages:
+
+- Regeneration Safe: Your updates will not be overwritten with the exception of the `my_extension-rb.cpp` file
+- Reuse `_instantiate` methods - Refinements can `#include` generated `.ipp` files to call [`_instantiate` functions](templates.md#template-instantiate-files-ipp) with new type arguments.
+
+### Example
+
+Here is an example `refinements/matrix_refinements.cpp` file:
+
+```cpp
+#include <sstream>
+#include "../include/matrix.hpp"
+#include "../generated/matrix-rb.hpp"
+#include "../generated/matrix-rb.ipp"
+#include "matrix_refinements.hpp"
+
+using namespace Rice;
+
+void Init_Matrix_Refinements()
+{
+  // Reopen the class that was already defined by generated code
+  Rice::Data_Type<Matrix> matrix;
+
+  matrix.
+    define_method("to_s", [](const Matrix& self) -> std::string
+    {
+      std::ostringstream stream;
+      stream << self;
+      return stream.str();
+    });
+
+  // Rename a method to better match Ruby idioms
+  rb_alias(matrix, rb_intern("[]"), rb_intern("call"));
+
+  // Instantiate additional templates not in the generated code
+  Matrix_instantiate<double>(rb_mMyExtension, "MatrixDouble");
+}
+```
+
+## Fixes
+
+### Manual Edits
+
+Sometimes you need to **modify** the generated Rice code. Common reasons include:
+
+| Change Type       | Example                         | Why                                                                                    |
+|-------------------|---------------------------------|----------------------------------------------------------------------------------------|
+| Missing includes  | `#include <core.hpp>` | Generated file references types from headers it doesn't include                        |
+| Version guards    | `#if VERSION >= 2`              | API only available in certain library versions                                         |
+| Default values    | Remove `Stream::Null()` default | Avoid hardware-dependent functions such as CUDA initialization                         |
+
+- Mark manual changes with `// Manual` comments so they're searchable: `grep -r "// Manual" ext/`
+- Include order matters: System/library headers should come before the primary header, local project headers after
+- Watch fluent chain syntax when commenting out methods: change the preceding `.` to `;` to terminate the chain
+- Refinements can include generated `.ipp` files to reuse `_instantiate` functions with additional type arguments
+
+If you have manual edits, you will need a strategy for preserving them when you [regenerate bindings](../updating_bindings.md).

data/docs/cpp/enums.md

@@ -0,0 +1,42 @@
+# Enums
+
+`ruby-bindgen` generates Rice enum bindings for both scoped and unscoped C++ enums. For details on the generated Ruby enum API (comparison, conversion, bitwise operations), see the Rice [Enums](https://ruby-rice.github.io/4.x/bindings/enums/) documentation.
+
+## Scoped Enums (enum class)
+
+```cpp
+enum class Color
+{
+    Red, Green, Blue
+};
+```
+
+Generates a Rice enum with properly scoped values.
+
+## Unscoped Enums
+
+Unscoped enums in namespaces have values at namespace scope:
+
+```cpp
+namespace cv
+{
+    enum BorderType
+    {
+        BORDER_CONSTANT, BORDER_REPLICATE
+    };
+}
+// Values are cv::BORDER_CONSTANT, not cv::BorderType::BORDER_CONSTANT
+```
+
+Unscoped enums inside classes have values qualified with the enum name:
+
+```cpp
+class Buffer
+{
+    enum Target
+    {
+        ARRAY_BUFFER, ELEMENT_ARRAY_BUFFER
+    };
+};
+// Values are Buffer::Target::ARRAY_BUFFER
+```

data/docs/cpp/filtering.md

@@ -0,0 +1,35 @@
+# 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]]`
+- **Variadic**: Functions with `...` parameters
+- **Deleted**: Methods marked `= delete`
+- **Private/Protected**: Non-public members
+- **Template functions**: Non-member function templates (e.g., `template<typename T> void func()`)
+- **Anonymous namespaces**: Internal implementation details
+
+## std:: Typedefs
+
+Typedefs to `std::` types are skipped since Rice handles them automatically:
+
+```cpp
+typedef std::string String;  // Skipped - Rice handles std::string
+```
+

data/docs/cpp/getting_started.md

@@ -0,0 +1,80 @@
+# Getting Started with Rice Bindings
+
+This guide walks you through generating Rice (C++) bindings for a C++ library.
+
+## 1. Create a configuration file
+
+Create a file named `rice-bindings.yaml`:
+
+```yaml
+project: my_extension
+input: ./include
+output: ./ext/generated
+format: Rice
+
+match:
+  - "**/*.hpp"
+
+clang:
+  args:
+    - -I./include
+    - -std=c++17
+    - -xc++
+```
+
+Key options:
+
+- `project` — name used for the extension init function (`Init_my_extension`) and project wrapper files
+- `input` — directory containing header files
+- `output` — where generated C++ files are written
+- `match` — glob patterns selecting which headers to process
+- `clang.args` — compiler arguments; `-xc++` tells clang to parse as C++, `-std=c++17` sets the language standard
+
+Paths are relative to the config file's directory, not the working directory.
+
+See [Configuration](../configuration.md) for all options, including [symbol filtering](../configuration.md#symbols), [export macros](../configuration.md#export-macros), [name mappings](../configuration.md#name-mappings), and [version guards](../configuration.md#versions).
+
+## 2. Generate bindings
+
+```bash
+ruby-bindgen rice-bindings.yaml
+```
+
+This produces `.cpp`, `.hpp`, and optionally `.ipp` files for each matched header, plus project wrapper files. See [Rice Output](output.md) for details.
+
+## 3. Generate CMake build files (optional)
+
+If you want `ruby-bindgen` to generate CMake build files, create a second config:
+
+`cmake-bindings.yaml`:
+
+```yaml
+project: my_extension
+output: ./ext/generated
+format: CMake
+
+include_dirs:
+  - "${CMAKE_CURRENT_SOURCE_DIR}/../include"
+```
+
+Then run it **after** the Rice generation:
+
+```bash
+ruby-bindgen cmake-bindings.yaml
+```
+
+See [CMake Bindings](../cmake/cmake_bindings.md) for details.
+
+## 4. Build the extension
+
+```bash
+cd ./ext/generated
+cmake --preset linux-debug    # or macos-debug, msvc-debug, etc.
+cmake --build build/linux-debug
+```
+
+## 5. Packaging
+
+For packaging your extension as a gem, see the Rice [Packaging](https://ruby-rice.github.io/4.x/packaging/packaging/) documentation.
+
+For a complete, fully automated example see [BitmapPlusPlus-ruby](https://ruby-rice.github.io/BitmapPlusPlus-ruby/).

data/docs/cpp/iterators.md

@@ -0,0 +1,94 @@
+# Iterators
+
+`ruby-bindgen` automatically generates Rice `define_iterator` calls for C++ classes that expose iterator methods. This provides Ruby's `Enumerable` module support for C++ containers. For details on how Rice bridges C++ iterators to Ruby, see the Rice [Iterators](https://ruby-rice.github.io/4.x/bindings/iterators/) documentation.
+
+## Automatic Iterator Detection
+
+When `ruby-bindgen` encounters a C++ class with `begin()` and `end()` methods that return iterators, it automatically generates the appropriate `define_iterator` calls. For example, a C++ class like:
+
+```cpp
+class Bitmap {
+public:
+    PixelIterator begin();
+    PixelIterator end();
+};
+```
+
+Will generate:
+
+```cpp
+define_class_under<Bitmap>(rb_mModule, "Bitmap").
+    define_iterator<PixelIterator(Bitmap::*)()>(&Bitmap::begin, &Bitmap::end, "each");
+```
+
+**Note:** If a class only defines `begin() const` and `end() const` (without non-const versions), the generated method will be `each_const`. Since Ruby conventions expect `each`, `ruby-bindgen` automatically aliases `each` to `each_const` in this case.
+
+## Multiple Iterator Types
+
+`ruby-bindgen` handles classes with multiple iterator types, such as const iterators, reverse iterators, and const reverse iterators:
+
+| Method Pair           | Ruby Method Name     |
+|-----------------------|----------------------|
+| `begin()`/`end()`     | `each`               |
+| `begin() const`/`end() const` | `each_const` |
+| `rbegin()`/`rend()`   | `each_reverse`       |
+| `rbegin() const`/`rend() const` | `each_reverse_const` |
+
+## Incomplete Iterator Traits
+
+Some C++ libraries define iterators that lack the required `std::iterator_traits` typedefs. These iterators are missing one or more of:
+
+- `value_type`
+- `reference`
+- `pointer`
+- `difference_type`
+- `iterator_category`
+
+Rice's `define_iterator` requires these traits to function properly. Without them, you'll see compile errors like:
+
+```
+error C2039: 'value_type': is not a member of 'std::iterator_traits<MyIterator>'
+```
+
+### Automatic Traits Generation
+
+`ruby-bindgen` automatically detects incomplete iterators and generates `std::iterator_traits` specializations for them. For example, given an iterator like:
+
+```cpp
+// Iterator WITHOUT proper std::iterator_traits
+class IncompleteIterator
+{
+public:
+    IncompleteIterator() : ptr_(nullptr) {}
+    explicit IncompleteIterator(Pixel* p) : ptr_(p) {}
+    Pixel& operator*() const { return *ptr_; }
+    IncompleteIterator& operator++() { ++ptr_; return *this; }
+    bool operator!=(const IncompleteIterator& other) const { return ptr_ != other.ptr_; }
+
+private:
+    Pixel* ptr_;
+    // NOTE: Missing value_type, reference, pointer, difference_type, iterator_category
+};
+```
+
+`ruby-bindgen` will generate:
+
+```cpp
+// Iterator traits specializations for iterators missing std::iterator_traits
+namespace std
+{
+  template<>
+  struct iterator_traits<iter::IncompleteIterator>
+  {
+    using iterator_category = forward_iterator_tag;
+    using value_type = iter::Pixel;
+    using difference_type = ptrdiff_t;
+    using pointer = iter::Pixel*;
+    using reference = iter::Pixel&;
+  };
+}
+```
+
+## Examples
+
+See [test/headers/cpp/iterators.hpp](https://github.com/ruby-rice/ruby-bindgen/blob/main/test/headers/cpp/iterators.hpp) for example iterator classes, including both complete and incomplete iterators. The generated bindings are in [test/bindings/cpp/iterators-rb.cpp](https://github.com/ruby-rice/ruby-bindgen/blob/main/test/bindings/cpp/iterators-rb.cpp).

data/docs/cpp/operators.md

@@ -0,0 +1,170 @@
+# Operators
+
+`ruby-bindgen` automatically generates Rice bindings for C++ operators, mapping them to Ruby methods. For the complete C++ to Ruby operator mapping tables, see the Rice [Operators](https://ruby-rice.github.io/4.x/bindings/operators/) documentation.
+
+## Non-Member Operators
+
+C++ allows operators to be defined as non-member (free) functions. Ruby doesn't have the concept of non-member functions — all methods belong to a class. Therefore, `ruby-bindgen` automatically converts non-member operators to instance methods on the first argument's class:
+
+```cpp
+class Matrix
+{
+public:
+    int rows, cols;
+};
+
+// Non-member operators
+Matrix& operator+=(Matrix& a, const Matrix& b);
+Matrix& operator-=(Matrix& a, const Matrix& b);
+Matrix& operator*=(Matrix& a, double scalar);
+```
+
+`ruby-bindgen` generates:
+
+```cpp
+rb_cMatrix.
+    define_method("assign_plus", [](Matrix& self, const Matrix& other) -> Matrix&
+    {
+      self += other;
+      return self;
+    }).
+    define_method("assign_minus", [](Matrix& self, const Matrix& other) -> Matrix&
+    {
+      self -= other;
+      return self;
+    }).
+    define_method("assign_multiply", [](Matrix& self, double other) -> Matrix&
+    {
+      self *= other;
+      return self;
+    });
+```
+
+Ruby usage:
+
+```ruby
+matrix1 = Matrix.new
+matrix2 = Matrix.new
+
+matrix1.assign_plus(matrix2)   # Calls operator+=(matrix1, matrix2)
+matrix1.assign_multiply(2.0)   # Calls operator*=(matrix1, 2.0)
+```
+
+### Non-Member Unary Operators
+
+Non-member unary operators (common in libraries like OpenCV) are wrapped via lambdas:
+
+```cpp
+MatExpr operator~(const Mat& m);   // Bitwise NOT
+MatExpr operator-(const Mat& m);   // Negation
+MatExpr operator+(const Mat& m);   // Unary plus
+```
+
+`ruby-bindgen` generates:
+
+```cpp
+rb_cMat.
+    define_method("~", [](const Mat& self) -> MatExpr
+    {
+      return ~self;
+    }).
+    define_method("-@", [](const Mat& self) -> MatExpr
+    {
+      return -self;
+    }).
+    define_method("+@", [](const Mat& self) -> MatExpr
+    {
+      return +self;
+    });
+```
+
+Ruby usage:
+
+```ruby
+mat = Mat.new
+result = ~mat   # Bitwise NOT
+result = -mat   # Negation
+result = +mat   # Unary plus
+```
+
+### Streaming Operator
+
+The `<<` operator is often used for stream-like semantics in C++. `ruby-bindgen` handles two cases:
+
+1. **Output streaming** (`std::ostream& operator<<(std::ostream&, const T&)`) — converted to `inspect` methods on the streamed class.
+
+2. **Other streaming** (e.g., `FileStorage& operator<<(FileStorage&, const T&)`) — converted to `<<` instance methods.
+
+```cpp
+// Output streaming - generates inspect method on Printable
+std::ostream& operator<<(std::ostream& os, const Printable& p);
+
+// FileStorage streaming - generates << method on FileStorage
+FileStorage& operator<<(FileStorage& fs, const std::string& value);
+FileStorage& operator<<(FileStorage& fs, int value);
+FileStorage& operator<<(FileStorage& fs, const cv::Mat& mat);
+```
+
+The generated Ruby code groups all non-member operators by their target class:
+
+```cpp
+rb_cPrintable.
+    define_method("inspect", [](const Printable& self) -> std::string
+    {
+      std::ostringstream stream;
+      stream << self;
+      return stream.str();
+    });
+
+rb_cFileStorage.
+    define_method("<<", [](FileStorage& self, const std::string& other) -> FileStorage&
+    {
+      self << other;
+      return self;
+    }).
+    define_method("<<", [](FileStorage& self, int other) -> FileStorage&
+    {
+      self << other;
+      return self;
+    });
+```
+
+## Conversion Operators
+
+C++ [conversion operators](https://en.cppreference.com/w/cpp/language/cast_operator) are mapped to Ruby `to_*` methods:
+
+```cpp
+operator double() const;         // to_f
+operator bool() const;           // to_bool
+operator std::string() const;    // to_s
+```
+
+### Conversion Type Mappings
+
+| C++ Type | Ruby Method | Ruby Class |
+|:---------|:------------|:-----------|
+| `int` | `to_i` | `Integer` |
+| `long` | `to_l` | `Integer` |
+| `long long` | `to_i64` | `Integer` |
+| `short` | `to_i16` | `Integer` |
+| `unsigned int` | `to_u` | `Integer` |
+| `unsigned long` | `to_ul` | `Integer` |
+| `unsigned long long` | `to_u64` | `Integer` |
+| `unsigned short` | `to_u16` | `Integer` |
+| `int8_t` | `to_i8` | `Integer` |
+| `int16_t` | `to_i16` | `Integer` |
+| `int32_t` | `to_i32` | `Integer` |
+| `int64_t` | `to_i64` | `Integer` |
+| `uint8_t` | `to_u8` | `Integer` |
+| `uint16_t` | `to_u16` | `Integer` |
+| `uint32_t` | `to_u32` | `Integer` |
+| `uint64_t` | `to_u64` | `Integer` |
+| `size_t` | `to_size` | `Integer` |
+| `float` | `to_f32` | `Float` |
+| `double` | `to_f` | `Float` |
+| `long double` | `to_ld` | `Float` |
+| `bool` | `to_bool` | `TrueClass` / `FalseClass` |
+| `std::string` | `to_s` | `String` |
+| `const char*` | `to_s` | `String` |
+
+Custom types are mapped to `to_<typename>` in snake_case (e.g., `operator MyClass()` becomes `to_my_class`). Pointer conversions map to `to_ptr` or `to_const_ptr`.

data/docs/cpp/output.md

@@ -0,0 +1,125 @@
+# Rice Output
+
+## Header Files
+
+For every C++ header file, `ruby-bindgen` generates a .hpp and .cpp file. These files have the same name as the C++ header but with the addition of `-rb` at the end. For example, a C++ header file called `matrix.hpp` will generate in `matrix-rb.hpp` and `matrix-rb.cpp`. If the C++ header file declares a template class, then a third file will be generated called `matrix-rb.ipp`.
+
+``` mermaid
+flowchart LR
+    subgraph Input
+        H1["matrix.hpp"]
+        CF["rice-bindings.yaml"]
+    end
+
+    H1 & CF --> RB["ruby-bindgen"]
+
+    subgraph "Rice Output"
+        R1["matrix-rb.cpp"]
+        R2["matrix-rb.hpp"]
+        R3["matrix-rb.ipp"]
+    end
+
+    RB --> R1 & R2 & R3
+```
+
+The `.hpp` file declares an `Init_` function (e.g., `Init_Matrix`) that registers the classes, methods, and enums from that header with Rice.
+
+The `.cpp` file defines that `Init_` function with the actual Rice bindings code.
+
+The `.ipp` file is only generated when the header declares template classes. It contains one `_instantiate` function per template class that can be used to instantiate the template. The `-rb.ipp` files can be reused across translated units. See [Templates](templates.md#template-instantiate-files-ipp) for details.
+
+## Init Function Names
+
+Each generated file has an `Init_` function. To avoid conflicts when multiple files have the same name in different directories (e.g., `core/version.hpp` and `dnn/version.hpp`), the function name includes the directory path:
+
+| File Path | Init Function |
+|-----------|---------------|
+| `version.hpp` | `Init_Version` |
+| `core/version.hpp` | `Init_Core_Version` |
+| `dnn/version.hpp` | `Init_Dnn_Version` |
+| `core/hal/interface.hpp` | `Init_Core_Hal_Interface` |
+
+The top-level directory is always removed to avoid overly long names (e.g., `opencv2/calib3d.hpp` becomes `Init_Calib3d`, and `opencv2/core/version.hpp` becomes `Init_Core_Version`).
+
+## Project Files
+
+When you set the `project` option in your configuration, `ruby-bindgen` also generates project-level wrapper files that tie everything together:
+
+```mermaid
+flowchart LR
+    subgraph Input
+        CF["rice-bindings.yaml"]
+    end
+
+    CF --> RB["ruby-bindgen"]
+
+    subgraph "Project Files"
+        P1["my_extension-rb.cpp"]
+        P2["my_extension-rb.hpp"]
+        P3["rice_include.hpp"]
+    end
+
+    RB --> P1 & P2 & P3
+```
+
+* `my_extension-rb.hpp` declares the main Ruby init function `Init_my_extension` with the appropriate export attribute (`__declspec(dllexport)` on Windows, `__attribute__((visibility("default")))` on Linux/macOS)
+* `my_extension-rb.cpp` defines `Init_my_extension`, which calls each per-header `Init_` function (e.g., `Init_Matrix`, `Init_Image`, `Init_Filter`)
+* `rice_include.hpp` is the default [include header](#include-header) that all generated translation units include
+
+To suppress project file generation, omit the `project` option from your configuration. This is useful when you want to manage the top-level init function yourself.
+
+## Include Header
+
+By default `ruby-bindgen` creates a default include files called `rice_include.hpp`. Its content is:
+
+```cpp
+#pragma once
+
+// Default Rice include header generated by ruby-bindgen
+// To customize, create your own header and specify it with the 'include:' config option
+#include <rice/rice.hpp>
+#include <rice/stl.hpp>
+```
+If the `rice_include.hpp` already exists, `ruby-bindgen` will not overwrite it.
+
+All generated headers include this file:
+
+```cpp
+#include "../../rice_include.hpp"  // relative path computed automatically
+
+void Init_MyClass();
+```
+
+Remember that C++ templates are instantiated per translation unit. If different translation units see different template definitions (e.g., one sees a `Type<T>` specialization and another doesn't), this causes an ODR (One Definition Rule) violation. The linker may silently pick the wrong instantiation, leading to subtle bugs.
+
+By centralizing all Rice includes in a single header that every generated file includes, all translation units see the same template definitions, preventing ODR violations.
+
+The include header is an ideal candidate for precompiled headers (PCH). Since every generated file includes it, precompiling this header can significantly speed up build times:
+
+```cmake
+# CMake example
+target_precompile_headers(my_extension PRIVATE
+  "${CMAKE_SOURCE_DIR}/rice_include.hpp"
+)
+```
+
+You can specify a custom include file by setting the `include` option in the configuration file. This will replace the default `rice_include.hpp` file and thus allow you to specify your own `include` files if necessary. Your custom header must include the Rice headers, plus any additional includes or definitions you want to be global.
+
+For example, it is a good place to add support for custom smart pointers. For example, OpenCV defines `cv::Ptr<T>` which inherits from `std::shared_ptr<T>`. The opencv-ruby bindings wrap this smart pointer in a custom header file that is then added to `rice_include.hpp`. That means all translation units see it, preventing ODR violations.
+
+A custom include file will not be overwritten by `ruby-bindgen`.
+
+## Init Function Call Graph
+
+When Ruby loads an extension, it calls the top-level `Init_<extension>` function, which in turn calls each per-header `Init_*` function to register classes, methods, and enums.
+
+```mermaid
+flowchart TD
+  A["Ruby loads extension"] --> B["Init_my_extension"]
+  B --> C["Init_Core"]
+  B --> D["Init_Mat"]
+  B --> E["Init_*"]
+  B --> G["Init_*_Refinements (manual, optional)"]
+```
+
+The extension `Init_<extension>` function is the top-level entry point and calls all per-header `Init_*` functions. Refinement init functions are optional manual hooks that run after generated definitions. See [refinements](customizing.md#refinements) for details.