More doc updates and use clang-cl only with mswin.

cfis · cfis · commit f41967064c9a · 2026-03-14T00:02:46.000-07:00
diff --git a/docs/cmake/cmake_bindings.md b/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.
diff --git a/docs/cmake/filtering.md b/docs/cmake/filtering.md
@@ -0,0 +1,5 @@
+# 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.
diff --git a/docs/cmake/getting_started.md b/docs/cmake/getting_started.md
@@ -0,0 +1,46 @@
+# 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
+
+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.
+- `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.
diff --git a/docs/cmake/output.md b/docs/cmake/output.md
@@ -1,50 +1,4 @@
-# CMake Bindings
-
-The `CMake` format generates `CMakeLists.txt` and `CMakePresets.json` files for building Rice C++ bindings.
-
-**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.
-
-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.
-
-## Configuration
-
-```yaml
-format: CMake
-project: my_extension
-output: ./ext/generated
-# input defaults to output for CMake and scans ./ext/generated for *-rb.cpp
-
-include_dirs:
-  - "${CMAKE_CURRENT_SOURCE_DIR}/../headers"
-```
-
-See [configuration](configuration.md) for details on all options.
-
-## Usage
-
-Generate bindings in two passes:
-
-```bash
-# 1. Generate Rice C++ source files
-ruby-bindgen rice-bindings.yaml
-
-# 2. Generate CMake build files
-ruby-bindgen cmake-bindings.yaml
-```
-
-Then build:
-
-```bash
-cd /path/to/output
-cmake --preset linux-debug    # or msvc-debug, macos-debug, etc.
-cmake --build build/linux-debug
-```
-
-## 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/FFI 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.
-
-## Output
+# CMake Output
 
 The CMake format scans the output directory for `*-rb.cpp` files and generates:
 
@@ -65,11 +19,11 @@ flowchart LR
     RB --> C1 & C2
 ```
 
-### Project Files (requires `project`)
+## 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
+## Top-level CMakeLists.txt
 
 The top-level `CMakeLists.txt` is a complete project file that configures the entire build:
 
@@ -82,6 +36,8 @@ The top-level `CMakeLists.txt` is a complete project file that configures the en
 
 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 |
@@ -94,10 +50,23 @@ The top-level directory also gets a `CMakePresets.json` with build presets for a
 
 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
+## 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")
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -6,7 +6,7 @@
 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_bindings.md).
+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
 
@@ -45,7 +45,7 @@ These options apply to all formats.
 | 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/cpp_bindings.md#include-header). |
+| `include`       | auto-generated | Path to a custom Rice include header. See [Include Header](cpp/output.md#include-header). |
 
 ## CMake Options
 
@@ -58,8 +58,8 @@ These options apply to all formats.
 
 `ruby-bindgen` uses top-level toolchain keys to configure compiler settings for different platforms:
 
-- **`clang-cl:`** - Used when `RUBY_PLATFORM` contains `mswin` or `mingw`
-- **`clang:`** - Used on Linux and macOS
+- **`clang-cl:`** - Used when `RUBY_PLATFORM` contains `mswin` (MSVC toolchain)
+- **`clang:`** - Used on Linux, macOS, and MinGW
 
 | Option     | Default     | Description |
 |------------|-------------|-------------|
@@ -73,9 +73,9 @@ You only need to include the toolchain sections for platforms you target.
 ```mermaid
 flowchart TD
   A["config.yaml location"] --> B["Resolve relative input/output paths"]
-  B --> C{"RUBY_PLATFORM contains mswin or mingw?"}
+  B --> C{"RUBY_PLATFORM contains mswin?"}
   C -->|Yes| D["Use clang-cl section"]
-  C -->|No| E["Use clang 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"]
@@ -256,7 +256,6 @@ Regex patterns are enclosed in forward slashes (`/pattern/`) and are matched aga
 `ruby-bindgen` automatically skips:
 
 - Deprecated functions (marked with `__attribute__((deprecated))`)
-- Internal functions (names ending with `_`)
 - Methods returning pointers to incomplete types (pimpl pattern)
 
 ## Export Macros
diff --git a/docs/cpp/cpp_bindings.md b/docs/cpp/cpp_bindings.md
@@ -18,7 +18,7 @@ See [Rice Output](output.md) for details on the generated files, including heade
 
 ## 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_bindings.md) to compile and link the generated bindings.
+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
 
diff --git a/docs/cpp/getting_started.md b/docs/cpp/getting_started.md
@@ -63,7 +63,7 @@ Then run it **after** the Rice generation:
 ruby-bindgen cmake-bindings.yaml
 ```
 
-See [CMake Bindings](../cmake_bindings.md) for details.
+See [CMake Bindings](../cmake/cmake_bindings.md) for details.
 
 ## 4. Build the extension
 
diff --git a/docs/index.md b/docs/index.md
@@ -62,7 +62,7 @@ flowchart TD
 
   click B "c/c_bindings.md" "C Bindings"
   click C "cpp/cpp_bindings.md" "C++ Bindings"
-  click E "cmake_bindings.md" "CMake Bindings"
+  click E "cmake/cmake_bindings.md" "CMake Bindings"
   click D "https://ruby-rice.github.io/4.x/packaging/extconf/" "Rice extconf.rb packaging"
 ```
 
@@ -98,7 +98,7 @@ For much more details, jump to the documentation page for each format:
 |-----------|-------------------------------------|
 | **FFI**   | [C Bindings](c/c_bindings.md)       |
 | **Rice**  | [C++ Bindings](cpp/cpp_bindings.md)     |
-| **CMake** | [CMake Bindings](cmake_bindings.md) |
+| **CMake** | [CMake Bindings](cmake/cmake_bindings.md) |
 
 Finally generate bindings by running the command:
 
diff --git a/docs/limitations.md b/docs/limitations.md
diff --git a/docs/prior_art.md b/docs/prior_art.md
@@ -14,7 +14,7 @@ This page lists related projects and adjacent tools that influenced, overlap wit
 
 - 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 liblang findings versus using [ffi-clang](https://github.com/ioquatix/ffi-clang).
+- 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
 
diff --git a/docs/updating_bindings.md b/docs/updating_bindings.md
@@ -4,7 +4,7 @@ After generating bindings with `ruby-bindgen`, you'll need to regenerate them pe
 
 ## Simple Case
 
-If you have no [customizations](cpp/customizing.md) to preserve, then you can simply regenerate the bindings:
+If you have no [manual edits or refinements](cpp/customizing.md) to preserve, you can simply regenerate the bindings. Configuration changes such as adding new skip patterns or version guards are fine — they are read from the YAML file each time.
 
 ```bash
 ruby-bindgen bindings.yaml
diff --git a/lib/ruby-bindgen/config.rb b/lib/ruby-bindgen/config.rb
@@ -22,7 +22,7 @@ def []=(key, value)
     private
 
     def resolve_toolchain
-      toolchain = RUBY_PLATFORM =~ /mswin|mingw/ ? :'clang-cl' : :clang
+      toolchain = RUBY_PLATFORM =~ /mswin/ ? :'clang-cl' : :clang
 
       toolchain_config = @data[toolchain]
       if toolchain_config.is_a?(Hash)
diff --git a/lib/ruby-bindgen/generators/ffi/constant.erb b/lib/ruby-bindgen/generators/ffi/constant.erb
@@ -0,0 +1 @@
+<%= name %> = <%= value %>
diff --git a/zensical.toml b/zensical.toml
@@ -33,10 +33,14 @@ nav = [
     { "Buffers" = "cpp/buffers.md" },
     { "Customizing" = "cpp/customizing.md" },
   ]},
-  { "CMake Bindings" = "cmake_bindings.md" },
+  { "CMake Bindings" = [
+    { "Overview" = "cmake/cmake_bindings.md" },
+    { "Getting Started" = "cmake/getting_started.md" },
+    { "Output" = "cmake/output.md" },
+    { "Filtering" = "cmake/filtering.md" },
+  ]},
   { "Configuration" = "configuration.md" },
   { "Updating Bindings" = "updating_bindings.md" },
-  { "Limitations" = "limitations.md" },
   { "Prior Art" = "prior_art.md" },
   { "Architecture" = "architecture.md" },
 ]
