[Lldb-commits] [lldb] [lldb/script] Add missing scripted extension base-class templates (PR #209311)
Med Ismail Bennani via lldb-commits
lldb-commits at lists.llvm.org
Mon Jul 13 16:01:17 PDT 2026
https://github.com/medismailben updated https://github.com/llvm/llvm-project/pull/209311
>From 3abc9fc2d602a46fa5bd1af0e9812ca5824b57bb Mon Sep 17 00:00:00 2001
From: Med Ismail Bennani <ismail at bennani.ma>
Date: Mon, 13 Jul 2026 16:01:01 -0700
Subject: [PATCH] [lldb/script] Add missing scripted extension base-class
templates
This patch adds the missing Python base-class templates for
`ScriptedBreakpoint`, `ScriptedStopHook` and `ScriptedHook`, and wires
them into the Python bindings and docs CMake so every scriptable
extension kind has a template that the docs and future tooling can
introspect.
Signed-off-by: Med Ismail Bennani <ismail at bennani.ma>
---
lldb/bindings/python/CMakeLists.txt | 3 +
lldb/docs/CMakeLists.txt | 3 +
.../python/templates/scripted_breakpoint.py | 105 ++++++++++++++++++
.../python/templates/scripted_hook.py | 59 ++++++++++
.../python/templates/scripted_stop_hook.py | 38 +++++++
5 files changed, 208 insertions(+)
create mode 100644 lldb/examples/python/templates/scripted_breakpoint.py
create mode 100644 lldb/examples/python/templates/scripted_hook.py
create mode 100644 lldb/examples/python/templates/scripted_stop_hook.py
diff --git a/lldb/bindings/python/CMakeLists.txt b/lldb/bindings/python/CMakeLists.txt
index 4cf216728ede8..34a048ca16b43 100644
--- a/lldb/bindings/python/CMakeLists.txt
+++ b/lldb/bindings/python/CMakeLists.txt
@@ -117,6 +117,9 @@ function(finish_swig_python swig_target lldb_python_bindings_dir lldb_python_tar
"${LLDB_SOURCE_DIR}/examples/python/templates/scripted_platform.py"
"${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py"
"${LLDB_SOURCE_DIR}/examples/python/templates/scripted_thread_plan.py"
+ "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_breakpoint.py"
+ "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_stop_hook.py"
+ "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_hook.py"
)
if(APPLE)
diff --git a/lldb/docs/CMakeLists.txt b/lldb/docs/CMakeLists.txt
index ccdcb4df1c60e..24cbddc5d6e73 100644
--- a/lldb/docs/CMakeLists.txt
+++ b/lldb/docs/CMakeLists.txt
@@ -30,6 +30,9 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND)
COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_platform.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_thread_plan.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
+ COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_breakpoint.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
+ COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_stop_hook.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
+ COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_hook.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/"
COMMENT "Copying lldb.py to pretend its a Python package.")
add_dependencies(lldb-python-doc-package swig_wrapper_python)
diff --git a/lldb/examples/python/templates/scripted_breakpoint.py b/lldb/examples/python/templates/scripted_breakpoint.py
new file mode 100644
index 0000000000000..b46ffade34743
--- /dev/null
+++ b/lldb/examples/python/templates/scripted_breakpoint.py
@@ -0,0 +1,105 @@
+from abc import ABCMeta, abstractmethod
+
+import lldb
+
+
+class ScriptedBreakpointResolver(metaclass=ABCMeta):
+ """
+ The base class for a scripted breakpoint resolver.
+ """
+
+ @abstractmethod
+ def __init__(self, bkpt, args):
+ """Construct a scripted breakpoint resolver.
+
+ Args:
+ bkpt (lldb.SBBreakpoint): The breakpoint owning this resolver.
+ args (lldb.SBStructuredData): A Dictionary holding arbitrary
+ key/value pairs used by the scripted breakpoint.
+ """
+ self.bkpt = bkpt
+ self.args = args
+
+ def overrides_resolver(self, resolver_data):
+ """Decide, from the incoming resolver options, whether this
+ breakpoint should have its resolver replaced by this class. When
+ `True`, this class's `__callback__` picks locations for this
+ breakpoint instead of the original resolver's. Search depth is
+ unaffected either way and still comes from `__get_depth__`.
+
+ Args:
+ resolver_data (lldb.SBStructuredData): The resolver options
+ passed in when the breakpoint was created.
+
+ Returns:
+ bool: `True` if this class's `__callback__` should be used in
+ place of the original resolver's, `False` to leave the
+ original resolver in charge.
+ """
+ return False
+
+ def set_breakpoint(self, bkpt):
+ """Called once the underlying breakpoint has been fully created and
+ associated to this resolver.
+
+ Args:
+ bkpt (lldb.SBBreakpoint): The breakpoint owning this resolver.
+ """
+ pass
+
+ @abstractmethod
+ def __callback__(self, sym_ctx):
+ """Called once per symbol context matched by the search depth
+ returned by `__get_depth__`. Set breakpoint locations here by calling
+ `AddLocation` on the resolver's breakpoint.
+
+ Args:
+ sym_ctx (lldb.SBSymbolContext): The symbol context to inspect.
+ """
+ pass
+
+ def __get_depth__(self):
+ """The search depth at which `__callback__` will be called.
+
+ Returns:
+ lldb.SBSearchDepth: One of the `lldb.eSearchDepth*` values.
+ Defaults to `lldb.eSearchDepthModule`.
+ """
+ return lldb.eSearchDepthModule
+
+ def get_short_help(self):
+ """A one-line description of this resolver, shown by `breakpoint list`.
+
+ Returns:
+ str: The short help string.
+ """
+ pass
+
+ def was_hit(self, frame, bp_loc):
+ """Called when a location owned by this resolver is hit, to allow
+ overriding which location is reported as hit.
+
+ Args:
+ frame (lldb.SBFrame): The frame where the breakpoint was hit.
+ bp_loc (lldb.SBBreakpointLocation): The breakpoint location that
+ was hit.
+
+ Returns:
+ lldb.SBBreakpointLocation: The location to report as hit.
+ Defaults to `bp_loc`.
+ """
+ return bp_loc
+
+ def get_location_description(self, bp_loc, level):
+ """Customize the description used when printing a breakpoint location
+ owned by this resolver.
+
+ Args:
+ bp_loc (lldb.SBBreakpointLocation): The breakpoint location to
+ describe.
+ level (lldb.DescriptionLevel): The level of detail requested.
+
+ Returns:
+ str: The description for the location.
+ """
+ pass
diff --git a/lldb/examples/python/templates/scripted_hook.py b/lldb/examples/python/templates/scripted_hook.py
new file mode 100644
index 0000000000000..81e900db4dec9
--- /dev/null
+++ b/lldb/examples/python/templates/scripted_hook.py
@@ -0,0 +1,59 @@
+from abc import ABCMeta, abstractmethod
+
+import lldb
+
+
+class ScriptedHook(metaclass=ABCMeta):
+ """
+ The base class for a scripted target hook.
+
+ A scripted hook can react to multiple target lifecycle events (module
+ load, module unload, process stop) through a single class. Override
+ only the methods for the events you care about.
+ """
+
+ @abstractmethod
+ def __init__(self, target, args):
+ """Construct a scripted hook.
+
+ Args:
+ target (lldb.SBTarget): The target owning this hook.
+ args (lldb.SBStructuredData): A Dictionary holding arbitrary
+ key/value pairs used by the scripted hook.
+ """
+ self.target = target
+ self.args = args
+
+ def handle_module_loaded(self, stream):
+ """Called whenever a module is loaded into the target.
+
+ Args:
+ stream (lldb.SBStream): The stream to which the hook can write
+ output that will be reported to the user.
+ """
+ pass
+
+ def handle_module_unloaded(self, stream):
+ """Called whenever a module is unloaded from the target.
+
+ Args:
+ stream (lldb.SBStream): The stream to which the hook can write
+ output that will be reported to the user.
+ """
+ pass
+
+ def handle_stop(self, exe_ctx, stream):
+ """Called whenever the process stops, before control is returned to
+ the user.
+
+ Args:
+ exe_ctx (lldb.SBExecutionContext): The execution context at the
+ point of the stop.
+ stream (lldb.SBStream): The stream to which the hook can write
+ output that will be reported to the user.
+
+ Returns:
+ bool: `True` if the process should stop and control should be
+ returned to the user, `False` if the process should keep running.
+ """
+ pass
diff --git a/lldb/examples/python/templates/scripted_stop_hook.py b/lldb/examples/python/templates/scripted_stop_hook.py
new file mode 100644
index 0000000000000..de0d3794e2b24
--- /dev/null
+++ b/lldb/examples/python/templates/scripted_stop_hook.py
@@ -0,0 +1,38 @@
+from abc import ABCMeta, abstractmethod
+
+import lldb
+
+
+class ScriptedStopHook(metaclass=ABCMeta):
+ """
+ The base class for a scripted stop-hook.
+ """
+
+ @abstractmethod
+ def __init__(self, target, args):
+ """Construct a scripted stop-hook.
+
+ Args:
+ target (lldb.SBTarget): The target owning this stop-hook.
+ args (lldb.SBStructuredData): A Dictionary holding arbitrary
+ key/value pairs used by the scripted stop-hook.
+ """
+ self.target = target
+ self.args = args
+
+ @abstractmethod
+ def handle_stop(self, exe_ctx, stream):
+ """Called whenever the process stops, before control is returned to
+ the user.
+
+ Args:
+ exe_ctx (lldb.SBExecutionContext): The execution context at the
+ point of the stop.
+ stream (lldb.SBStream): The stream to which the stop-hook can
+ write output that will be reported to the user.
+
+ Returns:
+ bool: `True` if the process should stop and control should be
+ returned to the user, `False` if the process should keep running.
+ """
+ pass
More information about the lldb-commits
mailing list