ffi-clang 0.14.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e7e863a657523fadf6b3bbe7bf5e53fc047fb028418464d9969011041ced1f7
-  data.tar.gz: 9fa425cacdfeda2905d5450081d308e7b37979f96beb181c5dcc64e51976c33e
+  metadata.gz: f49d102b63151e047ed3158af59e2ab793ea3a422f13a8a83515305f7c8f5025
+  data.tar.gz: df66a932286bb412577e176757d79ceea6b82dc2859407cc5abcb720595f57ff
 SHA512:
-  metadata.gz: 7200e81a683eed2b5415d544025af4c800767b96ac145f28b602c2d84c933650ddde92a8310b897592a7b434f08ccaf647a62965ce933493af7b5332fe6aac95
-  data.tar.gz: 494b4856f2dd7fbbabe4638bd3efda40910163d59cc78203f68553994791356f920ebf72962e8b1ce3270c6df3ed46c5e90cfaec13dbdbac87bc1e2d4b3f0323
+  metadata.gz: 00a0370a903ff0d26d60f3b17dee7a3d94cfaabbf836db4cfb8eba7a56ae966f86a95ab426ef7de1a475b7cb00dd77e2e65ca3553be2d16d05e7e2c13ee4cafa
+  data.tar.gz: 3efc05ec2a7da83578cff2bdb963f20dc5ff02168f471cf417672aac0715abf570fbc9744fb696a065a4dbd5f63a453fef7af09d6467a1342d392cddb58d2074

data/lib/ffi/clang/args/args.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Charlie Savage.
+
+require "open3"
+
+module FFI
+	module Clang
+		# Platform-specific clang configuration: finding libclang, locating the
+		# resource directory, and injecting extra command-line arguments into
+		# parse_translation_unit.
+		#
+		# All discovery is lazy — nothing runs until a method is called.
+		class Args
+			# Set the loaded libclang path after ffi_lib succeeds,
+			# so resource dir probing can use it.
+			# @parameter path [String | Nil] Path to the loaded libclang library.
+			attr_writer :libclang_loaded_path
+			
+			# Factory: returns the platform-appropriate subclass instance.
+			# @returns [Args] A platform-specific instance.
+			def self.create
+				case FFI::Clang.platform
+				when :darwin
+					DarwinArgs.new
+				when :mingw
+					MingwArgs.new
+				when :mswin
+					MswinArgs.new
+				else
+					LinuxArgs.new
+				end
+			end
+			
+			# Ordered list of library paths for ffi_lib.
+			# @returns [Array(String)] Paths to try when loading libclang.
+			def libclang_paths
+				@libclang_paths ||= if ENV["LIBCLANG"]
+					[ENV["LIBCLANG"]]
+				else
+					find_libclang_paths
+				end
+			end
+			
+			# Extra args to inject into parse_translation_unit.
+			# Includes -resource-dir (unless already present) plus any
+			# platform-specific flags.
+			# @parameter command_line_args [Array(String)] The existing command line arguments.
+			# @returns [Array(String)] Additional args to append.
+			def command_line_args(command_line_args = [])
+				args = []
+				
+				if !command_line_args.include?("-resource-dir") && resource_dir
+					args.push("-resource-dir", resource_dir)
+				end
+				
+				args.concat(extra_args(command_line_args))
+				args
+			end
+			
+			# The resolved resource directory path.
+			# @returns [String | Nil] The resource directory path, or nil if not found.
+			def resource_dir
+				if defined?(@resource_dir)
+					@resource_dir
+				else
+					@resource_dir = find_resource_dir
+				end
+			end
+			
+			# Called after ffi_lib successfully loads libclang.
+			# Subclasses may override to perform post-load setup.
+			#
+			# @parameter library [FFI::DynamicLibrary] The loaded libclang library.
+			def post_load(library)
+			end
+			
+			private
+			
+			def versions
+				22.downto(17)
+			end
+			
+			# Platform-specific extra args beyond -resource-dir.
+			# Subclasses override as needed.
+			# @parameter command_line_args [Array(String)] The existing command line arguments.
+			# @returns [Array(String)] Additional platform-specific args.
+			def extra_args(command_line_args)
+				[]
+			end
+			
+			# --- Shared helpers ---
+			
+			# Find the llvm-config binary. Checks LLVM_CONFIG env, then PATH
+			# (unless LLVM_VERSION is set to pin a specific version).
+			# @returns [String | Nil] Path to llvm-config, or nil.
+			def llvm_config
+				if defined?(@llvm_config)
+					return @llvm_config
+				end
+				
+				@llvm_config = ENV["LLVM_CONFIG"]
+				
+				unless @llvm_config || ENV["LLVM_VERSION"]
+					@llvm_config = "llvm-config"
+				end
+				
+				@llvm_config
+			end
+			
+			# Query llvm-config for its library directory.
+			# @returns [String | Nil] The library directory, or nil.
+			def llvm_library_dir
+				return nil unless llvm_config
+				
+				@llvm_library_dir ||= run_command(llvm_config, "--libdir")
+			end
+			
+			# Query llvm-config for its binary directory.
+			# @returns [String | Nil] The binary directory, or nil.
+			def llvm_bin_dir
+				return nil unless llvm_config
+				
+				@llvm_bin_dir ||= run_command(llvm_config, "--bindir")
+			end
+			
+			# Ask a clang binary for its resource directory.
+			# @parameter clang [String] Path to or name of the clang binary.
+			# @returns [String | Nil] The resource directory path, or nil.
+			def resource_dir_from_clang(clang)
+				dir = run_command(clang, "-print-resource-dir")
+				valid_resource_dir?(dir) ? dir : nil
+			end
+			
+			def run_command(*command)
+				stdout, _stderr, status = Open3.capture3(*command)
+				return nil unless status.success?
+				
+				output = stdout.strip
+				output.empty? ? nil : output
+			rescue Errno::ENOENT
+				nil
+			end
+			
+			# Probe for the resource directory relative to the libclang shared library.
+			# @parameter libclang_path [String] Path to the libclang shared library.
+			# @returns [String | Nil] The resource directory path, or nil.
+			def probe_from_libclang(libclang_path)
+				base = ::File.expand_path(::File.dirname(libclang_path))
+				
+				candidates = []
+				candidates.concat Dir.glob(::File.join(base, "..", "lib", "clang", "*"))
+				candidates.concat Dir.glob(::File.join(base, "..", "..", "lib", "clang", "*"))
+				candidates.concat Dir.glob(::File.join(base, "clang", "*"))
+				
+				candidates = candidates.map{|p| ::File.expand_path(p)}.uniq
+				
+				candidates
+					.select{|dir| valid_resource_dir?(dir)}
+					.sort
+					.last
+			end
+			
+			# Check whether a directory looks like a valid clang resource directory.
+			# @parameter dir [String | Nil] The directory to check.
+			# @returns [Boolean] True if the directory contains expected compiler headers.
+			def valid_resource_dir?(dir)
+				return false unless dir && ::File.directory?(dir)
+				
+				inc = ::File.join(dir, "include")
+				return false unless ::File.directory?(inc)
+				
+				::File.exist?(::File.join(inc, "stddef.h")) ||
+					::File.exist?(::File.join(inc, "__stddef_size_t.h")) ||
+					::File.exist?(::File.join(inc, "stdint.h"))
+			end
+			
+			# Common resource dir search: env override, clang from llvm-config,
+			# clang on PATH, probe from loaded libclang.
+			# @returns [String | Nil] The resource directory path, or nil.
+			def find_resource_dir
+				# 1. Explicit override via environment variable.
+				env = ENV["LIBCLANG_RESOURCE_DIR"]
+				return env if valid_resource_dir?(env)
+				
+				# 2. Clang binary from llvm-config.
+				if (bin_dir = llvm_bin_dir)
+					clang_path = ::File.join(bin_dir, "clang")
+					if (dir = resource_dir_from_clang(clang_path))
+						return dir
+					end
+				end
+				
+				# 3. clang on PATH.
+				if (dir = resource_dir_from_clang("clang"))
+					return dir
+				end
+				
+				# 4. Probe relative to the loaded libclang shared library.
+				if @libclang_loaded_path && (dir = probe_from_libclang(@libclang_loaded_path))
+					return dir
+				end
+				
+				nil
+			end
+		end
+	end
+end

data/lib/ffi/clang/args/darwin.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Charlie Savage.
+
+module FFI
+	module Clang
+		# macOS-specific clang configuration using Xcode toolchain paths.
+		class DarwinArgs < Args
+			private
+			
+			def find_libclang_paths
+				if llvm_library_dir
+					return [::File.join(llvm_library_dir, "libclang.dylib")]
+				end
+				
+				# Try xcode-select paths.
+				begin
+					xcode_dir = `xcode-select -p`.chomp
+					%W[
+						#{xcode_dir}/Toolchains/XcodeDefault.xctoolchain/usr/lib/libclang.dylib
+						#{xcode_dir}/usr/lib/libclang.dylib
+					].each do |f|
+						return [f] if ::File.exist?(f)
+					end
+				rescue Errno::ENOENT
+					# xcode-select not available
+				end
+				
+				["clang"]
+			end
+			
+			def isysroot
+				if defined?(@isysroot)
+					return @isysroot
+				end
+				
+				@isysroot = begin
+					stdout, _stderr, status = Open3.capture3("xcrun", "--show-sdk-path")
+					status.success? ? stdout.strip : nil
+				rescue Errno::ENOENT
+					nil
+				end
+			end
+			
+			def extra_args(command_line_args)
+				args = []
+				
+				if !command_line_args.include?("-isysroot") && isysroot
+					args.push("-isysroot", isysroot)
+				end
+				
+				args
+			end
+		end
+	end
+end

data/lib/ffi/clang/args/linux.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Charlie Savage.
+
+module FFI
+	module Clang
+		# Linux-specific clang configuration.
+		class LinuxArgs < Args
+			private
+			
+			def find_libclang_paths
+				prefix = llvm_library_dir
+				
+				paths = versions.flat_map do |version|
+					5.downto(0).map do |minor|
+						libclang_path(prefix, "libclang.so.#{version}.#{minor}")
+					end
+				end
+				
+				paths.concat(versions.map do |version|
+					libclang_path(prefix, "libclang.so.#{version}")
+				end)
+				
+				paths << libclang_path(prefix, "libclang.so")
+			end
+			
+			def libclang_path(prefix, name)
+				prefix ? ::File.join(prefix, name) : name
+			end
+		end
+	end
+end

data/lib/ffi/clang/args/mingw.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Charlie Savage.
+
+module FFI
+	module Clang
+		# MinGW/MSYS2-specific clang configuration.
+		class MingwArgs < Args
+			private
+			
+			def find_libclang_paths
+				if llvm_bin_dir
+					return [::File.join(llvm_bin_dir, "libclang.dll")]
+				end
+				
+				["libclang.dll"]
+			end
+		end
+	end
+end

data/lib/ffi/clang/args/mswin.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2026, by Charlie Savage.
+
+module FFI
+	module Clang
+		# MSVC-specific clang configuration. Discovers libclang and system
+		# include paths from the Visual Studio installation:
+		#
+		# 1. Find the VS installation path via vswhere.exe
+		# 2. Call vcvarsall.bat to set up the MSVC developer environment
+		# 3. Run clang-cl -v -E -x c++ NUL in that environment
+		# 4. Parse the "#include <...> search starts here:" block from the output
+		# 5. Inject each discovered path as -I into parse_translation_unit
+		class MswinArgs < Args
+			VSWHERE = "C:/Program Files (x86)/Microsoft Visual Studio/Installer/vswhere.exe"
+			
+			# Pin libclang in memory so Windows will not unload it at exit.
+			#
+			# LLVM's rpmalloc allocator registers Fiber Local Storage (FLS)
+			# callbacks via FlsAlloc but does not call FlsFree on
+			# DLL_PROCESS_DETACH (LLVM bug #154361, fixed in LLVM 22.1.0 by
+			# https://github.com/llvm/llvm-project/pull/171465).
+			# Pinning with GET_MODULE_HANDLE_EX_FLAG_PIN prevents the unload
+			# so the FLS callbacks remain valid through process shutdown.
+			#
+			# @parameter library [FFI::DynamicLibrary] The loaded libclang library.
+			def post_load(library)
+				symbol = library.find_symbol("clang_getClangVersion")
+				return unless symbol
+				
+				kernel32 = FFI::DynamicLibrary.open("kernel32", 0)
+				get_module_handle_ex_w = kernel32.find_function("GetModuleHandleExW")
+				return unless get_module_handle_ex_w
+				
+				get_module_handle_ex_flag_from_address = 0x4
+				get_module_handle_ex_flag_pin = 0x1
+				flags = get_module_handle_ex_flag_from_address | get_module_handle_ex_flag_pin
+				handle_out = FFI::MemoryPointer.new(:pointer)
+				pin = FFI::Function.new(:bool, [:uint, :pointer, :pointer], get_module_handle_ex_w)
+				pin.call(flags, symbol, handle_out)
+			end
+			
+			private
+			
+			
+			def find_libclang_paths
+				if llvm_bin_dir
+					return [::File.join(llvm_bin_dir, "libclang.dll")]
+				end
+				
+				if (vs_llvm = vs_llvm_dir)
+					return [::File.join(vs_llvm, "bin", "libclang.dll")]
+				end
+				
+				["libclang.dll"]
+			end
+			
+			# Mswin skips "clang on PATH" — uses clang-cl probe instead.
+			def find_resource_dir
+				# 1. Explicit override via environment variable.
+				env = ENV["LIBCLANG_RESOURCE_DIR"]
+				return env if valid_resource_dir?(env)
+				
+				# 2. clang-cl next to the loaded libclang.
+				if @libclang_loaded_path
+					clang_cl = ::File.join(::File.dirname(@libclang_loaded_path), "clang-cl.exe")
+					if ::File.exist?(clang_cl) && (dir = resource_dir_from_clang(clang_cl))
+						return dir
+					end
+				end
+				
+				# 3. Probe relative to the loaded libclang shared library.
+				if @libclang_loaded_path && (dir = probe_from_libclang(@libclang_loaded_path))
+					return dir
+				end
+				
+				nil
+			end
+			
+			def extra_args(command_line_args)
+				args = []
+				
+				system_includes.each do |path|
+					unless command_line_args.include?(path)
+						args.push("-I", path)
+					end
+				end
+				
+				args
+			end
+			
+			# Parse system include paths from clang-cl running in a VS developer environment.
+			# @returns [Array(String)] System include directories.
+			def system_includes
+				@system_includes ||= find_system_includes
+			end
+			
+			def find_system_includes
+				vs_path = vs_installation_path
+				return [] unless vs_path
+				
+				vcvarsall = ::File.join(vs_path, "VC", "Auxiliary", "Build", "vcvarsall.bat")
+				return [] unless ::File.exist?(vcvarsall)
+				
+				clang_cl = find_clang_cl
+				return [] unless clang_cl
+				
+				arch = RbConfig::CONFIG["target_cpu"] == "x64" ? "x64" : "arm64"
+				cmd = "cmd /c \"call \"#{vcvarsall}\" #{arch} >nul 2>&1 && \"#{clang_cl}\" -v -E -x c++ NUL 2>&1\""
+				
+				stdout, _status = Open3.capture2(cmd)
+				parse_include_paths(stdout)
+			rescue Errno::ENOENT
+				[]
+			end
+			
+			# Find clang-cl.exe — next to loaded libclang, or in VS LLVM dir.
+			# @returns [String | Nil] Path to clang-cl.exe, or nil.
+			def find_clang_cl
+				if @libclang_loaded_path
+					path = ::File.join(::File.dirname(@libclang_loaded_path), "clang-cl.exe")
+					return path if ::File.exist?(path)
+				end
+				
+				if (vs_llvm = vs_llvm_dir)
+					path = ::File.join(vs_llvm, "bin", "clang-cl.exe")
+					return path if ::File.exist?(path)
+				end
+				
+				nil
+			end
+			
+			# Parse the #include <...> search paths from clang -v output.
+			# @parameter output [String] The combined stdout/stderr from clang-cl -v.
+			# @returns [Array(String)] The include directories.
+			def parse_include_paths(output)
+				paths = []
+				in_search_list = false
+				
+				output.each_line do |line|
+					line = line.strip
+					
+					if line == "#include <...> search starts here:"
+						in_search_list = true
+					elsif line == "End of search list."
+						break
+					elsif in_search_list && !line.empty?
+						paths << line
+					end
+				end
+				
+				paths
+			end
+			
+			# Find the VS installation path using vswhere.
+			# @returns [String | Nil] Path like "C:/Program Files/Microsoft Visual Studio/18/Insiders", or nil.
+			def vs_installation_path
+				if defined?(@vs_installation_path)
+					return @vs_installation_path
+				end
+				
+				@vs_installation_path = find_vs_installation_path
+			end
+			
+			def find_vs_installation_path
+				return nil unless ::File.exist?(VSWHERE)
+				
+				stdout, _stderr, status = Open3.capture3(
+					VSWHERE, "-latest", "-products", "*", "-prerelease",
+					"-requires", "Microsoft.VisualStudio.Component.VC.Llvm.Clang",
+					"-property", "installationPath"
+				)
+				return nil unless status.success?
+				
+				path = stdout.strip
+				path.empty? ? nil : path
+			rescue Errno::ENOENT
+				nil
+			end
+			
+			# Find the VS-bundled LLVM directory.
+			# @returns [String | Nil] Path like ".../VC/Tools/Llvm/x64", or nil.
+			def vs_llvm_dir
+				vs_path = vs_installation_path
+				return nil unless vs_path
+				
+				arch = RbConfig::CONFIG["target_cpu"] == "x64" ? "x64" : "ARM64"
+				llvm_dir = ::File.join(vs_path, "VC", "Tools", "Llvm", arch)
+				::File.directory?(llvm_dir) ? llvm_dir : nil
+			end
+		end
+	end
+end

data/lib/ffi/clang/code_completion.rb

@@ -3,7 +3,7 @@
 # Released under the MIT License.
 # Copyright, 2014, by Masahiro Sano.
 # Copyright, 2014-2025, by Samuel Williams.
-# Copyright, 2023-2024, by Charlie Savage.
+# Copyright, 2023-2026, by Charlie Savage.
 
 require_relative "lib/code_completion"
 
@@ -21,12 +21,19 @@ module FFI
 			class Results < FFI::AutoPointer
 				include Enumerable
 				
-				# @attribute [Integer] The number of completion results.
+				# @attribute [r] size
+				# 	@returns [Integer] The number of completion results.
 				attr_reader :size
 				
-				# @attribute [Array(Result)] The array of completion results.
+				# @attribute [r] results
+				# 	@returns [Array(Result)] The array of completion results.
 				attr_reader :results
 				
+				# @attribute [r] code_complete_results
+				# 	@returns [Lib::CXCodeCompleteResults] The underlying results structure.
+				# @private
+				attr_reader :code_complete_results
+				
 				# Initialize code completion results.
 				# @parameter code_complete_results [Lib::CXCodeCompleteResults] The completion results structure.
 				# @parameter translation_unit [TranslationUnit] The parent translation unit.
@@ -47,10 +54,11 @@ module FFI
 				# Iterate over each completion result.
 				# @yields {|result| ...} Each completion result.
 				# 	@parameter result [Result] The completion result.
+				# @returns [Enumerator] If no block is given.
 				def each(&block)
-					@results.each do |token|
-						block.call(token)
-					end
+					return to_enum(__method__) unless block_given?
+					
+					@results.each(&block)
 				end
 				
 				# Get the number of diagnostics.
@@ -69,9 +77,9 @@ module FFI
 				# Get all diagnostics.
 				# @returns [Array(Diagnostic)] Array of diagnostics.
 				def diagnostics
-					num_diagnostics.times.map {|i|
+					num_diagnostics.times.map do |i|
 						Diagnostic.new(@translation_unit, Lib.get_code_complete_get_diagnostic(@code_complete_results, i))
-					}
+					end
 				end
 				
 				# Get the completion contexts.
@@ -126,9 +134,11 @@ module FFI
 					@size = @code_complete_results[:num]
 					cur_ptr = @code_complete_results[:results]
 					@results = []
-					@size.times {@results << Result.new(Lib::CXCompletionResult.new(cur_ptr))
-																		cur_ptr += Lib::CXCompletionResult.size
-					}
+					@size.times do |i|
+						completion_result = Lib::CXCompletionResult.new(cur_ptr)
+						@results << Result.new(completion_result, self, i)
+						cur_ptr += Lib::CXCompletionResult.size
+					end
 				end
 			end
 			
@@ -136,8 +146,12 @@ module FFI
 			class Result
 				# Initialize a completion result.
 				# @parameter result [Lib::CXCompletionResult] The completion result structure.
-				def initialize(result)
+				# @parameter owner [Results | Nil] The owning Results object (prevents GC of the parent allocation).
+				# @parameter index [Integer | Nil] The index of this result in the parent.
+				def initialize(result, owner = nil, index = nil)
 					@result = result
+					@owner = owner
+					@index = index
 				end
 				
 				# Get the kind of completion.
@@ -152,6 +166,25 @@ module FFI
 					CodeCompletion::String.new @result[:string]
 				end
 				
+				# Get the number of fix-its required before this completion can be applied.
+				# @returns [Integer] The number of fix-its.
+				def num_fix_its
+					return 0 unless @owner
+					
+					Lib.get_completion_num_fix_its(@owner.code_complete_results, @index)
+				end
+				
+				# Get all fix-its for this completion result.
+				# @returns [Array(FixIt)] The fix-its.
+				def fix_its
+					num_fix_its.times.map do |i|
+						range_ptr = MemoryPointer.new(Lib::CXSourceRange, 1)
+						text = Lib.extract_string(Lib.get_completion_fix_it(@owner.code_complete_results, @index, i, range_ptr))
+						range = SourceRange.new(Lib::CXSourceRange.new(range_ptr))
+						FixIt.new(text, range)
+					end
+				end
+				
 				# Get a string representation of this result.
 				# @returns [String] The result as a string.
 				def inspect
@@ -159,6 +192,23 @@ module FFI
 				end
 			end
 			
+			# Represents a fix-it that must be applied before a completion can be inserted.
+			class FixIt
+				# @attribute [r] text
+				# 	@returns [String] The replacement text.
+				# @attribute [r] range
+				# 	@returns [SourceRange] The source range to replace.
+				attr_reader :text, :range
+				
+				# Initialize a fix-it.
+				# @parameter text [String] The replacement text.
+				# @parameter range [SourceRange] The source range to replace.
+				def initialize(text, range)
+					@text = text
+					@range = range
+				end
+			end
+			
 			# Represents a code completion string with chunks.
 			class String
 				# Initialize a completion string.
@@ -197,7 +247,7 @@ module FFI
 				# Get all chunks as an array of hashes.
 				# @returns [Array(Hash)] Array of chunk hashes with `:kind`, `:text`, and `:completion` keys.
 				def chunks
-					num_chunks.times.map {|i|
+					num_chunks.times.map{|i|
 						{ kind: chunk_kind(i), text: chunk_text(i), completion: chunk_completion(i) }
 					}
 				end
@@ -230,7 +280,7 @@ module FFI
 				# Get all annotations.
 				# @returns [Array(String)] Array of annotation strings.
 				def annotations
-					num_annotations.times.map {|i|
+					num_annotations.times.map{|i|
 						Lib.extract_string Lib.get_completion_annotation(@pointer, i)
 					}
 				end