lldb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a9c4b0d0816a16700d8fc4e5b7bcb5e122875ead9fcfc8a2dde3c722e68d827
-  data.tar.gz: 6268f8c9bea45f4947cdb5a95ca5d95603e1d322e16f2f4aa1267c84f258b84c
+  metadata.gz: 6e620343dac990365f90f32d8bd349abee9969a5f3cf51ddd255ab8b37e739ea
+  data.tar.gz: 527026156a888a96244a6687a31559bafcfb619b0c4eb91c96799689a02fbe90
 SHA512:
-  metadata.gz: f305a6a355a1f599bd2706e8e9531c6a465ff17bf45aa3525bfac8f1c0a9f6cc3ecaf32bfc78f0ff7006b383094ad653e0656a5f994ab2a86335c632f57812d1
-  data.tar.gz: cdbe16e161820379724b65595ce44d4d04f307f3edb1c9cae6f854b6088f90e7d7ea654799fef0f5126243e41c020e4b84a412a4b4dd7e03510db039c7f8eecf
+  metadata.gz: '087ad913a4adcc1db493e844ff844ea1fb6a86f01199606a9af606f5016d7e08a6fde5866842b9ffb7e1e2008e71d0e08e7de6094f1f9d6d51589239d9d0ee5d'
+  data.tar.gz: ebdfcbf627a830bc905cf41d80d5c6526039a96ae432f4c8fc1bcfec818c72486191d036a86a3c348cb4256c34739ba5d920b26578f13e47ac660e1e98efbcc7

data/CHANGELOG.md

@@ -1,12 +1,51 @@
 # Changelog
 
-## Unreleased
+All notable changes to this project will be documented in this file.
 
-## 0.2.0 - 2026-01-04
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-08-12
+
+### Added
+
+- Expose thread step modes and command return statuses, and return `nil` from `Process#send_async_interrupt`.
+- Add explicit broadcaster, listener, and event handles for LLDB state events.
+- Add `source_init_files`, `LaunchInfo`, `AttachInfo`, and `ExpressionOptions` controls.
+- Expose structured `FileSpec`, `Address`, `LineEntry`, and `FileSpecList` objects with dynamically sized path buffers and LLDB sentinel constants.
+- Expose `TypeMember` metadata for fields and direct or virtual base classes.
+- Expose structured `Symbol`, `Function`, `CompileUnit`, and `Block` objects from modules and frames.
+- Expose structured instruction lists and instruction bytes from frames.
+- Add LLDB discovery and compile/link validation for Linux and macOS builds.
+- Expose wrapper ABI and LLDB version metadata with capability-based watchpoint access checks.
+- Add binding parity, surface-ledger, reproducible RBS, and sanitizer checks.
+
+### Changed
+
+- Preserve LLDB operation status, error type, and operation context.
+- Make `Target#launch` preserve LLDB launch semantics without implicit flags, polling, or auto-continue.
+- Release Ruby's GVL around launch, attach, continue, stepping, and command execution calls.
+- Normalize basic type values across LLDB versions.
+- Pin the RBS collection revision and verify generated RBS deterministically.
+
+### Fixed
+
+- Report native wrapper exceptions as `InternalBindingError`.
+- Add idempotent native handles, shared debugger contexts, and deterministic debugger close.
+- Make native finalizer release safe under GC stress.
+- Prevent native build artifacts from leaking into built gems.
+
+## [0.2.0] - 2026-01-04
+
+### Added
 
 - Add MemoryRegionInfo bindings.
 - Add APISupport module for feature detection.
 
-## 0.1.0 - 2025-12-30
+## [0.1.0] - 2025-12-30
+
+### Added
 
-- Initial release.
+- Initial release.

data/README.md

@@ -1,4 +1,4 @@
-# LLDB Ruby
+# LLDB Ruby [![Gem Version](https://badge.fury.io/rb/lldb.svg)](https://badge.fury.io/rb/lldb) [![CI](https://github.com/ydah/lldb-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/ydah/lldb-ruby/actions/workflows/ci.yml)
 
 Ruby bindings for the LLDB debugger.
 
@@ -9,7 +9,7 @@ This gem provides Ruby bindings for LLDB (Low Level Debugger), allowing you to a
 ## Requirements
 
 - Ruby 3.0 or later
-- LLDB 14 or later
+- LLDB 14 or later (Linux and macOS)
 - C++17 compatible compiler (gcc 8+ / clang 10+)
 - libffi-dev (for the FFI gem)
 
@@ -165,6 +165,53 @@ if var && var.valid?
 end
 ```
 
+`Target#launch` passes the launch request directly to LLDB. It does not add
+`STOP_AT_ENTRY`, wait for a state transition, or auto-continue to a breakpoint.
+Set `launch_flags: LLDB::LaunchFlags::STOP_AT_ENTRY` explicitly when that
+behavior is required; callers are responsible for waiting on asynchronous
+processes.
+
+### Handling Events Explicitly
+
+Use LLDB's listener queue when asynchronous state changes are needed:
+
+```ruby
+listener = debugger.listener
+broadcaster = process.broadcaster
+listener.start_listening_for_events(broadcaster, LLDB::Process::BroadcastBit::STATE_CHANGED)
+
+if (event = listener.wait_for_event(timeout_seconds: 1))
+  puts "state = #{LLDB::State.name(event.process_state)}"
+end
+```
+
+`timeout_seconds: 0` performs a non-blocking poll. The library does not start
+background event threads.
+
+Source locations remain structured when needed: `Frame#line_entry` exposes its
+`LineEntry`, including `start_address`, `end_address`, file, line, and column;
+`BreakpointLocation#address` exposes an `Address` with separate
+`file_address` and `load_address` values. `FileSpecList` can collect and return
+`FileSpec` objects without reducing them to path strings.
+
+Type inspection also preserves member metadata. Use `Type#field_at_index`,
+`#direct_base_class_at_index`, or `#virtual_base_class_at_index` to obtain a
+`TypeMember` with its name, type, byte/bit offset, and bitfield width.
+
+Modules and frames expose structured debug objects as well: use
+`Module#symbol_at_index`, `Frame#function`, `Frame#symbol`,
+`Frame#compile_unit`, and `Frame#block` to retain symbol, function, source
+unit, and lexical block metadata.
+
+For structured disassembly, use `Frame#instruction_list`. Each
+`Instruction` exposes its address, mnemonic, operands, comment, byte size, and
+raw bytes; the existing `Frame#disassemble` string API remains available.
+
+Debugger and launch choices are explicit option objects. For example,
+`LLDB::Debugger.create(source_init_files: true)` opts into LLDB init files,
+while `LLDB::ExpressionOptions` can be passed to expression evaluation without
+changing the no-options call path.
+
 ### Working with Threads
 
 ```ruby
@@ -196,8 +243,18 @@ process = target.attach(pid: 12345)
 - `LLDB::Thread` - Represents an execution thread
 - `LLDB::Frame` - Represents a stack frame
 - `LLDB::Breakpoint` - Represents a breakpoint
+- `LLDB::BreakpointLocation` - Represents a breakpoint location
 - `LLDB::Value` - Represents a variable or expression result
+- `LLDB::Type` - Represents debug type information
+- `LLDB::TypeMember` - Represents a field or base-class member
 - `LLDB::Module` - Represents a loaded module
+- `LLDB::Symbol` - Represents a symbol
+- `LLDB::Function` - Represents a function
+- `LLDB::CompileUnit` - Represents a compilation unit
+- `LLDB::Block` - Represents a lexical block
+- `LLDB::InstructionList` / `LLDB::Instruction` - Represents structured disassembly
+- `LLDB::FileSpec` / `LLDB::Address` / `LLDB::LineEntry` - Represents source locations
+- `LLDB::Listener` / `LLDB::Event` / `LLDB::Broadcaster` - Represents LLDB events
 - `LLDB::Error` - Represents an error from LLDB
 
 ### Constants
@@ -209,9 +266,22 @@ Process states are available in `LLDB::State`:
 Stop reasons are available in `LLDB::StopReason`:
 - `INVALID`, `NONE`, `TRACE`, `BREAKPOINT`, `WATCHPOINT`
 - `SIGNAL`, `EXCEPTION`, `EXEC`, `PLAN_COMPLETE`, `THREAD_EXITING`, `INSTRUMENTATION`
+- `PROCESSOR_TRACE`, `FORK`, `VFORK`, `VFORK_DONE`
 
 ## Development
 
+The native wrapper build discovers LLDB in this order:
+
+1. `--with-lldb-include` and `--with-lldb-lib`
+2. `--with-lldb-dir`
+3. `LLDB_DIR`
+4. `llvm-config` or a versioned `llvm-config-N` on `PATH`
+5. Homebrew, Xcode, and standard LLVM prefixes
+
+Discovery succeeds only after compiling and linking a C++17 probe against
+`liblldb`. The selected paths and optional API capabilities are printed during
+the build. Windows is not a supported platform yet.
+
 After checking out the repo, run:
 
 ```bash
@@ -220,6 +290,20 @@ cd ext/lldb && ruby extconf.rb && make && cd ../..
 bundle exec rspec
 ```
 
+Binding and type-surface checks can be run with:
+
+```bash
+bundle exec rake bindings:check
+bundle exec rake rbs:verify
+```
+
+`bindings/surface.yml` records the classification and exception-safety review
+for every native export. Update it together with any new header declaration.
+
+Only calls that can wait for the inferior, debugger server, or command script
+release Ruby's GVL. The wrapper does not invoke Ruby callbacks from those
+calls; adding callback APIs requires revisiting this policy.
+
 To run tests, you need to compile the test fixtures:
 
 ```bash

data/Rakefile

@@ -2,6 +2,8 @@
 
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
+require 'shellwords'
+require 'tmpdir'
 
 RSpec::Core::RakeTask.new(:spec)
 
@@ -47,6 +49,7 @@ task :clean do
   Dir.chdir(ext_dir) do
     system('make clean') if File.exist?('Makefile')
     FileUtils.rm_f('Makefile')
+    FileUtils.rm_f('lldb_wrapper_config.h')
   end
 
   FileUtils.rm_f(File.join(lib_dir, 'liblldb_wrapper.dylib'))
@@ -74,6 +77,39 @@ namespace :steep do
   end
 end
 
+namespace :bindings do
+  desc 'Check native, FFI, RBS, and surface-ledger parity'
+  task check: :compile do
+    sh 'ruby script/check_bindings'
+  end
+end
+
+namespace :rbs do
+  desc 'Verify that generated RBS output is deterministic'
+  task :verify do
+    Dir.mktmpdir('lldb-ruby-rbs') do |directory|
+      outputs = %w[first second].map { |name| File.join(directory, name) }
+      outputs.each do |output|
+        sh "bundle exec rbs-inline --output=#{Shellwords.escape(output)} lib"
+      end
+
+      files = lambda do |root|
+        Dir.glob(File.join(root, '**/*.rbs')).map do |path|
+          path.delete_prefix("#{root}#{File::SEPARATOR}")
+        end.sort
+      end
+      first_files, second_files = outputs.map { |output| files.call(output) }
+      abort 'RBS output file set is not reproducible' unless first_files == second_files
+
+      first_files.each do |relative|
+        first = File.binread(File.join(outputs[0], relative))
+        second = File.binread(File.join(outputs[1], relative))
+        abort "RBS output is not reproducible: #{relative}" unless first == second
+      end
+    end
+  end
+end
+
 desc 'Run steep type check'
 task steep: ['steep:check']
 

data/bindings/constants.yml

@@ -0,0 +1,137 @@
+version: 1
+
+constants:
+  - ruby: INVALID_ADDRESS
+    native: LLDB_INVALID_ADDRESS
+  - ruby: INVALID_PROCESS_ID
+    native: LLDB_INVALID_PROCESS_ID
+  - ruby: INVALID_THREAD_ID
+    native: LLDB_INVALID_THREAD_ID
+  - ruby: INVALID_BREAK_ID
+    native: LLDB_INVALID_BREAK_ID
+  - ruby: INVALID_LINE_NUMBER
+    native: LLDB_INVALID_LINE_NUMBER
+  - ruby: State::INVALID
+    native: lldb::eStateInvalid
+  - ruby: State::UNLOADED
+    native: lldb::eStateUnloaded
+  - ruby: State::CONNECTED
+    native: lldb::eStateConnected
+  - ruby: State::ATTACHING
+    native: lldb::eStateAttaching
+  - ruby: State::LAUNCHING
+    native: lldb::eStateLaunching
+  - ruby: State::STOPPED
+    native: lldb::eStateStopped
+  - ruby: State::RUNNING
+    native: lldb::eStateRunning
+  - ruby: State::STEPPING
+    native: lldb::eStateStepping
+  - ruby: State::CRASHED
+    native: lldb::eStateCrashed
+  - ruby: State::DETACHED
+    native: lldb::eStateDetached
+  - ruby: State::EXITED
+    native: lldb::eStateExited
+  - ruby: State::SUSPENDED
+    native: lldb::eStateSuspended
+  - ruby: StopReason::INVALID
+    native: lldb::eStopReasonInvalid
+  - ruby: StopReason::NONE
+    native: lldb::eStopReasonNone
+  - ruby: StopReason::TRACE
+    native: lldb::eStopReasonTrace
+  - ruby: StopReason::BREAKPOINT
+    native: lldb::eStopReasonBreakpoint
+  - ruby: StopReason::WATCHPOINT
+    native: lldb::eStopReasonWatchpoint
+  - ruby: StopReason::SIGNAL
+    native: lldb::eStopReasonSignal
+  - ruby: StopReason::EXCEPTION
+    native: lldb::eStopReasonException
+  - ruby: StopReason::EXEC
+    native: lldb::eStopReasonExec
+  - ruby: StopReason::PLAN_COMPLETE
+    native: lldb::eStopReasonPlanComplete
+  - ruby: StopReason::THREAD_EXITING
+    native: lldb::eStopReasonThreadExiting
+  - ruby: StopReason::INSTRUMENTATION
+    native: lldb::eStopReasonInstrumentation
+  - ruby: StopReason::PROCESSOR_TRACE
+    native: lldb::eStopReasonProcessorTrace
+  - ruby: StopReason::FORK
+    native: lldb::eStopReasonFork
+  - ruby: StopReason::VFORK
+    native: lldb::eStopReasonVFork
+  - ruby: StopReason::VFORK_DONE
+    native: lldb::eStopReasonVForkDone
+  - ruby: SymbolContextItem::TARGET
+    native: lldb::eSymbolContextTarget
+  - ruby: SymbolContextItem::MODULE
+    native: lldb::eSymbolContextModule
+  - ruby: SymbolContextItem::COMPILE_UNIT
+    native: lldb::eSymbolContextCompUnit
+  - ruby: SymbolContextItem::FUNCTION
+    native: lldb::eSymbolContextFunction
+  - ruby: SymbolContextItem::BLOCK
+    native: lldb::eSymbolContextBlock
+  - ruby: SymbolContextItem::LINE_ENTRY
+    native: lldb::eSymbolContextLineEntry
+  - ruby: SymbolContextItem::SYMBOL
+    native: lldb::eSymbolContextSymbol
+  - ruby: SymbolContextItem::EVERYTHING
+    native: lldb::eSymbolContextEverything
+  - ruby: SymbolContextItem::VARIABLE
+    native: lldb::eSymbolContextVariable
+  - ruby: ValueType::INVALID
+    native: lldb::eValueTypeInvalid
+  - ruby: ValueType::VARIABLE_GLOBAL
+    native: lldb::eValueTypeVariableGlobal
+  - ruby: ValueType::VARIABLE_STATIC
+    native: lldb::eValueTypeVariableStatic
+  - ruby: ValueType::VARIABLE_ARGUMENT
+    native: lldb::eValueTypeVariableArgument
+  - ruby: ValueType::VARIABLE_LOCAL
+    native: lldb::eValueTypeVariableLocal
+  - ruby: ValueType::REGISTER
+    native: lldb::eValueTypeRegister
+  - ruby: ValueType::REGISTER_SET
+    native: lldb::eValueTypeRegisterSet
+  - ruby: ValueType::CONSTANT_RESULT
+    native: lldb::eValueTypeConstResult
+  - ruby: ValueType::VARIABLE_THREAD_LOCAL
+    native: lldb::eValueTypeVariableThreadLocal
+  - ruby: ErrorType::INVALID
+    native: lldb::eErrorTypeInvalid
+  - ruby: ErrorType::GENERIC
+    native: lldb::eErrorTypeGeneric
+  - ruby: ErrorType::MACH_KERNEL
+    native: lldb::eErrorTypeMachKernel
+  - ruby: ErrorType::POSIX
+    native: lldb::eErrorTypePOSIX
+  - ruby: ErrorType::EXPRESSION
+    native: lldb::eErrorTypeExpression
+  - ruby: ErrorType::WIN32
+    native: lldb::eErrorTypeWin32
+  - ruby: ReturnStatus::INVALID
+    native: lldb::eReturnStatusInvalid
+  - ruby: ReturnStatus::SUCCESS_FINISH_NO_RESULT
+    native: lldb::eReturnStatusSuccessFinishNoResult
+  - ruby: ReturnStatus::SUCCESS_FINISH_RESULT
+    native: lldb::eReturnStatusSuccessFinishResult
+  - ruby: ReturnStatus::SUCCESS_CONTINUING_NO_RESULT
+    native: lldb::eReturnStatusSuccessContinuingNoResult
+  - ruby: ReturnStatus::SUCCESS_CONTINUING_RESULT
+    native: lldb::eReturnStatusSuccessContinuingResult
+  - ruby: ReturnStatus::STARTED
+    native: lldb::eReturnStatusStarted
+  - ruby: ReturnStatus::FAILED
+    native: lldb::eReturnStatusFailed
+  - ruby: ReturnStatus::QUIT
+    native: lldb::eReturnStatusQuit
+  - ruby: RunMode::ONLY_THIS_THREAD
+    native: lldb::eOnlyThisThread
+  - ruby: RunMode::ALL_THREADS
+    native: lldb::eAllThreads
+  - ruby: RunMode::ONLY_DURING_STEPPING
+    native: lldb::eOnlyDuringStepping