ruby-bindgen 1.0.0

data/docs/c/library_loading.md

@@ -0,0 +1,53 @@
+# Library Loading
+
+FFI loads the target shared library at runtime. The `library_names`, `library_versions`, and `library_search_path` configuration options specify where to find the library.
+
+## Library Names
+
+`library_names` specifies the base names of the shared library. The loader turns each base name into one or more search names and passes them to `ffi_lib`:
+
+| Platform | `library_names: ["proj"]` searches for              |
+|----------|-----------------------------------------------------|
+| Linux    | `libproj`, `libproj.so.{version}`                   |
+| macOS    | `libproj`, `libproj.{version}`                      |
+| MinGW    | `libproj`, `libproj-{version}`                      |
+| MSVC     | `libproj`, `proj_{version}`                         |
+
+The unversioned `libproj` entry is always included as a fallback.
+
+The platform's loader appends the conventional shared-library suffix at
+load time (`.so` on Linux, `.dylib` on macOS, `.dll` on Windows), so a
+macOS entry like `libproj.25` resolves to `libproj.25.dylib`.
+
+## Library Versions
+
+C shared libraries use version suffixes that vary by platform and change across releases. `library_versions` lets you list known version suffixes so FFI can find whichever version is installed.
+
+For example, the [PROJ](https://proj.org/) coordinate transformation library has used these version suffixes across releases:
+
+```yaml
+library_names:
+  - proj
+library_versions:
+  - "25"    # PROJ 9.2
+  - "22"    # PROJ 8.x
+  - "19"    # PROJ 7.x
+  - "17"    # PROJ 6.1, 6.2
+  - "15"    # PROJ 6.0
+```
+
+This generates search names like `libproj.so.25`, `libproj.so.22`, etc. on Linux, `libproj.25` on macOS, `libproj-25` on MinGW, and `proj_25` on MSVC. The loader sorts the version suffixes in descending order before emitting them, so newer versions are tried first.
+
+If `library_versions` is omitted, only the unversioned name is searched. This works on most systems where the package manager creates an unversioned symlink (e.g., `libproj.so` → `libproj.so.25`).
+
+## Library Search Path
+
+If the library is installed outside standard operating system search paths, use `library_search_path`:
+
+```yaml
+library_names:
+  - proj
+library_search_path: PROJ_LIB_PATH
+```
+
+This generates loader code that checks `ENV["PROJ_LIB_PATH"]` at runtime and prepends that directory to every generated search name before falling back to the default search list.

data/docs/c/output.md

@@ -0,0 +1,96 @@
+# FFI Output
+
+`ruby-bindgen` generates a project file, an optional version file and one FFI binding file per header. The project file first loads the target library and then binding files.
+
+``` mermaid
+flowchart LR
+    subgraph Input
+        H1["mylib.h"]
+        H2["mylib_extra.h"]
+        CF["ffi-bindings.yaml"]
+    end
+
+    H1 & H2 & CF --> RB["ruby-bindgen"]
+
+    subgraph "FFI Output"
+        P["mylib_ffi.rb"]
+        V["mylib_version.rb"]
+        C1["mylib.rb"]
+        C2["mylib_extra.rb"]
+    end
+
+    RB --> P & V & C1 & C2
+```
+
+Given a project named `mylib` that matches `mylib.h` and `mylib_extra.h`:
+
+```
+output/
+  mylib_ffi.rb        # project file: require 'ffi', library preamble, require_relatives
+  mylib_version.rb    # version file: stub for runtime version detection (only with version_check)
+  mylib.rb            # content from mylib.h
+  mylib_extra.rb      # content from mylib_extra.h (reopens module)
+```
+
+## Project file (`mylib_ffi.rb`)
+
+```ruby
+# This file was generated by ruby-bindgen. Please do not edit by hand.
+require 'ffi'
+
+module Mylib
+  extend FFI::Library
+
+  def self.library_names
+    ["mylib"]
+  end
+
+  def self.search_names
+    # Cross-platform library name generation
+    # Handles .so, .dylib, .dll variants
+  end
+
+  ffi_lib self.search_names
+end
+
+require_relative './mylib'
+require_relative './mylib_extra'
+```
+
+## Version file (`mylib_version.rb`)
+
+When [`version_check`](../configuration.md#versions) is configured, a version file is generated with a stub method that you must implement to return the runtime library version. This file is preserved on subsequent runs so your implementation is not overwritten. See [Version Guards](version_guards.md) for details.
+
+```ruby
+module Mylib
+  def self.mylib_version
+    # Return the runtime library version as an integer.
+    # Example: 90602 for version 9.6.2
+    raise NotImplementedError, "Implement mylib_version to return the runtime library version number"
+  end
+end
+```
+
+## Content file (`mylib.rb`)
+
+```ruby
+module Mylib
+  # Structs
+  class MyStruct < FFI::Struct
+    layout :field1, :int,
+           :field2, :double
+  end
+
+  # Enums
+  MY_ENUM = enum(
+    :value_one, 0,
+    :value_two, 1
+  )
+
+  # Callbacks
+  callback :my_callback, [:int, :pointer], :void
+
+  # Functions
+  attach_function :my_function, :my_function, [:int, :string], :int
+end
+```

data/docs/c/types.md

@@ -0,0 +1,61 @@
+# Type Mapping
+
+## String and Pointer Types
+
+C uses `char *` for both strings and raw memory buffers. `ruby-bindgen` uses const-qualification and context to pick an FFI type as shown in the following table:
+
+| Context | `const char *` | `char *` |
+|---------|---------------|----------|
+| Function parameters | `:string` | `:pointer` |
+| Function returns | `:string` | `:pointer` |
+| Callback returns | `:pointer` | `:pointer` |
+| Struct/union fields | `:string` | `:pointer` |
+
+Since `const char *` is a read-only string, FFI can safely auto-convert it to a Ruby `String`. On the other hand, `char *` often indicates a caller-allocated buffer (e.g., `char *buf, size_t buf_size`), so it is safer to map it to `:pointer`. This allows callers to create the buffer with `FFI::MemoryPointer.new`. Callback returns always use `:pointer` regardless of const because FFI cannot manage the lifetime of callback-returned strings.
+
+If a specific function needs a different type mapping, use [`symbols: overrides:`](../configuration.md#overrides-ffi-only) to replace the generated signature.
+
+## Struct Pointer Types
+
+When a function parameter is a pointer to a struct, `ruby-bindgen` generates `StructName.by_ref`. This is correct for the common case of passing a single struct by pointer:
+
+```c
+int proj_get_area_of_use(PJ *obj, double *west, ...);
+// → attach_function :proj_get_area_of_use, ..., [:pointer, :pointer, ...], :int
+```
+
+However, `.by_ref` is **wrong** when the pointer is actually an array of structs. `ruby-bindgen` cannot distinguish these cases from the C signatures — both are `SomeStruct *`.
+
+Below are two common patterns to help decide.
+
+### Array parameters
+Look for a count parameter that either precedes or follows the struct pointer:
+
+```c
+PJ *proj_create_conversion(PJ_CONTEXT *ctx, ..., int param_count,
+                            const PJ_PARAM_DESCRIPTION *params);
+```
+
+Here `params` points to an array of `param_count` structs. The caller allocates the array with `FFI::MemoryPointer` and writes structs into it.
+
+### Array returns
+A function returns a pointer to a statically-allocated or heap-allocated array of structs:
+
+```c
+const PJ_OPERATIONS *proj_list_operations(void);
+```
+
+This returns a NULL-terminated array of `PJ_OPERATIONS` structs, not a single struct. The caller iterates the array by advancing the pointer.
+
+Use [`symbols: overrides:`](../configuration.md#overrides-ffi-only) to fix these:
+
+```yaml
+symbols:
+  overrides:
+    proj_create_conversion: "[:pointer, :string, :string, :string, :string, :string, :string, :int, :pointer], :pointer"
+    proj_list_operations: "[], :pointer"
+```
+
+## Union Pointer Types
+
+The same considerations apply to unions. When a function takes a pointer to a union, `ruby-bindgen` generates `UnionName.by_ref`. As with structs, this is wrong when the pointer is actually an array of unions — use [`symbols: overrides:`](../configuration.md#overrides-ffi-only) to fix these cases.

data/docs/c/version_guards.md

@@ -0,0 +1,105 @@
+# Version Detection
+
+When [`symbols.versions`](../configuration.md#versions) has entries, `ruby-bindgen` generates version-guarded Ruby conditionals and a `{project}_version.rb` skeleton file. You must implement the version detection method in that file — typically by calling the library's own version API.
+
+## Configuration
+
+This example is from [proj4rb](https://github.com/cfis/proj4rb), Ruby bindings for the [PROJ](https://proj.org/) coordinate transformation library. PROJ's API has grown significantly across versions — `proj_normalize_for_visualization` was added in 6.1.0, `proj_cleanup` in 6.2.0, and so forth.
+
+```yaml
+format: FFI
+project: proj
+module: Proj::Api
+version_check: proj_version
+
+library_names:
+  - proj
+
+symbols:
+  skip:
+    - PJ_INFO   # manually defined in version file
+    - proj_info # manually defined in version file
+
+  versions:
+    # 6.1.0
+    60100:
+      - proj_normalize_for_visualization
+
+    # 6.2.0
+    60200:
+      - proj_cleanup
+      - proj_as_projjson
+      - proj_create_crs_to_crs_from_pj
+
+    # 8.0.0
+    80000:
+      - proj_context_errno_string
+```
+
+The version file calls `proj_info()` and uses `PJ_INFO` to compute the runtime version number. Since those symbols are manually defined in the version file, add them to `skip` so they aren't also generated in the content files.
+
+## Generated Output
+
+The generator produces three things:
+
+**1. Version guards in content files** — version-specific symbols are wrapped in conditionals:
+
+```ruby
+if proj_version >= 60100
+  attach_function :proj_normalize_for_visualization, ...
+end
+if proj_version >= 60200
+  attach_function :proj_cleanup, :proj_cleanup, [], :void
+end
+```
+
+**2. Version require in the project file** (`proj_ffi.rb`):
+
+```ruby
+require_relative 'proj_version'
+require_relative './proj'
+```
+
+**3. Version skeleton file** (`proj_version.rb`) — generated once, then user-maintained:
+
+```ruby
+module Proj
+  module Api
+    def self.proj_version
+      # Return the runtime library version as an integer.
+      # Example: 90602 for version 9.6.2
+      raise NotImplementedError, "Implement proj_version to return the runtime library version number"
+    end
+  end
+end
+```
+
+## Implementing Version Detection
+
+Replace the skeleton with your library's version API. PROJ provides `proj_info()` which returns a `PJ_INFO` struct with `major`, `minor`, and `patch` fields. Since the version file is loaded before the generated content files, define the struct and function here:
+
+```ruby
+module Proj
+  module Api
+    class PjInfo < FFI::Struct
+      layout :major, :int,
+             :minor, :int,
+             :patch, :int,
+             :release, :string,
+             :version, :string,
+             :searchpath, :string,
+             :paths, :pointer,
+             :path_count, :ulong
+    end
+
+    attach_function :proj_info, :proj_info, [], PjInfo.by_value
+
+    def self.proj_version
+      info = proj_info
+      info[:major] * 10000 + info[:minor] * 100 + info[:patch]
+    end
+  end
+end
+```
+
+The version file is loaded before the content files, so `proj_version` is available when the guards execute. The skeleton is only generated if the file doesn't already exist — your implementation is preserved across re-runs.

data/docs/cmake/cmake_bindings.md

@@ -0,0 +1,19 @@
+# CMake Bindings
+
+The `CMake` format generates `CMakeLists.txt` and `CMakePresets.json` files for building Rice C++ bindings.
+
+Rice supports building extensions with either [extconf.rb](https://ruby-rice.github.io/4.x/packaging/extconf.rb/) or [CMake](https://ruby-rice.github.io/4.x/packaging/cmake/). While `extconf.rb` works for simple bindings, CMake is vastly superior for anything more complex — it provides better cross-platform support, dependency management, and build configuration.
+
+**Important:** CMake generation must run after Rice generation because it scans the output directory for `*-rb.cpp` files. If no Rice output exists, the generated CMake source lists will be empty.
+
+## Getting Started
+
+See [Getting Started](getting_started.md) for a step-by-step guide.
+
+## Output
+
+See [Output](output.md) for details on the generated files.
+
+## Filtering
+
+See [Filtering](filtering.md) for how to exclude files from the generated CMake build and how to conditionally include generated sources and directories with `guards`.

data/docs/cmake/filtering.md

@@ -0,0 +1,26 @@
+# Filtering
+
+## Skipping Files
+
+The CMake config supports a `skip` option to exclude specific `*-rb.cpp` files from the generated `CMakeLists.txt`. However, in most cases it's better to add skip patterns to your Rice config instead — that way the problematic files are never generated, and CMake won't find them to include. The CMake `skip` is useful as a quick fix when you have stale generated files on disk that you don't want to recompile.
+
+## Guarding Files And Directories
+
+Use `guards` when generated paths should remain on disk but only be compiled when a CMake condition is true.
+
+```yaml
+guards:
+  OpenCV_HAS_CUDA:
+    - opencv2/cuda*-rb.cpp
+  TARGET OpenCV::dnn:
+    - opencv2/dnn
+```
+
+Guard keys are emitted as raw `if(...)` conditions. Guard values may be exact paths or globs and may match generated directories and `*-rb.cpp` files.
+
+- Matching directories are emitted inside guarded `add_subdirectory(...)` blocks.
+- Matching `*-rb.cpp` files are emitted inside guarded `target_sources(...)` blocks.
+- A guard pattern that matches nothing emits a warning.
+- If the same path matches multiple guards, generation fails with an error.
+
+Use `skip` for permanent exclusion. Use `guards` for conditional inclusion.

data/docs/cmake/getting_started.md

@@ -0,0 +1,52 @@
+# Getting Started with CMake Bindings
+
+This guide walks you through generating CMake build files for Rice C++ bindings.
+
+## Prerequisites
+
+You must first generate Rice C++ bindings. See [Getting Started with Rice](../cpp/getting_started.md).
+
+## 1. Create a configuration file
+
+Create a file named `cmake-bindings.yaml`:
+
+```yaml
+project: my_extension
+output: ./ext/generated
+format: CMake
+
+guards:
+  TARGET MyLib::gpu:
+    - gpu
+    - gpu/**/*-rb.cpp
+
+include_dirs:
+  - "${CMAKE_CURRENT_SOURCE_DIR}/../include"
+```
+
+Key options:
+
+- `project` — name used in the CMake `project()` command and build target. When omitted, only subdirectory `CMakeLists.txt` files are generated — useful when you manage the root project files yourself.
+- `output` — directory containing the Rice `*-rb.cpp` files. `input` defaults to `output` for CMake.
+- `guards` — raw CMake conditions mapped to generated path patterns. Use this when a generated subdirectory or `*-rb.cpp` file should only be compiled when a module or feature is available.
+- `include_dirs` — include directories added via `target_include_directories`. These are CMake expressions written directly into the generated `CMakeLists.txt`.
+
+See [Configuration](../configuration.md) for all options.
+
+## 2. Generate CMake files
+
+Run this **after** generating Rice bindings:
+
+```bash
+ruby-bindgen cmake-bindings.yaml
+```
+
+## 3. Build
+
+```bash
+cd ./ext/generated
+cmake --preset linux-debug    # or macos-debug, msvc-debug, mingw-debug, etc.
+cmake --build build/linux-debug
+```
+
+See [Output](output.md) for details on the available presets and generated files.

data/docs/cmake/output.md

@@ -0,0 +1,110 @@
+# CMake Output
+
+The CMake format scans the output directory for `*-rb.cpp` files and generates:
+
+``` mermaid
+flowchart LR
+    subgraph Input
+        CF["cmake-bindings.yaml"]
+        S1["*-rb.cpp"]
+    end
+
+    CF & S1 --> RB["ruby-bindgen"]
+
+    subgraph "CMake Output"
+        C1["CMakeLists.txt"]
+        C2["CMakePresets.json"]
+    end
+
+    RB --> C1 & C2
+```
+
+## Project Files
+
+When the `project` option is set, `ruby-bindgen` generates the root `CMakeLists.txt` and `CMakePresets.json`. When `project` is omitted, these files are **not** generated — only subdirectory `CMakeLists.txt` files are produced. This is useful when you want to create and manage the root project files yourself and only regenerate subdirectory files on subsequent runs.
+
+## Top-level CMakeLists.txt
+
+The top-level `CMakeLists.txt` is a complete project file that configures the entire build:
+
+- C++17 standard requirement
+- Rice fetched from GitHub via `FetchContent`
+- Ruby detection via `find_package(Ruby)`
+- Library target (SHARED on MSVC, MODULE elsewhere)
+- Extension output configuration (correct suffix, visibility settings)
+- Subdirectory includes and `*-rb.cpp` source file listing
+
+For a well-documented example, see the [BitmapPlusPlus-ruby CMakeLists.txt](https://github.com/ruby-rice/BitmapPlusPlus-ruby/blob/main/ext/CMakeLists.txt). For details on how Rice uses CMake, see the Rice [CMake](https://ruby-rice.github.io/4.x/packaging/cmake/) documentation.
+
+## CMakePresets.json
+
+The top-level directory also gets a `CMakePresets.json` with build presets for all major platforms. For an example, see the [BitmapPlusPlus-ruby CMakePresets.json](https://github.com/ruby-rice/BitmapPlusPlus-ruby/blob/main/ext/CMakePresets.json). For details, see the Rice [CMakePresets.json](https://ruby-rice.github.io/4.x/packaging/cmake/#cmakepresetsjson) documentation.
+
+| Preset | Platform | Compiler |
+|--------|----------|----------|
+| `linux-debug` / `linux-release` | Linux | GCC/Clang |
+| `macos-debug` / `macos-release` | macOS | Clang |
+| `msvc-debug` / `msvc-release` | Windows | MSVC |
+| `mingw-debug` / `mingw-release` | Windows | MinGW GCC |
+| `clang-windows-debug` / `clang-windows-release` | Windows | clang-cl |
+
+All presets use [Ninja](https://ninja-build.org/) as the build generator and include appropriate compiler flags for each platform (visibility settings, debug info, optimization levels).
+
+## Subdirectories
+
+Each subdirectory containing `*-rb.cpp` files gets a minimal `CMakeLists.txt` that lists its source files and any nested subdirectories:
+
+```
+ext/generated/
+  CMakeLists.txt          # root project (requires project option)
+  CMakePresets.json       # build presets
+  core/
+    CMakeLists.txt        # add_subdirectory("hal") + target_sources(...)
+    matrix-rb.cpp
+    image-rb.cpp
+    hal/
+      CMakeLists.txt      # target_sources(...)
+      interface-rb.cpp
+```
+
+```cmake
+# Subdirectories
+add_subdirectory("hal")
+
+# Sources
+target_sources(${CMAKE_PROJECT_NAME} PUBLIC
+  "matrix-rb.cpp"
+  "image-rb.cpp"
+)
+```
+
+When `guards` are configured, the generator groups matching directories and files under raw CMake `if(...)` blocks in the generated `CMakeLists.txt`:
+
+```yaml
+guards:
+  TARGET OpenCV::dnn:
+    - opencv2/dnn
+  OpenCV_HAS_CUDA:
+    - opencv2/cuda*-rb.cpp
+```
+
+```cmake
+# Subdirectories
+add_subdirectory("core")
+
+# Sources
+target_sources(${CMAKE_PROJECT_NAME} PRIVATE
+  "core-rb.cpp"
+)
+
+if(TARGET OpenCV::dnn)
+  add_subdirectory("dnn")
+endif()
+
+if(OpenCV_HAS_CUDA)
+  target_sources(${CMAKE_PROJECT_NAME} PRIVATE
+    "cudaarithm-rb.cpp"
+    "cudaimgproc-rb.cpp"
+  )
+endif()
+```