ruby-gdb 0.1.0

data/data/ruby/gdb/value.py

@@ -0,0 +1,181 @@
+import gdb
+import constants
+import format
+
+import rbasic
+import rfloat
+import rsymbol
+import rstring
+import rarray
+import rhash
+import rstruct
+import rbignum
+
+class RImmediate:
+	"""Wrapper for Ruby immediate values (fixnum, nil, true, false)."""
+	
+	def __init__(self, value):
+		self.value = value
+		self.val_int = int(value)
+	
+	def __str__(self):
+		if self.val_int == 0:
+			return "<T_FALSE>"
+		elif self.val_int == 0x04 or self.val_int == 0x08:
+			return "<T_NIL>"
+		elif self.val_int == 0x14:
+			return "<T_TRUE>"
+		elif (self.val_int & 0x01) != 0:
+			# Fixnum - shift right to get actual value
+			return str(self.val_int >> 1)
+		else:
+			# Unknown immediate
+			return f"<Immediate:0x{self.val_int:x}>"
+	
+	def print_to(self, terminal):
+		"""Print this value with formatting to the given terminal."""
+		if self.val_int == 0:
+			return terminal.print(format.metadata, '<', format.type, 'T_FALSE', format.metadata, '>', format.reset)
+		elif self.val_int == 0x04 or self.val_int == 0x08:
+			return terminal.print(format.metadata, '<', format.type, 'T_NIL', format.metadata, '>', format.reset)
+		elif self.val_int == 0x14:
+			return terminal.print(format.metadata, '<', format.type, 'T_TRUE', format.metadata, '>', format.reset)
+		elif (self.val_int & 0x01) != 0:
+			# Fixnum - shift right to get actual value
+			tag = terminal.print(format.metadata, '<', format.type, 'T_FIXNUM', format.metadata, '>', format.reset)
+			num = terminal.print(format.number, str(self.val_int >> 1), format.reset)
+			return f"{tag} {num}"
+		else:
+			# Unknown immediate
+			return f"<Immediate:0x{self.val_int:x}>"
+	
+	def print_recursive(self, printer, depth):
+		"""Print this immediate value (no recursion needed)."""
+		printer.print(self)
+
+def is_nil(value):
+	"""Check if a Ruby VALUE is nil.
+	
+	Arguments:
+		value: A GDB value representing a Ruby VALUE
+	
+	Returns:
+		True if the value is nil (Qnil), False otherwise
+	"""
+	val_int = int(value)
+	# Qnil can be 0x04 or 0x08 depending on Ruby version
+	return val_int == 0x04 or val_int == 0x08
+
+def is_immediate(value):
+	"""Check if a Ruby VALUE is an immediate value.
+	
+	Immediate values include fixnum, symbols, nil, true, false.
+	They are encoded directly in the VALUE, not as heap objects.
+	
+	Arguments:
+		value: A GDB value representing a Ruby VALUE
+	
+	Returns:
+		True if the value is immediate, False if it's a heap object
+	"""
+	val_int = int(value)
+	# Check for special constants (Qfalse=0, Qnil=0x04/0x08, Qtrue=0x14)
+	# or immediate values (fixnum, symbol, flonum) which have low bits set
+	return val_int == 0 or (val_int & 0x03) != 0
+
+def is_object(value):
+	"""Check if a Ruby VALUE is a heap object (not immediate).
+	
+	Arguments:
+		value: A GDB value representing a Ruby VALUE
+	
+	Returns:
+		True if the value is a heap object, False if it's immediate
+	"""
+	return not is_immediate(value)
+
+def is_exception(value):
+	"""Check if a Ruby VALUE is an exception object.
+	
+	Arguments:
+		value: A GDB value representing a Ruby VALUE
+	
+	Returns:
+		True if the value appears to be an exception object, False otherwise
+	"""
+	if not is_object(value):
+		return False
+	
+	try:
+		# Check if it's a T_OBJECT or T_DATA (exceptions can be either)
+		basic = value.cast(constants.get_type("struct RBasic").pointer())
+		flags = int(basic.dereference()['flags'])
+		type_flag = flags & constants.get("RUBY_T_MASK")
+		
+		# Exceptions are typically T_OBJECT, but could also be T_DATA
+		# We can't reliably determine if it's an exception without checking the class hierarchy
+		# So we just check if it's an object type that could be an exception
+		t_object = constants.get("RUBY_T_OBJECT")
+		t_data = constants.get("RUBY_T_DATA")
+		
+		return type_flag == t_object or type_flag == t_data
+	except Exception:
+		return False
+
+def interpret(value):
+	"""Interpret a Ruby VALUE and return the appropriate typed object.
+	
+	This is a factory function that examines the value and returns the
+	most specific type wrapper available (RString, RArray, RHash, etc.),
+	or RBasic as a fallback for unhandled types.
+	
+	For immediate values (fixnum, flonum, symbol, nil, true, false), it returns
+	the appropriate wrapper (RImmediate, RFloat, RSymbol).
+	
+	Arguments:
+		value: A GDB value representing a Ruby VALUE
+	
+	Returns:
+		An instance of the appropriate type class (never None)
+	"""
+	val_int = int(value)
+	
+	# Check for immediate flonum (must be before fixnum check)
+	if rfloat.is_flonum(value):
+		return rfloat.RFloat(value)
+	
+	# Check if it's a symbol (immediate or heap)
+	if rsymbol.is_symbol(value):
+		return rsymbol.RSymbol(value)
+	
+	# Handle special constants and fixnum (anything with low bits set)
+	if val_int == 0 or val_int == 0x04 or val_int == 0x08 or val_int == 0x14 or (val_int & 0x01) != 0:
+		return RImmediate(value)
+	
+	# It's a heap object, examine its type
+	try:
+		basic = value.cast(constants.get_type("struct RBasic").pointer())
+		flags = int(basic.dereference()['flags'])
+		type_flag = flags & constants.get("RUBY_T_MASK")
+		
+		# Map type flags to their corresponding factory functions
+		if type_flag == constants.get("RUBY_T_STRING"):
+			return rstring.RString(value)
+		elif type_flag == constants.get("RUBY_T_ARRAY"):
+			return rarray.RArray(value)
+		elif type_flag == constants.get("RUBY_T_HASH"):
+			return rhash.RHash(value)
+		elif type_flag == constants.get("RUBY_T_STRUCT"):
+			return rstruct.RStruct(value)
+		elif type_flag == constants.get("RUBY_T_SYMBOL"):
+			return rsymbol.RSymbol(value)
+		elif type_flag == constants.get("RUBY_T_FLOAT"):
+			return rfloat.RFloat(value)
+		elif type_flag == constants.get("RUBY_T_BIGNUM"):
+			return rbignum.RBignum(value)
+		else:
+			# Unknown type - return generic RBasic
+			return rbasic.RBasic(value)
+	except Exception:
+		# If we can't examine it, return a generic wrapper
+		return rbasic.RBasic(value)

data/lib/ruby/gdb/version.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+# @namespace
+module Ruby
+	# @namespace
+	module GDB
+		VERSION = "0.1.0"
+	end
+end
+

data/lib/ruby/gdb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Samuel Williams.
+
+require_relative "gdb/version"
+
+module Ruby
+	module GDB
+		# Path to the GDB extension scripts.
+		def self.data_path
+			File.expand_path("../../data", __dir__)
+		end
+		
+		# Path to the init.py script.
+		def self.init_script_path
+			File.join(data_path, "ruby", "gdb", "init.py")
+		end
+		
+		
+		
+	end
+end

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, by Samuel Williams.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,42 @@
+# Ruby::GDB
+
+Ruby debugging extensions for GDB, providing commands for inspecting Ruby objects, fibers, and VM internals.
+
+[![Development Status](https://github.com/socketry/ruby-gdb/workflows/Test/badge.svg)](https://github.com/socketry/ruby-gdb/actions?workflow=Test)
+
+## Usage
+
+Please see the [project documentation](https://socketry.github.io/ruby-gdb/) for more details.
+
+  - [Getting Started](https://socketry.github.io/ruby-gdb/guides/getting-started/index) - This guide explains how to install and use Ruby GDB extensions for debugging Ruby programs and core dumps.
+
+  - [Object Inspection](https://socketry.github.io/ruby-gdb/guides/object-inspection/index) - This guide explains how to use `rb-object-print` to inspect Ruby objects, hashes, arrays, and structs in GDB.
+
+  - [Stack Inspection](https://socketry.github.io/ruby-gdb/guides/stack-inspection/index) - This guide explains how to inspect both Ruby VM stacks and native C stacks when debugging Ruby programs.
+
+  - [Fiber Debugging](https://socketry.github.io/ruby-gdb/guides/fiber-debugging/index) - This guide explains how to debug Ruby fibers using GDB, including inspecting fiber state, backtraces, and switching between fiber contexts.
+
+  - [Heap Debugging](https://socketry.github.io/ruby-gdb/guides/heap-debugging/index) - This guide explains how to navigate Ruby's heap to find objects, diagnose memory issues, and understand object relationships.
+
+## See Also
+
+  - [GDB Python API Documentation](https://sourceware.org/gdb/current/onlinedocs/gdb.html/Python-API.html)
+  - [Ruby VM Internals](https://docs.ruby-lang.org/en/master/extension_rdoc.html)
+
+## Contributing
+
+We welcome contributions to this project.
+
+1.  Fork it.
+2.  Create your feature branch (`git checkout -b my-new-feature`).
+3.  Commit your changes (`git commit -am 'Add some feature'`).
+4.  Push to the branch (`git push origin my-new-feature`).
+5.  Create new Pull Request.
+
+### Developer Certificate of Origin
+
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
+
+### Community Guidelines
+
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: ruby-gdb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Samuel Williams
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- bake/ruby/gdb.rb
+- context/fiber-debugging.md
+- context/getting-started.md
+- context/heap-debugging.md
+- context/index.yaml
+- context/object-inspection.md
+- context/stack-inspection.md
+- data/ruby/gdb/command.py
+- data/ruby/gdb/constants.py
+- data/ruby/gdb/fiber.py
+- data/ruby/gdb/format.py
+- data/ruby/gdb/heap.py
+- data/ruby/gdb/init.py
+- data/ruby/gdb/object.py
+- data/ruby/gdb/rarray.py
+- data/ruby/gdb/rbasic.py
+- data/ruby/gdb/rbignum.py
+- data/ruby/gdb/rclass.py
+- data/ruby/gdb/rexception.py
+- data/ruby/gdb/rfloat.py
+- data/ruby/gdb/rhash.py
+- data/ruby/gdb/rstring.py
+- data/ruby/gdb/rstruct.py
+- data/ruby/gdb/rsymbol.py
+- data/ruby/gdb/stack.py
+- data/ruby/gdb/value.py
+- lib/ruby/gdb.rb
+- lib/ruby/gdb/version.rb
+- license.md
+- readme.md
+homepage: https://github.com/socketry/ruby-gdb
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/ruby-gdb/
+  source_code_uri: https://github.com/socketry/ruby-gdb
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby debugging extensions for GDB
+test_files: []