# DExTer : Debugging Experience Tester
# ~~~~~~ ~ ~~ ~ ~~
#
# Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
# See https://llvm.org/LICENSE.txt for license information.
# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
"""Base class for all debugger interface implementations."""
import abc
import os
import sys
import traceback
import unittest
from types import SimpleNamespace
from dex.command.CommandBase import StepExpectInfo
from dex.dextIR import DebuggerIR, FrameIR, LocIR, StepIR, ValueIR
from dex.utils.Exceptions import DebuggerException
from dex.utils.ReturnCode import ReturnCode
def watch_is_active(watch_info: StepExpectInfo, path, frame_idx, line_no):
_, watch_path, watch_frame_idx, watch_line_range = watch_info
# If this watch should only be active for a specific file...
if watch_path and os.path.isfile(watch_path):
# If the current path does not match the expected file, this watch is
# not active.
if not (path and os.path.isfile(path) and os.path.samefile(path, watch_path)):
return False
if watch_frame_idx != frame_idx:
return False
if watch_line_range and line_no not in list(watch_line_range):
return False
return True
class DebuggerBase(object, metaclass=abc.ABCMeta):
def __init__(self, context):
self.context = context
# Note: We can't already read values from options
# as DebuggerBase is created before we initialize options
# to read potential_debuggers.
self.options = self.context.options
self._interface = None
self.has_loaded = False
self._loading_error = None
try:
self._interface = self._load_interface()
self.has_loaded = True
except DebuggerException:
self._loading_error = sys.exc_info()
def __enter__(self):
try:
self._custom_init()
self.clear_breakpoints()
except DebuggerException:
self._loading_error = sys.exc_info()
return self
def __exit__(self, *args):
self._custom_exit()
def _custom_init(self):
pass
def _custom_exit(self):
pass
@property
def debugger_info(self):
return DebuggerIR(name=self.name, version=self.version)
@property
def is_available(self):
return self.has_loaded and self.loading_error is None
@property
def loading_error(self):
return str(self._loading_error[1]) if self._loading_error is not None else None
@property
def loading_error_trace(self):
if not self._loading_error:
return None
tb = traceback.format_exception(*self._loading_error)
if self._loading_error[1].orig_exception is not None:
orig_exception = traceback.format_exception(
*self._loading_error[1].orig_exception
)
if "".join(orig_exception) not in "".join(tb):
tb.extend(["\n"])
tb.extend(orig_exception)
tb = "".join(tb).splitlines(True)
return tb
def _sanitize_function_name(self, name): # pylint: disable=no-self-use
"""If the function name returned by the debugger needs any post-
processing to make it fit (for example, if it includes a byte offset),
do that here.
"""
return name
@abc.abstractmethod
def _load_interface(self):
pass
@classmethod
def get_option_name(cls):
"""Short name that will be used on the command line to specify this
debugger.
"""
raise NotImplementedError()
@classmethod
def get_name(cls):
"""Full name of this debugger."""
raise NotImplementedError()
@property
def name(self):
return self.__class__.get_name()
@property
def option_name(self):
return self.__class__.get_option_name()
@abc.abstractproperty
def version(self):
pass
@abc.abstractmethod
def clear_breakpoints(self):
pass
def add_breakpoint(self, file_, line):
"""Returns a unique opaque breakpoint id.
The ID type depends on the debugger being used, but will probably be
an int.
"""
return self._add_breakpoint(self._external_to_debug_path(file_), line)
@abc.abstractmethod
def _add_breakpoint(self, file_, line):
"""Returns a unique opaque breakpoint id."""
pass
def add_conditional_breakpoint(self, file_, line, condition):
"""Returns a unique opaque breakpoint id.
The ID type depends on the debugger being used, but will probably be
an int.
"""
return self._add_conditional_breakpoint(
self._external_to_debug_path(file_), line, condition
)
@abc.abstractmethod
def _add_conditional_breakpoint(self, file_, line, condition):
"""Returns a unique opaque breakpoint id."""
pass
@abc.abstractmethod
def delete_breakpoints(self, ids):
"""Delete a set of breakpoints by ids.
Raises a KeyError if, for any id, no breakpoint with that id exists.
"""
pass
@abc.abstractmethod
def get_triggered_breakpoint_ids(self):
"""Returns a set of opaque ids for just-triggered breakpoints."""
pass
@abc.abstractmethod
def launch(self):
pass
@abc.abstractmethod
def step(self):
pass
@abc.abstractmethod
def go(self) -> ReturnCode:
pass
def get_step_info(self, watches, step_index):
step_info = self._get_step_info(watches, step_index)
for frame in step_info.frames:
frame.loc.path = self._debug_to_external_path(frame.loc.path)
return step_info
@abc.abstractmethod
def _get_step_info(self, watches, step_index):
pass
@abc.abstractproperty
def is_running(self):
pass
@abc.abstractproperty
def is_finished(self):
pass
@abc.abstractproperty
def frames_below_main(self):
pass
@abc.abstractmethod
def evaluate_expression(self, expression, frame_idx=0) -> ValueIR:
pass
def _external_to_debug_path(self, path):
if not self.options.debugger_use_relative_paths:
return path
root_dir = self.options.source_root_dir
if not root_dir or not path:
return path
assert path.startswith(root_dir)
return path[len(root_dir) :].lstrip(os.path.sep)
def _debug_to_external_path(self, path):
if not self.options.debugger_use_relative_paths:
return path
if not path or not self.options.source_root_dir:
return path
for file in self.options.source_files:
if path.endswith(self._external_to_debug_path(file)):
return file
return path
class TestDebuggerBase(unittest.TestCase):
class MockDebugger(DebuggerBase):
def __init__(self, context, *args):
super().__init__(context, *args)
self.step_info = None
self.breakpoint_file = None
def _add_breakpoint(self, file, line):
self.breakpoint_file = file
def _get_step_info(self, watches, step_index):
return self.step_info
def __init__(self, *args):
super().__init__(*args)
TestDebuggerBase.MockDebugger.__abstractmethods__ = set()
self.options = SimpleNamespace(source_root_dir="", source_files=[])
context = SimpleNamespace(options=self.options)
self.dbg = TestDebuggerBase.MockDebugger(context)
def _new_step(self, paths):
frames = [
FrameIR(
function=None,
is_inlined=False,
loc=LocIR(path=path, lineno=0, column=0),
)
for path in paths
]
return StepIR(step_index=0, stop_reason=None, frames=frames)
def _step_paths(self, step):
return [frame.loc.path for frame in step.frames]
def test_add_breakpoint_no_source_root_dir(self):
self.options.debugger_use_relative_paths = True
self.options.source_root_dir = ""
path = os.path.join(os.path.sep + "root", "some_file")
self.dbg.add_breakpoint(path, 12)
self.assertEqual(path, self.dbg.breakpoint_file)
def test_add_breakpoint_with_source_root_dir(self):
self.options.debugger_use_relative_paths = True
self.options.source_root_dir = os.path.sep + "my_root"
path = os.path.join(self.options.source_root_dir, "some_file")
self.dbg.add_breakpoint(path, 12)
self.assertEqual("some_file", self.dbg.breakpoint_file)
def test_add_breakpoint_with_source_root_dir_slash_suffix(self):
self.options.debugger_use_relative_paths = True
self.options.source_root_dir = os.path.sep + "my_root" + os.path.sep
path = os.path.join(self.options.source_root_dir, "some_file")
self.dbg.add_breakpoint(path, 12)
self.assertEqual("some_file", self.dbg.breakpoint_file)
def test_get_step_info_no_source_root_dir(self):
self.options.debugger_use_relative_paths = True
path = os.path.join(os.path.sep + "root", "some_file")
self.dbg.step_info = self._new_step([path])
self.assertEqual([path], self._step_paths(self.dbg.get_step_info([], 0)))
def test_get_step_info_no_frames(self):
self.options.debugger_use_relative_paths = True
self.options.source_root_dir = os.path.sep + "my_root"
self.dbg.step_info = self._new_step([])
self.assertEqual([], self._step_paths(self.dbg.get_step_info([], 0)))
def test_get_step_info(self):
self.options.debugger_use_relative_paths = True
self.options.source_root_dir = os.path.sep + "my_root"
path = os.path.join(self.options.source_root_dir, "some_file")
self.options.source_files = [path]
other_path = os.path.join(os.path.sep + "other", "file")
dbg_path = os.path.join(os.path.sep + "dbg", "some_file")
self.dbg.step_info = self._new_step([None, other_path, dbg_path])
self.assertEqual(
[None, other_path, path], self._step_paths(self.dbg.get_step_info([], 0))
)
Codebase Browser
llvm