Add guard support to CMake generator

Author: cfis

docs/cmake/cmake_bindings.md

@@ -16,4 +16,4 @@ 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.
+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`.

docs/cmake/filtering.md

@@ -3,3 +3,24 @@
 ## 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.

docs/cmake/getting_started.md

@@ -15,6 +15,11 @@ project: my_extension
 output: ./ext/generated
 format: CMake
 
+guards:
+  TARGET MyLib::gpu:
+    - gpu
+    - gpu/**/*-rb.cpp
+
 include_dirs:
   - "${CMAKE_CURRENT_SOURCE_DIR}/../include"
 ```
@@ -23,6 +28,7 @@ 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.

docs/cmake/output.md

@@ -77,3 +77,34 @@ target_sources(${CMAKE_PROJECT_NAME} PUBLIC
   "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()
+```

docs/configuration.md

@@ -53,6 +53,7 @@ These options apply to all formats.
 |----------------|---------|-------------|
 | `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
 

lib/ruby-bindgen/generators/cmake/cmake.rb

@@ -1,6 +1,8 @@
 module RubyBindgen
   module Generators
     class CMake < Generator
+      GuardedEntry = Data.define(:condition, :directories, :files)
+
       def self.template_dir
         __dir__
       end
@@ -9,11 +11,22 @@ def include_dirs
         config[:include_dirs] || []
       end
 
+      def guards
+        @guards ||= begin
+          config_guards = config[:guards] || {}
+          config_guards.map do |condition, patterns|
+            Guard.new(condition: condition, patterns: patterns, base_path: @inputter.base_path)
+          end
+        end
+      end
+
       def generate
         base = Pathname.new(@inputter.base_path)
 
         # Collect files from inputter, grouped by relative directory
-        files_by_dir = Hash.new { |h, k| h[k] = [] }
+        files_by_dir = Hash.new do |hash, key|
+          hash[key] = []
+        end
 
         @inputter.each do |path, relative_path|
           dir = File.dirname(relative_path)
@@ -32,20 +45,29 @@ def generate
         end
 
         # Build parent -> immediate child directories mapping
-        child_dirs_of = Hash.new { |h, k| h[k] = [] }
+        child_dirs_of = Hash.new do |hash, key|
+          hash[key] = []
+        end
         all_dirs.each do |dir|
           parent = File.dirname(dir)
           parent = "." if parent == dir
           child_dirs_of[parent] << base.join(dir)
         end
         child_dirs_of.each_value(&:sort!)
 
+        file_guards, directory_guards = build_guard_maps(files_by_dir, all_dirs.to_a)
+
         if @project
           # Root CMakeLists.txt
           content = render_template("project",
                                     :project => self.project,
-                                    :directories => child_dirs_of["."],
-                                    :files => files_by_dir["."].sort,
+                                    :directories => unguarded_paths(child_dirs_of["."], directory_guards, base),
+                                    :files => unguarded_paths(files_by_dir["."].sort, file_guards, base),
+                                    :guarded_entries => guarded_entries(child_dirs_of["."],
+                                                                        directory_guards,
+                                                                        files_by_dir["."].sort,
+                                                                        file_guards,
+                                                                        base),
                                     :include_dirs => self.include_dirs)
           self.outputter.write("CMakeLists.txt", content)
 
@@ -58,11 +80,92 @@ def generate
         all_dirs.sort.each do |dir|
           content = render_template("directory",
                                     :project => self.project,
-                                    :directories => child_dirs_of[dir],
-                                    :files => (files_by_dir[dir] || []).sort)
+                                    :directories => unguarded_paths(child_dirs_of[dir], directory_guards, base),
+                                    :files => unguarded_paths((files_by_dir[dir] || []).sort, file_guards, base),
+                                    :guarded_entries => guarded_entries(child_dirs_of[dir],
+                                                                        directory_guards,
+                                                                        (files_by_dir[dir] || []).sort,
+                                                                        file_guards,
+                                                                        base))
           self.outputter.write(File.join(dir, "CMakeLists.txt"), content)
         end
       end
+
+      private
+
+      def build_guard_maps(files_by_dir, all_dirs)
+        file_paths = files_by_dir.values.flatten.map do |path|
+          expand_path(path)
+        end.sort
+        directory_paths = all_dirs.map do |dir|
+          expand_path(dir, @inputter.base_path)
+        end.sort
+        file_guards = {}
+        directory_guards = {}
+
+        guards.each do |guard|
+          match = guard.match(file_paths: file_paths, directory_paths: directory_paths)
+
+          match.files.each do |path|
+            assign_guard!(file_guards, path, match.condition)
+          end
+
+          match.directories.each do |path|
+            assign_guard!(directory_guards, path, match.condition)
+          end
+        end
+
+        [file_guards, directory_guards]
+      end
+
+      def assign_guard!(assignments, path, condition)
+        previous = assignments[path]
+        if previous && previous != condition
+          raise ArgumentError, "#{path} matched multiple guard conditions: #{previous.inspect}, #{condition.inspect}"
+        end
+
+        assignments[path] = condition
+      end
+
+      def guarded_entries(directories, directory_guards, files, file_guards, base)
+        grouped = Hash.new do |hash, key|
+          hash[key] = GuardedEntry.new(condition: key, directories: [], files: [])
+        end
+
+        directories.each do |directory|
+          condition = directory_guards[expand_path(directory, base)]
+          next unless condition
+
+          grouped[condition].directories << directory
+        end
+
+        files.each do |file|
+          condition = file_guards[expand_path(file, base)]
+          next unless condition
+
+          grouped[condition].files << file
+        end
+
+        guards.map(&:condition).filter_map do |condition|
+          entry = grouped[condition]
+          next if entry.nil? || (entry.directories.empty? && entry.files.empty?)
+
+          entry
+        end
+      end
+
+      def expand_path(path, base = @inputter.base_path)
+        File.expand_path(path.to_s, base.to_s)
+      end
+
+      def unguarded_paths(paths, guard_map, base)
+        paths.reject do |path|
+          guard_map.key?(expand_path(path, base))
+        end
+      end
+
     end
   end
 end
+
+require_relative 'guard'

lib/ruby-bindgen/generators/cmake/directory.erb

@@ -8,8 +8,22 @@ add_subdirectory ("<%= directory.relative_path_from(directory.parent) %>")
 # Sources
 <% if !files.empty? -%>
 target_sources(${CMAKE_PROJECT_NAME} PRIVATE
-  <% files.each do |file| -%>
+<% files.each do |file| -%>
   "<%= file.relative_path_from(file.parent) %>"
-  <% end -%>
+<% end -%>
 )
 <% end -%>
+<% guarded_entries.each do |entry| -%>
+if(<%= entry.condition %>)
+<% entry.directories.each do |directory| -%>
+  add_subdirectory ("<%= directory.relative_path_from(directory.parent) %>")
+<% end -%>
+<% if !entry.files.empty? -%>
+  target_sources(${CMAKE_PROJECT_NAME} PRIVATE
+<% entry.files.each do |file| -%>
+    "<%= file.relative_path_from(file.parent) %>"
+<% end -%>
+  )
+<% end -%>
+endif()
+<% end -%>

lib/ruby-bindgen/generators/cmake/guard.rb

@@ -0,0 +1,55 @@
+module RubyBindgen
+  module Generators
+    class CMake
+      class Guard
+        GuardMatch = Data.define(:condition, :directories, :files)
+
+        attr_reader :condition, :patterns
+
+        def initialize(condition:, patterns:, base_path:)
+          @condition = condition.to_s
+          @patterns = Array(patterns).map do |pattern|
+            expand_path(pattern.to_s, base_path)
+          end
+        end
+
+        def match(file_paths:, directory_paths:)
+          matched_files = []
+          matched_directories = []
+
+          patterns.each do |pattern|
+            files = file_paths.select do |path|
+              path_match?(pattern, path)
+            end
+            directories = directory_paths.select do |path|
+              path_match?(pattern, path)
+            end
+
+            warn_unmatched(pattern) if files.empty? && directories.empty?
+
+            matched_files.concat(files)
+            matched_directories.concat(directories)
+          end
+
+          GuardMatch.new(condition: condition,
+                         directories: matched_directories.uniq.sort,
+                         files: matched_files.uniq.sort)
+        end
+
+        private
+
+        def path_match?(pattern, path)
+          File.fnmatch?(pattern, path, File::FNM_PATHNAME)
+        end
+
+        def expand_path(path, base)
+          File.expand_path(path.to_s, base.to_s)
+        end
+
+        def warn_unmatched(pattern)
+          warn "CMake guard #{condition.inspect} did not match any generated paths for pattern #{pattern.inspect}"
+        end
+      end
+    end
+  end
+end

lib/ruby-bindgen/generators/cmake/project.erb

@@ -73,3 +73,17 @@ target_sources(${CMAKE_PROJECT_NAME} PRIVATE
 <% end -%>
 )
 <% end -%>
+<% guarded_entries.each do |entry| -%>
+if(<%= entry.condition %>)
+<% entry.directories.each do |directory| -%>
+  add_subdirectory("<%= directory.relative_path_from(directory.parent) %>")
+<% end -%>
+<% if !entry.files.empty? -%>
+  target_sources(${CMAKE_PROJECT_NAME} PRIVATE
+<% entry.files.each do |file| -%>
+    "<%= file.relative_path_from(file.parent) %>"
+<% end -%>
+  )
+<% end -%>
+endif()
+<% end -%>

test/abstract_test.rb

@@ -1,4 +1,5 @@
 require 'bundler/setup'
+require 'fileutils'
 
 if ENV['COVERAGE']
   require 'simplecov'
@@ -57,6 +58,7 @@ def validate_result(outputter)
     outputter.output_paths.each do |path, content|
       generated_paths << path
       if ENV["UPDATE_EXPECTED"]
+        FileUtils.mkdir_p(File.dirname(path))
         File.open(path, 'wb') do |file|
           file << content
         end