toolbox 0.1.4 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 694d8c20e3efb7fad4c3ce738ab9784308fca74971e7198e627458349be2f316
+  data.tar.gz: 41e1fa7e7352ade3a28fdc90ec0db233f937dfef0ddb1a1ac819c052c9edb1f4
+SHA512:
+  metadata.gz: 65ebb449eadbcd6c92ba560aac7fd3216e9e50c2fdc2864eb2daf2c0169191d678c7cda7956e3a3ee359eab926bc08c13ff0d8fd1605509b999cb69516d8031a
+  data.tar.gz: '0806493639960770d85ff768e2ad985657b46b7db46327acdfb6248e44cf1cb6b39586273975ce7c7f2e5128307cfc0a667cc13e846d29023615e3b7f9c79068'

data/bake/ruby/gdb.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "ruby/gdb"
+require "fileutils"
+
+# Install GDB extensions by adding source line to ~/.gdbinit
+# @parameter gdbinit [String] Optional path to .gdbinit (defaults to ~/.gdbinit)
+def install(gdbinit: nil)
+	gdbinit_path = gdbinit || File.join(Dir.home, ".gdbinit")
+	init_py_path = Ruby::GDB.init_script_path
+	source_line = "source #{init_py_path}"
+	marker_comment = "# Ruby GDB Extensions (ruby-gdb gem)"
+	
+	puts "Installing Ruby GDB extensions..."
+	puts "  Extensions: #{File.dirname(init_py_path)}"
+	puts "  Config: #{gdbinit_path}"
+	
+	# Read existing .gdbinit or create empty array
+	lines = File.exist?(gdbinit_path) ? File.readlines(gdbinit_path) : []
+	
+	# Check if already installed (look for marker comment)
+	marker_index = lines.index{|line| line.strip == marker_comment}
+	
+	if marker_index
+		# Already installed - update the source line in case path changed
+		source_index = marker_index + 1
+		if source_index < lines.size && lines[source_index].strip.start_with?("source")
+			old_source = lines[source_index].strip
+			if old_source == source_line
+				puts "\n✓ Already installed in #{gdbinit_path}"
+				puts "  #{source_line}"
+				return
+			else
+				# Path changed - update it
+				lines[source_index] = "#{source_line}\n"
+				File.write(gdbinit_path, lines.join)
+				puts "\n✓ Updated installation in #{gdbinit_path}"
+				puts "  Old: #{old_source}"
+				puts "  New: #{source_line}"
+				return
+			end
+		end
+	end
+	
+	# Not installed - add it
+	File.open(gdbinit_path, "a") do |f|
+		f.puts unless lines.last&.strip&.empty?
+		f.puts marker_comment
+		f.puts source_line
+	end
+	
+	puts "\n✓ Installation complete!"
+	puts "\nAdded to #{gdbinit_path}:"
+	puts "  #{source_line}"
+	puts "\nExtensions will load automatically when you start GDB."
+end
+
+# Uninstall GDB extensions by removing source line from ~/.gdbinit
+# @parameter gdbinit [String] Optional path to .gdbinit (defaults to ~/.gdbinit)
+def uninstall(gdbinit: nil)
+	gdbinit_path = gdbinit || File.join(Dir.home, ".gdbinit")
+	marker_comment = "# Ruby GDB Extensions (ruby-gdb gem)"
+	
+	puts "Uninstalling Ruby GDB extensions..."
+	
+	unless File.exist?(gdbinit_path)
+		puts "No ~/.gdbinit file found - nothing to uninstall."
+		return
+	end
+	
+	lines = File.readlines(gdbinit_path)
+	marker_index = lines.index{|line| line.strip == marker_comment}
+	
+	unless marker_index
+		puts "Extensions were not found in #{gdbinit_path}"
+		return
+	end
+	
+	# Remove the marker comment and the source line after it
+	lines.delete_at(marker_index)  # Remove comment
+	if marker_index < lines.size && lines[marker_index].strip.start_with?("source")
+		removed_line = lines.delete_at(marker_index).strip  # Remove source line
+		puts "  Removed: #{removed_line}"
+	end
+	
+	# Clean up empty line before marker if it exists
+	if marker_index > 0 && lines[marker_index - 1].strip.empty?
+		lines.delete_at(marker_index - 1)
+	end
+	
+	File.write(gdbinit_path, lines.join)
+	puts "✓ Removed Ruby GDB extensions from #{gdbinit_path}"
+end
+
+# Show installation information
+# @parameter gdbinit [String] Optional path to .gdbinit (defaults to ~/.gdbinit)
+def info(gdbinit: nil)
+	gdbinit_path = gdbinit || File.join(Dir.home, ".gdbinit")
+	init_py_path = Ruby::GDB.init_script_path
+	marker_comment = "# Ruby GDB Extensions (ruby-gdb gem)"
+	
+	puts "Ruby GDB Extensions v#{Ruby::GDB::VERSION}"
+	puts "\nGem data directory: #{Ruby::GDB.data_path}"
+	puts "Init script: #{init_py_path}"
+	
+	# Check installation status by looking for marker comment
+	installed = false
+	current_source = nil
+	
+	if File.exist?(gdbinit_path)
+		lines = File.readlines(gdbinit_path)
+		marker_index = lines.index{|line| line.strip == marker_comment}
+		if marker_index
+			installed = true
+			source_index = marker_index + 1
+			if source_index < lines.size
+				current_source = lines[source_index].strip
+			end
+		end
+	end
+	
+	puts "\nGDB config: #{gdbinit_path}"
+	if installed
+		puts "Status: ✓ Installed"
+		if current_source
+			puts "  #{current_source}"
+		end
+	else
+		puts "Status: ✗ Not installed"
+		puts "\nRun: bake ruby:gdb:install"
+	end
+end

data/bake/toolbox/gdb.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "toolbox/gdb"
+require "fileutils"
+
+# Install GDB extensions by adding source line to ~/.gdbinit
+# @parameter gdbinit [String] Optional path to .gdbinit (defaults to ~/.gdbinit)
+def install(gdbinit: nil)
+	gdbinit_path = gdbinit || File.join(Dir.home, ".gdbinit")
+	init_py_path = Toolbox::GDB.init_script_path
+	source_line = "source #{init_py_path}"
+	marker_comment = "# Ruby Toolbox GDB Extensions"
+	
+	puts "Installing Ruby Toolbox GDB extensions..."
+	puts "  Extensions: #{File.dirname(init_py_path)}"
+	puts "  Config: #{gdbinit_path}"
+	
+	# Read existing .gdbinit or create empty array
+	lines = File.exist?(gdbinit_path) ? File.readlines(gdbinit_path) : []
+	
+	# Check if already installed (look for marker comment)
+	marker_index = lines.index{|line| line.strip == marker_comment}
+	
+	if marker_index
+		# Already installed - update the source line in case path changed
+		source_index = marker_index + 1
+		if source_index < lines.size && lines[source_index].strip.start_with?("source")
+			old_source = lines[source_index].strip
+			if old_source == source_line
+				puts "\n✓ Already installed in #{gdbinit_path}"
+				puts "  #{source_line}"
+				return
+			else
+				# Path changed - update it
+				lines[source_index] = "#{source_line}\n"
+				File.write(gdbinit_path, lines.join)
+				puts "\n✓ Updated installation in #{gdbinit_path}"
+				puts "  Old: #{old_source}"
+				puts "  New: #{source_line}"
+				return
+			end
+		end
+	end
+	
+	# Not installed - add it
+	File.open(gdbinit_path, "a") do |f|
+		f.puts unless lines.last&.strip&.empty?
+		f.puts marker_comment
+		f.puts source_line
+	end
+	
+	puts "\n✓ Installation complete!"
+	puts "\nAdded to #{gdbinit_path}:"
+	puts "  #{source_line}"
+	puts "\nExtensions will load automatically when you start GDB."
+end
+
+# Uninstall GDB extensions by removing source line from ~/.gdbinit
+# @parameter gdbinit [String] Optional path to .gdbinit (defaults to ~/.gdbinit)
+def uninstall(gdbinit: nil)
+	gdbinit_path = gdbinit || File.join(Dir.home, ".gdbinit")
+	marker_comment = "# Ruby Toolbox GDB Extensions"
+	
+	puts "Uninstalling Ruby Toolbox GDB extensions..."
+	
+	unless File.exist?(gdbinit_path)
+		puts "No ~/.gdbinit file found - nothing to uninstall."
+		return
+	end
+	
+	lines = File.readlines(gdbinit_path)
+	marker_index = lines.index{|line| line.strip == marker_comment}
+	
+	unless marker_index
+		puts "Extensions were not found in #{gdbinit_path}"
+		return
+	end
+	
+	# Remove the marker comment and the source line after it
+	lines.delete_at(marker_index)  # Remove comment
+	if marker_index < lines.size && lines[marker_index].strip.start_with?("source")
+		removed_line = lines.delete_at(marker_index).strip  # Remove source line
+		puts "  Removed: #{removed_line}"
+	end
+	
+	# Clean up empty line before marker if it exists
+	if marker_index > 0 && lines[marker_index - 1].strip.empty?
+		lines.delete_at(marker_index - 1)
+	end
+	
+	File.write(gdbinit_path, lines.join)
+	puts "✓ Removed Ruby Toolbox GDB extensions from #{gdbinit_path}"
+end
+
+# Show installation information
+# @parameter gdbinit [String] Optional path to .gdbinit (defaults to ~/.gdbinit)
+def info(gdbinit: nil)
+	gdbinit_path = gdbinit || File.join(Dir.home, ".gdbinit")
+	init_py_path = Toolbox::GDB.init_script_path
+	marker_comment = "# Ruby Toolbox GDB Extensions"
+	
+	puts "Ruby Toolbox GDB Extensions v#{Toolbox::VERSION}"
+	puts "\nToolbox directory: #{Toolbox::GDB.data_path}"
+	puts "Init script: #{init_py_path}"
+	puts "Note: Same init.py works for both GDB and LLDB"
+	
+	# Check installation status by looking for marker comment
+	installed = false
+	current_source = nil
+	
+	if File.exist?(gdbinit_path)
+		lines = File.readlines(gdbinit_path)
+		marker_index = lines.index{|line| line.strip == marker_comment}
+		if marker_index
+			installed = true
+			source_index = marker_index + 1
+			if source_index < lines.size
+				current_source = lines[source_index].strip
+			end
+		end
+	end
+	
+	puts "\nGDB config: #{gdbinit_path}"
+	if installed
+		puts "Status: ✓ Installed"
+		if current_source
+			puts "  #{current_source}"
+		end
+	else
+		puts "Status: ✗ Not installed"
+		puts "\nRun: bake toolbox:gdb:install"
+	end
+end
+

data/bake/toolbox/lldb.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require "toolbox/lldb"
+require "fileutils"
+
+# Install LLDB extensions by adding command to ~/.lldbinit
+# @parameter lldbinit [String] Optional path to .lldbinit (defaults to ~/.lldbinit)
+def install(lldbinit: nil)
+	lldbinit_path = lldbinit || File.join(Dir.home, ".lldbinit")
+	init_py_path = Toolbox::LLDB.init_script_path
+	command_line = "command script import #{init_py_path}"
+	marker_comment = "# Ruby Toolbox LLDB Extensions"
+	
+	puts "Installing Ruby Toolbox LLDB extensions..."
+	puts "  Extensions: #{File.dirname(init_py_path)}"
+	puts "  Config: #{lldbinit_path}"
+	
+	# Read existing .lldbinit or create empty array
+	lines = File.exist?(lldbinit_path) ? File.readlines(lldbinit_path) : []
+	
+	# Check if already installed (look for marker comment)
+	marker_index = lines.index{|line| line.strip == marker_comment}
+	
+	if marker_index
+		# Already installed - update the command line in case path changed
+		command_index = marker_index + 1
+		if command_index < lines.size && lines[command_index].strip.start_with?("command script import")
+			old_command = lines[command_index].strip
+			if old_command == command_line
+				puts "\n✓ Already installed in #{lldbinit_path}"
+				puts "  #{command_line}"
+				return
+			else
+				# Path changed - update it
+				lines[command_index] = "#{command_line}\n"
+				File.write(lldbinit_path, lines.join)
+				puts "\n✓ Updated installation in #{lldbinit_path}"
+				puts "  Old: #{old_command}"
+				puts "  New: #{command_line}"
+				return
+			end
+		end
+	end
+	
+	# Not installed - add it
+	File.open(lldbinit_path, "a") do |f|
+		f.puts unless lines.last&.strip&.empty?
+		f.puts marker_comment
+		f.puts command_line
+	end
+	
+	puts "\n✓ Installation complete!"
+	puts "\nAdded to #{lldbinit_path}:"
+	puts "  #{command_line}"
+	puts "\nExtensions will load automatically when you start LLDB."
+end
+
+# Uninstall LLDB extensions by removing command from ~/.lldbinit
+# @parameter lldbinit [String] Optional path to .lldbinit (defaults to ~/.lldbinit)
+def uninstall(lldbinit: nil)
+	lldbinit_path = lldbinit || File.join(Dir.home, ".lldbinit")
+	marker_comment = "# Ruby Toolbox LLDB Extensions"
+	
+	puts "Uninstalling Ruby Toolbox LLDB extensions..."
+	
+	unless File.exist?(lldbinit_path)
+		puts "No ~/.lldbinit file found - nothing to uninstall."
+		return
+	end
+	
+	lines = File.readlines(lldbinit_path)
+	marker_index = lines.index{|line| line.strip == marker_comment}
+	
+	unless marker_index
+		puts "Extensions were not found in #{lldbinit_path}"
+		return
+	end
+	
+	# Remove the marker comment and the command line after it
+	lines.delete_at(marker_index)  # Remove comment
+	if marker_index < lines.size && lines[marker_index].strip.start_with?("command script import")
+		removed_line = lines.delete_at(marker_index).strip  # Remove command line
+		puts "  Removed: #{removed_line}"
+	end
+	
+	# Clean up empty line before marker if it exists
+	if marker_index > 0 && lines[marker_index - 1].strip.empty?
+		lines.delete_at(marker_index - 1)
+	end
+	
+	File.write(lldbinit_path, lines.join)
+	puts "✓ Removed Ruby Toolbox LLDB extensions from #{lldbinit_path}"
+end
+
+# Show installation information
+# @parameter lldbinit [String] Optional path to .lldbinit (defaults to ~/.lldbinit)
+def info(lldbinit: nil)
+	lldbinit_path = lldbinit || File.join(Dir.home, ".lldbinit")
+	init_py_path = Toolbox::LLDB.init_script_path
+	marker_comment = "# Ruby Toolbox LLDB Extensions"
+	
+	puts "Ruby Toolbox LLDB Extensions v#{Toolbox::VERSION}"
+	puts "\nToolbox directory: #{Toolbox::LLDB.data_path}"
+	puts "Init script: #{init_py_path}"
+	puts "Note: Same init.py works for both GDB and LLDB"
+	
+	# Check installation status by looking for marker comment
+	installed = false
+	current_command = nil
+	
+	if File.exist?(lldbinit_path)
+		lines = File.readlines(lldbinit_path)
+		marker_index = lines.index{|line| line.strip == marker_comment}
+		if marker_index
+			installed = true
+			command_index = marker_index + 1
+			if command_index < lines.size
+				current_command = lines[command_index].strip
+			end
+		end
+	end
+	
+	puts "\nLLDB config: #{lldbinit_path}"
+	if installed
+		puts "Status: ✓ Installed"
+		if current_command
+			puts "  #{current_command}"
+		end
+	else
+		puts "Status: ✗ Not installed"
+		puts "\nRun: bake toolbox:lldb:install"
+	end
+end
+

data/context/fiber-debugging.md

@@ -0,0 +1,171 @@
+# Fiber Debugging
+
+This guide explains how to debug Ruby fibers using GDB, including inspecting fiber state, backtraces, and switching between fiber contexts.
+
+## Why Fiber Debugging is Critical
+
+When debugging concurrent Ruby applications, fibers can be in various states - running, suspended, or terminated. Unlike traditional debugging where you see one call stack, fiber-based programs have multiple execution contexts simultaneously. Understanding what each fiber is doing and why it stopped is essential for diagnosing deadlocks, exceptions, and state corruption.
+
+Use fiber debugging when you need:
+
+- **Diagnose deadlocks**: See which fibers are waiting and on what
+- **Find hidden exceptions**: Discover exceptions in suspended fibers that haven't propagated yet
+- **Understand concurrency**: Visualize what all fibers are doing at a point in time
+- **Debug async code**: Navigate between fiber contexts to trace execution flow
+
+## Scanning for Fibers
+
+The first step in fiber debugging is finding all fibers in the heap.
+
+### Basic Scan
+
+Scan the entire Ruby heap for fiber objects:
+
+~~~
+(gdb) rb-fiber-scan-heap
+Scanning heap for Fiber objects...
+  Checked 45000 objects, found 12 fiber(s)...
+
+Found 12 fiber(s):
+
+Fiber #0: <T_DATA@...> → <struct rb_fiber_struct@...>
+  Status: SUSPENDED
+  Stack: <void *@...>
+  VM Stack: <VALUE *@...>
+  CFP: <rb_control_frame_t@...>
+  
+Fiber #1: <T_DATA@...> → <struct rb_fiber_struct@...>
+  Status: SUSPENDED
+  ...
+~~~
+
+### Limiting Results
+
+For large applications, limit the scan:
+
+~~~
+(gdb) rb-fiber-scan-heap --limit 10    # Find first 10 fibers only
+~~~
+
+### Caching Results
+
+Cache fiber addresses for faster subsequent access:
+
+~~~
+(gdb) rb-fiber-scan-heap --cache            # Save to fibers.json
+(gdb) rb-fiber-scan-heap --cache my.json    # Custom cache file
+~~~
+
+Later, load from cache instantly:
+
+~~~
+(gdb) rb-fiber-scan-heap --cache
+Loaded 12 fiber(s) from fibers.json
+~~~
+
+This is especially useful with core dumps where heap scanning is slow.
+
+## Inspecting Specific Fibers
+
+After scanning, you can switch to a specific fiber's context or view all backtraces.
+
+### View All Fiber Backtraces
+
+See Ruby-level call stacks for all fibers at once:
+
+~~~
+(gdb) rb-fiber-scan-stack-trace-all
+Found 12 fiber(s)
+
+Fiber #0: <T_DATA@...> → <struct rb_fiber_struct@...>
+  Status: RESUMED
+  [No backtrace - fiber is running]
+
+Fiber #1: <T_DATA@...> → <struct rb_fiber_struct@...>
+  Status: SUSPENDED
+  /app/lib/connection.rb:123:in `read'
+  /app/lib/connection.rb:89:in `receive'
+  /app/lib/server.rb:56:in `handle_client'
+  ...
+
+Fiber #5: <T_DATA@...> → <struct rb_fiber_struct@...>
+  Status: SUSPENDED  
+  Exception: IOError: Connection reset
+  /app/lib/connection.rb:45:in `write'
+  ...
+~~~
+
+This gives you a complete overview of what every fiber is doing.
+
+## Switching Fiber Context
+
+The most powerful feature: switch GDB's view to a fiber's stack (even in core dumps!).
+
+### Basic Usage
+
+~~~
+(gdb) rb-fiber-scan-heap
+(gdb) rb-fiber-scan-switch 5
+Switching to Fiber #5: VALUE 0x...
+Switched to Fiber: <T_DATA@...> → <struct rb_fiber_struct@...>
+  Status: SUSPENDED
+
+Convenience variables set:
+  $fiber     = Current fiber VALUE
+  $fiber_ptr = Current fiber pointer (struct rb_fiber_struct *)
+  $ec        = Execution context (rb_execution_context_t *)
+  $errinfo   = Exception being handled (VALUE)
+
+Now try:
+  bt          # Show C backtrace of fiber
+  rb-stack-trace  # Show combined Ruby/C backtrace
+  info locals     # Show local variables
+~~~
+
+After switching, all standard GDB commands work with the fiber's context:
+
+~~~
+(gdb) rb-stack-trace            # Combined Ruby/C backtrace
+(gdb) bt                        # C backtrace of fiber
+#0  0x00007f8a1c567890 in fiber_setcontext
+#1  0x00007f8a1c567900 in rb_fiber_yield
+#2  0x00007f8a1c234567 in rb_io_wait_readable
+...
+
+(gdb) frame 2
+(gdb) info locals              # Local C variables in that frame
+~~~
+
+### Switching by VALUE
+
+You can also switch to a specific fiber by its VALUE or address:
+
+~~~
+(gdb) rb-fiber-switch 0x7f8a1c800500
+~~~
+
+### Switching Back
+
+Return to normal stack view:
+
+~~~
+(gdb) rb-fiber-scan-switch off
+~~~
+
+## Analyzing Fiber State
+
+After switching to a fiber with `rb-fiber-scan-switch`, you can use standard GDB commands to inspect the fiber's state:
+
+~~~
+(gdb) rb-fiber-scan-switch 5
+(gdb) bt                    # Show C backtrace
+(gdb) frame <n>             # Switch to specific frame
+(gdb) info locals           # Show local variables
+(gdb) rb-object-print $errinfo  # Print exception if present
+~~~
+
+The fiber switch command sets up several convenience variables:
+- `$fiber` - The fiber VALUE
+- `$fiber_ptr` - Pointer to `struct rb_fiber_struct`
+- `$ec` - The fiber's execution context
+- `$errinfo` - Exception being handled (if any)