ruby-bindgen 1.0.0

data/docs/configuration.md

@@ -0,0 +1,351 @@
+# Configuration
+
+`ruby-bindgen` uses a YAML configuration file to specify how bindings should be generated. This approach keeps your build configuration versioned and reproducible.
+
+```bash
+ruby-bindgen rice-bindings.yaml
+```
+
+For end-to-end examples, see [C Bindings](c/c_bindings.md), [C++ Bindings](cpp/cpp_bindings.md), and [CMake Bindings](cmake/cmake_bindings.md).
+
+## Required Options
+
+| Option   | Description                                                                                                       |
+|----------|-------------------------------------------------------------------------------------------------------------------|
+| `input`  | Directory containing the header files to parse. Required for `FFI` and `Rice`. For `CMake`, if omitted it defaults to `output` so the generator scans previously generated `*-rb.cpp` files. Can be absolute or relative to the config file location. |
+| `output` | Directory where generated binding files will be written. Can be absolute or relative to the config file location. |
+| `format` | Type of bindings to generate: `Rice` for C++, `FFI` for C, or `CMake` for CMakeLists.txt. |
+
+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.
+
+| Option          | Default            | Description                                                                               |
+|-----------------|--------------------|-------------------------------------------------------------------------------------------|
+| `match`         | `["**/*.{h,hpp}"]` for `FFI`/`Rice`, `["**/*-rb.cpp"]` for `CMake` | Array of glob patterns specifying which files to process. **Note:** removing a header from `match` does not delete its previously generated `*-rb.cpp` file. You must manually delete stale output files when removing headers. Auto-cleanup is not performed because `match` is often temporarily narrowed to regenerate a single file. |
+| `skip`          | `[]`               | Array of glob patterns specifying which files to skip. For Rice/FFI, these match header file paths. For CMake, these match generated `*-rb.cpp` file paths. In most cases, it's better to add skips to the Rice/FFI config so the files are never generated, rather than skipping them in CMake after the fact. |
+| `symbols`       | `{}`               | Symbol actions and name mappings grouped by type. See [Symbols](#symbols).                  |
+| `export_macros` | `[]`               | List of macros that indicate a function is exported. See [Export Macros](#export-macros). |
+| `version_check` | none | Identifier used for version guards. Required when `symbols.versions` is non-empty. For **Rice**, this is a C preprocessor macro — symbols are wrapped in `#if version_check >= version` / `#endif`. For **FFI**, this is a Ruby method name — symbols are wrapped in `if version_check >= version` / `end`. See [Versions](#versions). |
+
+## C (FFI) Options
+
+| Option             | Default  | Description |
+|--------------------|----------|-------------|
+| `project`          | **required** | Project name. Used for the loader file name (`{project}_ffi.rb`) which contains the library preamble and `require_relative`s for each content file. |
+| `library_names`    | `[]`     | Base names of shared libraries to load (e.g., `["proj"]` for `libproj`). |
+| `library_versions` | `[]`     | Library version suffixes to search for (e.g., `["25", "9"]`). Combined with `library_names` to build platform-specific search names like `libproj.so.25`. |
+| `module`           | filename | Ruby module name for the generated bindings. Defaults to the header filename camelized (e.g., `proj.h` → `Proj`). For the project loader, defaults to `project` camelized. Supports nested modules with `::` (e.g., `Proj::Api`). |
+| `library_search_path` | none | Name of an environment variable containing a directory path. When the env var is set at runtime, library names are searched in that directory first before falling back to standard search. For example, `library_search_path: PROJ_LIB_PATH` generates code that checks `ENV['PROJ_LIB_PATH']` and prepends that path to each library name. |
+
+## C++ (Rice) Options
+
+| Option          | Default        | Description |
+|-----------------|----------------|-------------|
+| `project`       | none           | Project name for the Ruby extension. Used for the `Init_` function name and project wrapper file names. Must be a valid C/C++ identifier. When provided, generates project wrapper files (`{project}-rb.cpp`, `{project}-rb.hpp`). When omitted, only per-file bindings are generated. |
+| `include`       | auto-generated | Path to a custom Rice include header. See [Include Header](cpp/output.md#include-header). |
+
+## CMake Options
+
+| Option         | Default | Description |
+|----------------|---------|-------------|
+| `project`      | none    | Project name used in the CMake `project()` command and build target name. When provided, generates the root `CMakeLists.txt` (with project setup, Rice fetch, Ruby detection) and `CMakePresets.json`. When omitted, only subdirectory `CMakeLists.txt` files are generated — useful when you manage the root project files yourself. |
+| `include_dirs` | `[]`    | List of include directory expressions added via `target_include_directories`. These are CMake expressions written directly into `CMakeLists.txt` (e.g., `${CMAKE_CURRENT_SOURCE_DIR}/../headers`). |
+| `guards`       | `{}`    | Map of raw CMake condition expressions to arrays of generated path patterns. Matching directories are emitted inside guarded `add_subdirectory(...)` blocks; matching `*-rb.cpp` files are emitted inside guarded `target_sources(...)` blocks. Exact paths and globs are both supported. |
+
+## Compiler Toolchain
+
+`ruby-bindgen` uses top-level toolchain keys to configure compiler settings for different platforms:
+
+- **`clang-cl:`** - Used when `RUBY_PLATFORM` contains `mswin` (MSVC toolchain)
+- **`clang:`** - Used on Linux, macOS, and MinGW
+
+| Option     | Default     | Description |
+|------------|-------------|-------------|
+| `libclang` | auto-detect | Path to the libclang shared library. Nested under `clang-cl:` or `clang:`. When specified, sets the `LIBCLANG` environment variable before loading ffi-clang. |
+| `args`     | `[]`        | Arguments passed to libclang for parsing (include paths, language standard, defines, etc.). Nested under `clang-cl:` or `clang:`. |
+
+You only need to include the toolchain sections for platforms you target.
+
+### Resolution Flow
+
+```mermaid
+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 (Linux, macOS, MinGW)"]
+  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:
+```bash
+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:
+```bash
+# 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:
+```bash
+# 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 and name mappings by type. The action groups are `skip`, `versions`, and `overrides`. Name mappings use `rename_types` and `rename_methods`.
+
+### Skip
+
+The `skip` key lists symbols to exclude from bindings. This works for functions, classes, enums, typedefs, unions, and variables. This is useful when:
+
+- Symbols have export macros but still aren't available (build configuration issues)
+- Symbols are internal/private APIs not meant for external use
+- Symbols cause linker errors due to missing definitions
+
+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
+
+#### How Matching Works
+
+For exact symbol matching, `ruby-bindgen` does not rely on just one spelling. It tries a small set of candidate names so that configuration can match what users usually write in headers.
+
+For a member function such as `cv::dnn::Layer::init`, the candidate set typically includes:
+
+- The simple spelling: `init`
+- The semantic qualified name from libclang: `cv::dnn::dnn4_v20241223::Layer::init`
+- A parent-type form that collapses inline namespaces: `cv::dnn::Layer::init`
+
+For overloads, the same shapes are also tried with parameter lists appended:
+
+- `init(const cv::Mat &)`
+- `cv::dnn::dnn4_v20241223::Layer::init(const cv::Mat &)`
+- `cv::dnn::Layer::init(const cv::Mat &)`
+
+This matters for libraries such as OpenCV, where public APIs are often declared inside versioned inline namespaces but users usually write the enclosing API name in configuration.
+
+Two additional normalizations are worth knowing:
+
+- Anonymous scopes are stripped from user-facing matches. For example, an enum constant reported by clang as `Outer::(unnamed enum at ... )::Value` can be matched as `Outer::Value`.
+- Macros only match by their simple name, because libclang does not provide a usable qualified name for macro definitions.
+
+```yaml
+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
+    - DeprecatedEnum                           # Skips an enum
+    - InternalUnion                            # Skips a union
+    - debugVariable                            # Skips a variable
+```
+
+### 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.
+
+```yaml
+format: Rice
+version_check: CV_VERSION
+symbols:
+  versions:
+    40100:
+      - cv::Foo::baz
+    40500:
+      - /cv::cuda::.*/
+```
+
+This generates:
+```cpp
+#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](c/version_guards.md) for a full example.
+
+```yaml
+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:
+```ruby
+if proj_version >= 60100
+  attach_function :proj_normalize_for_visualization, ...
+end
+```
+
+See [Version Guards](version_guards.md) for the Rice guide and [Version Detection](c/version_guards.md) 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, `:
+
+```yaml
+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:
+
+```yaml
+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 the same candidate set as exact names: simple names, semantic qualified names, and inline-namespace-collapsed member names when available. 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))`)
+- 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.
+
+```yaml
+export_macros:
+  - CV_EXPORTS
+  - CV_EXPORTS_W
+```
+
+### Common Library Macros
+
+| Library | Export Macros |
+|---------|--------------|
+| OpenCV | `CV_EXPORTS`, `CV_EXPORTS_W`, `CV_EXPORTS_W_SIMPLE` |
+| Qt | `Q_DECL_EXPORT`, `Q_CORE_EXPORT` |
+| Boost | `BOOST_*_DECL` |
+
+### 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` keys under `symbols` 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.
+
+```yaml
+symbols:
+  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.
+
+```yaml
+symbols:
+  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).

data/docs/contributing.md

@@ -0,0 +1,68 @@
+# Contributing
+
+Guidelines for changing `ruby-bindgen` and its generated-output tests.
+
+## Key Files
+
+- `lib/ruby-bindgen/generators/generator.rb` - base class shared by all generators
+- `lib/ruby-bindgen/generators/rice/rice.rb` - main AST walker for Rice code generation
+- `lib/ruby-bindgen/generators/rice/*.erb` - Rice templates
+- `lib/ruby-bindgen/generators/ffi/ffi.rb` - main AST walker for FFI code generation
+- `lib/ruby-bindgen/generators/cmake/cmake.rb` - CMake file generator
+- `test/headers/cpp/*.hpp` - C++ input headers for tests
+- `test/bindings/cpp/*-rb.cpp` - expected generated output (golden files)
+
+## Run Tests
+
+Run all tests before updating expected files:
+
+```bash
+bundle exec ruby -Ilib -Itest test/ffi_test.rb
+bundle exec ruby -Ilib -Itest test/rice_test.rb
+bundle exec ruby -Ilib -Itest test/cmake_test.rb
+```
+
+Run one test:
+
+```bash
+bundle exec ruby -Ilib -Itest test/rice_test.rb --name test_classes
+```
+
+Important:
+- Run `cmake_test` after `rice_test` because it scans generated `*-rb.cpp` files.
+
+## Updating Expected Files
+
+Only update expected outputs after all tests pass on current expectations.
+
+```bash
+UPDATE_EXPECTED=1 bundle exec ruby -Ilib -Itest test/rice_test.rb
+UPDATE_EXPECTED=1 bundle exec ruby -Ilib -Itest test/cmake_test.rb
+```
+
+## Test Coverage Requirement
+
+Every bug fix should include test coverage:
+
+- Add or adjust headers in `test/headers/cpp/`
+- Update expected generated outputs in `test/bindings/cpp/`
+
+For cross-file typedef issues, use:
+- `test/headers/cpp/cross_file_base.hpp`
+- `test/headers/cpp/cross_file_derived.hpp`
+
+## Regenerating opencv-ruby Bindings
+
+Use the project configs in:
+- `<opencv-ruby>/ext/rice-bindings.yaml`
+- `<opencv-ruby>/ext/cmake-bindings.yaml`
+
+Generate with:
+
+```bash
+cd <ruby-bindgen>
+# 1. Generate Rice source files
+bundle exec ruby -Ilib bin/ruby-bindgen <opencv-ruby>/ext/rice-bindings.yaml
+# 2. Generate CMake files
+bundle exec ruby -Ilib bin/ruby-bindgen <opencv-ruby>/ext/cmake-bindings.yaml
+```

data/docs/cpp/buffers.md

@@ -0,0 +1,24 @@
+# Buffers and Pointers
+
+`ruby-bindgen` automatically wraps some pointer parameters and return types. For details on using buffers and pointers from Ruby, see the Rice documentation on [Buffers](https://ruby-rice.github.io/4.x/bindings/buffers/) and [Pointers](https://ruby-rice.github.io/4.x/bindings/pointers/).
+
+Pointers to most fundamental types (`int*`, `double*`, `unsigned char*`, `void*`, etc.) and double pointers (`T**`) are automatically wrapped using Rice's `ArgBuffer` and `ReturnBuffer` classes:
+
+```cpp
+void processData(int* data, int size);           // ArgBuffer("data")
+void getMinMax(double* min, double* max);        // Out parameters via ArgBuffer
+int* createBuffer(int size);                     // ReturnBuffer
+void processArrays(float** matrices, int count); // Double pointer via ArgBuffer
+```
+
+`char*` and `wchar_t*` are treated as strings rather than raw buffers, so they do **not** use `ArgBuffer` or `ReturnBuffer`:
+
+```cpp
+void processCharBuffer(char* buffer, int length);  // Arg("buffer")
+```
+
+This distinction matters for APIs that mix byte buffers and strings:
+
+- `unsigned char*` is treated as a byte buffer
+- `char*` / `wchar_t*` are treated as string pointers
+- Any `T**` is treated as a buffer-style pointer, even when `T` is a class type

data/docs/cpp/classes.md

@@ -0,0 +1,139 @@
+# Classes & Structs
+
+`ruby-bindgen` generates Rice bindings for C++ classes and structs, including constructors, methods, member variables, and single inheritance. For details on how Rice wraps classes, see the Rice documentation on [Classes](https://ruby-rice.github.io/4.x/bindings/classes/), [Constructors](https://ruby-rice.github.io/4.x/bindings/constructors/), [Methods](https://ruby-rice.github.io/4.x/bindings/methods/), [Overloaded Methods](https://ruby-rice.github.io/4.x/bindings/overloaded_methods/), [Attributes](https://ruby-rice.github.io/4.x/bindings/attributes/), and [Constants](https://ruby-rice.github.io/4.x/bindings/constants/).
+
+## Constructors
+
+### Multiple Constructors
+
+All public, non-deleted, non-deprecated constructors are wrapped:
+
+```cpp
+class MyClass {
+    MyClass();
+    MyClass(int x);
+    MyClass(int x, int y);
+};
+```
+
+### Implicit Default Constructor
+
+If a class has no explicit constructors, the implicit default constructor is wrapped.
+
+### Skipped Constructors
+
+- Move constructors
+- Deleted constructors
+- Deprecated constructors
+- Constructors of abstract classes
+
+## Attributes
+
+### Public Member Variables
+
+Public member variables generate getter/setter methods via `define_attr`:
+
+```cpp
+class Point {
+public:
+    int x, y;  // Generates x, x=, y, y=
+};
+```
+
+### Static Member Variables
+
+Static members on classes use `define_singleton_attr`.
+
+### Constants
+
+`const` qualified variables and namespace-level variables generate Ruby constants.
+
+## Single Inheritance
+
+```cpp
+class Derived : public Base {};
+```
+
+Generates:
+```cpp
+define_class<Derived, Base>("Derived")
+```
+
+For template base class inheritance, see [Templates](templates.md#template-base-classes).
+
+## Methods
+
+### Overloaded Methods
+
+Overloaded methods are automatically detected and generate explicit type signatures:
+
+```cpp
+void process(int x);
+void process(double x);
+```
+
+Generates:
+```cpp
+define_method<void(MyClass::*)(int)>("process", &MyClass::process, Arg("x")).
+define_method<void(MyClass::*)(double)>("process", &MyClass::process, Arg("x"));
+```
+
+### Conversion Operators
+
+Type conversion operators generate appropriately named Ruby methods:
+
+```cpp
+operator bool() const;           // to_bool
+operator std::string() const;    // to_s
+operator int*();                 // to_ptr (non-const)
+operator const int*() const;     // to_const_ptr
+```
+
+Template parameter conversions in class templates use generic names (`to_ptr`, `to_const_ptr`) to avoid invalid method names.
+
+For a complete table of conversion type mappings, see the [Operators](operators.md#conversion-operators) page.
+
+### Callbacks
+
+`ruby-bindgen` understands C-style callbacks and generates the appropriate Rice [callback code](https://ruby-rice.github.io/4.x/bindings/callbacks/).
+
+### Safe Bool Idiom
+
+Pre-C++11 "safe bool idiom" using typedef to member function pointer is automatically skipped:
+
+```cpp
+typedef void (MyClass::*bool_type)() const;
+operator bool_type() const;  // Skipped
+```
+
+### Default Values
+
+`ruby-bindgen` preserves C++ default parameter values, handling namespace qualification and type constraints.
+
+Default values are automatically qualified with full namespace paths:
+
+```cpp
+void func(int flags = NORM_L2);           // -> cv::NORM_L2
+void func(Mat m = noArray());             // -> cv::noArray()
+void func(Scalar s = Scalar::all(0));     // -> cv::Scalar::all(0)
+```
+
+Default values referencing class template members preserve template parameters:
+
+```cpp
+template<typename T>
+class Quat {
+    static constexpr T EPS = 1e-6;
+    Quat(T eps = EPS);  // -> cv::Quat<T>::EPS
+};
+```
+
+Default parameter values are only generated for copyable types. `ruby-bindgen` detects non-copyable types via private copy constructors, deleted copy constructors (`= delete`), or inherited inaccessible copy constructors:
+
+```cpp
+class NonCopyable {
+    NonCopyable(const NonCopyable&) = delete;
+};
+
+void func(NonCopyable nc = NonCopyable());  // Default value NOT generated
+```

data/docs/cpp/cpp_bindings.md

@@ -0,0 +1,29 @@
+# C++ Bindings
+
+`ruby-bindgen` creates Ruby bindings for C++ libraries using [Rice](https://github.com/ruby-rice/rice). Creating C++ bindings takes more work than creating C bindings, so if a library provides both a C and C++ API you should use the C API.
+
+`ruby-bindgen` does 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. 
+
+For many libraries, the generated bindings will compile and work with no additional changes. For example, [BitmapPlusPlus-ruby](https://ruby-rice.github.io/BitmapPlusPlus-ruby/) is a fully automated set of bindings generated by `ruby-bindgen` for the BitmapPlusPlus library.
+
+For more complex libraries, like [OpenCV](https://github.com/opencv/opencv), some [customization](customizing.md) will likely be required.
+
+## Getting Started
+
+See [Getting Started](getting_started.md) for a step-by-step guide to creating your first Rice bindings.
+
+## Output
+
+See [Rice Output](output.md) for details on the generated files, including header files, project files, the include header, and the init function call graph.
+
+## Build System
+
+After generating Rice bindings, you will need to setup a build system for your extension. `ruby-bindgen` can generate [CMake build files](../cmake/cmake_bindings.md) to compile and link the generated bindings.
+
+## Packaging
+
+For packaging your extension as a gem, see the Rice [Packaging](https://ruby-rice.github.io/4.x/packaging/packaging/) documentation.
+
+## Example
+
+For a complete, fully automated example see [BitmapPlusPlus-ruby](https://ruby-rice.github.io/BitmapPlusPlus-ruby/).