Update C/ffi bindings to also support export macros.

Author: cfis

docs/c_bindings.md

@@ -144,6 +144,13 @@ This generates search names like `libproj.so.25`, `libproj.so.22`, etc. on Linux
 
 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`).
 
+## Filtering
+
+`ruby-bindgen` can filter which symbols are included in the generated bindings:
+
+- [`skip_symbols`](configuration.md#skip-symbols) - Skip specific functions, structs, enums, or typedefs by name or regex pattern
+- [`export_macros`](configuration.md#export-macros) - Only include functions marked with specific visibility macros
+
 ## Usage Tips
 
 Since C is procedural rather than object-oriented, you may want to wrap the generated FFI bindings in Ruby classes to provide a more idiomatic API:

docs/configuration.md

@@ -27,6 +27,7 @@ These options apply to all formats.
 | `match`         | `["**/*.{h,hpp}"]` | Glob patterns specifying which header files to process. |
 | `skip`          | `[]`               | Glob patterns specifying which header files to skip. |
 | `skip_symbols`  | `[]`               | List of symbol names to skip. Supports simple names, fully qualified names, or regex patterns. See [Skip Symbols](#skip-symbols). |
+| `export_macros` | `[]`               | List of macros that indicate a function is exported. When set, only functions whose source text contains one of these macros are included. See [Export Macros](#export-macros). |
 
 ## C (FFI) Options
 
@@ -41,7 +42,6 @@ These options apply to all formats.
 |-----------------|----------------|-------------|
 | `extension`     | none           | Name of the Ruby extension. Used for the `Init_` function name. Must be a valid C/C++ identifier. When provided, generates project wrapper files (`{extension}-rb.cpp`, `{extension}-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). |
-| `export_macros` | `[]`           | List of macros that indicate a symbol is exported. See [Export Macros](cpp/filtering.md#export-macros). |
 
 ## CMake Options
 
@@ -162,3 +162,23 @@ Regex patterns are enclosed in forward slashes (`/pattern/`) and are matched aga
 - Deprecated functions (marked with `__attribute__((deprecated))`)
 - Internal functions (names ending with `_`)
 - 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` |

docs/cpp/customizing.md

@@ -13,7 +13,7 @@ However, complex libraries may require some customization. Customizations fall i
 Some issues are best solved via the [configuration](../configuration.md) file rather than editing generated code:
 
 - Skip symbols: Functions that cause linker errors or aren’t meant for external use can be added to [`skip_symbols`](../configuration.md#skip-symbols)
-- Export macros: Use [`export_macros`](filtering.md#export-macros) to limit bindings to exported symbols, preventing linker errors from internal functions
+- Export macros: Use [`export_macros`](../configuration.md#export-macros) to limit bindings to exported symbols, preventing linker errors from internal functions
 
 ## Refinements
 

docs/cpp/filtering.md

@@ -4,23 +4,7 @@
 
 ## Export Macros
 
-The `export_macros` option filters functions based on the presence of specific macros in the source code. This is particularly useful for libraries like OpenCV 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` |
+See [`export_macros`](../configuration.md#export-macros) in the configuration documentation.
 
 ## Skip Symbols
 

lib/ruby-bindgen/visitors/ffi/ffi.rb

@@ -11,6 +11,7 @@ def initialize(outputter, config)
         @library_names = config[:library_names] || []
         @library_versions = config[:library_versions] || []
         @skip_symbols = config[:skip_symbols] || []
+        @export_macros = config[:export_macros] || []
         @indentation = 0
       end
 
@@ -27,6 +28,20 @@ def skip_symbol?(cursor)
         end
       end
 
+      # Check if cursor has one of the required export macros in its source text.
+      # When export_macros is empty, all symbols pass (no filtering).
+      def has_export_macro?(cursor)
+        return true if @export_macros.empty?
+
+        begin
+          source_text = cursor.extent.text
+          return true if source_text.nil?
+          @export_macros.any? { |macro| source_text.include?(macro) }
+        rescue
+          true
+        end
+      end
+
       def visit_start
       end
 
@@ -134,6 +149,7 @@ def visit_enum_constant_decl(cursor)
 
       def visit_function(cursor)
         return if skip_symbol?(cursor)
+        return unless has_export_macro?(cursor)
 
         result = Array.new
         parameter_types = cursor.find_by_kind(false, :cursor_parm_decl).map do |parameter|

test/bindings/c/filtering.rb

@@ -35,8 +35,8 @@ def self.search_names
 
   ffi_lib self.search_names
 
-  attach_function :included_function, :includedFunction, [:int], :int
-  attach_function :keep_this_function, :keepThisFunction, [:double, :double], :double
+  attach_function :exported_function, :exportedFunction, [:int], :int
+  attach_function :another_exported, :anotherExported, [:double, :double], :double
 
   class IncludedStruct < FFI::Struct
     layout :x, :int,

test/ffi_test.rb

@@ -26,6 +26,7 @@ def test_sqlite3
   def test_filtering
     run_ffi_test("filtering.h",
       library_names: ["filtering"], library_versions: [],
+      export_macros: ["MY_EXPORT"],
       skip_symbols: ["skippedFunction", "alsoSkipped", "/internal_helper.*/", "SkippedStruct", "SkippedEnum", "SkippedTypedef"])
   end
 

test/headers/c/filtering.h

@@ -1,25 +1,38 @@
-// Test cases for FFI skip_symbols filtering
+// Test cases for FFI filtering:
+// 1. Export macros - only include functions with specified macros
+// 2. Skip symbols - explicitly skip certain symbol names
 
-// --- Functions ---
+#if defined(_MSC_VER)
+  #define MY_EXPORT __declspec(dllexport)
+#else
+  #define MY_EXPORT __attribute__((visibility("default")))
+#endif
 
-// Normal function - should be INCLUDED
-int includedFunction(int x);
+// --- Export Macro Tests ---
+
+// Exported function - should be INCLUDED when export_macros contains MY_EXPORT
+MY_EXPORT int exportedFunction(int x);
+
+// Non-exported function - should be SKIPPED when export_macros is set
+void internalFunction(int x);
+
+// Another exported function - should be INCLUDED
+MY_EXPORT double anotherExported(double a, double b);
+
+// --- Skip Symbol Tests ---
 
 // Function to skip by name - should be SKIPPED
-void skippedFunction(int x);
+MY_EXPORT void skippedFunction(int x);
 
 // Another function to skip by name - should be SKIPPED
-int alsoSkipped(double y);
+MY_EXPORT int alsoSkipped(double y);
 
 // Function to skip by regex - should be SKIPPED
-void internal_helper_init(void);
-
-// Normal function - should be INCLUDED
-double keepThisFunction(double a, double b);
+MY_EXPORT void internal_helper_init(void);
 
 // --- Structs ---
 
-// Normal struct - should be INCLUDED
+// Normal struct - should be INCLUDED (export macros only filter functions)
 struct IncludedStruct
 {
     int x;