Author: Med Ismail Bennani Date: 2024-07-02T15:20:18-07:00 New Revision: 622df0ee9226b90e924538909337d55333d5d2fa
URL: https://github.com/llvm/llvm-project/commit/622df0ee9226b90e924538909337d55333d5d2fa DIFF: https://github.com/llvm/llvm-project/commit/622df0ee9226b90e924538909337d55333d5d2fa.diff LOG: [lldb] Add scripted thread plan python base class to lldb & website (#97481) Following a feedback request in #97262, I took out the scripted thread plan python base class from it and make a separate PR for it. This patch adds the scripted thread plan base python class to the lldb python module as well as the lldb documentation website. Signed-off-by: Med Ismail Bennani <ism...@bennani.ma> Added: lldb/docs/python_extensions.rst lldb/examples/python/templates/scripted_thread_plan.py Modified: lldb/bindings/python/CMakeLists.txt lldb/docs/CMakeLists.txt Removed: ################################################################################ diff --git a/lldb/bindings/python/CMakeLists.txt b/lldb/bindings/python/CMakeLists.txt index def6941e802bb..69306a384e0b1 100644 --- a/lldb/bindings/python/CMakeLists.txt +++ b/lldb/bindings/python/CMakeLists.txt @@ -108,7 +108,9 @@ function(finish_swig_python swig_target lldb_python_bindings_dir lldb_python_tar "${LLDB_SOURCE_DIR}/examples/python/templates/parsed_cmd.py" "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_process.py" "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_platform.py" - "${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py") + "${LLDB_SOURCE_DIR}/examples/python/templates/operating_system.py" + "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_thread_plan.py" + ) if(APPLE) create_python_package( diff --git a/lldb/docs/CMakeLists.txt b/lldb/docs/CMakeLists.txt index ed4296bbf03a4..f1664a6965332 100644 --- a/lldb/docs/CMakeLists.txt +++ b/lldb/docs/CMakeLists.txt @@ -31,6 +31,7 @@ if (LLDB_ENABLE_PYTHON AND SPHINX_FOUND) COMMAND "${CMAKE_COMMAND}" -E copy "${LLDB_SOURCE_DIR}/examples/python/templates/scripted_process.py" "${CMAKE_CURRENT_BINARY_DIR}/lldb/plugins/" 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/" COMMENT "Copying lldb.py to pretend its a Python package.") add_dependencies(lldb-python-doc-package swig_wrapper_python lldb-python) diff --git a/lldb/docs/python_extensions.rst b/lldb/docs/python_extensions.rst new file mode 100644 index 0000000000000..7e5f1ba6879db --- /dev/null +++ b/lldb/docs/python_extensions.rst @@ -0,0 +1,39 @@ +Python Extensions +================= + +LLDB provides scriptable extensions to augment the debugger's capabilities. +This gives users the ability to tailor their debugging experience to their own needs. + +This page describes some of these scripting extensions: + +Operating System Thread Plugins +------------------------------- + +.. automodapi:: lldb.plugins.operating_system + :no-heading: + :skip: ScriptedThread + :no-inheritance-diagram: + +Scripted Process Plugins +------------------------------- + +.. automodapi:: lldb.plugins.scripted_process + :no-heading: + :skip: ABCMeta + :no-inheritance-diagram: + +Scripted Platform Plugins +------------------------------- + +.. automodapi:: lldb.plugins.scripted_platform + :no-heading: + :skip: ABCMeta + :no-inheritance-diagram: + +Scripted Thread Plan Plugins +------------------------------- + +.. automodapi:: lldb.plugins.scripted_thread_plan + :no-heading: + :no-inheritance-diagram: + diff --git a/lldb/examples/python/templates/scripted_thread_plan.py b/lldb/examples/python/templates/scripted_thread_plan.py new file mode 100644 index 0000000000000..67396cdfc53a2 --- /dev/null +++ b/lldb/examples/python/templates/scripted_thread_plan.py @@ -0,0 +1,70 @@ +from abc import abstractmethod + +import lldb + + +class ScriptedThreadPlan: + """ + Class that provides data for an instance of a LLDB 'ScriptedThreadPlan' plug-in class used to construct custom stepping logic. + + """ + + def __init__(self, thread_plan: lldb.SBThreadPlan): + """Initialization needs a valid lldb.SBThreadPlan object. This plug-in will get created after a live process is valid and has stopped. + + Args: + thread_plan (lldb.SBThreadPlan): The underlying `ThreadPlan` that is pushed onto the plan stack. + """ + self.thread_plan = thread_plan + + def explains_stop(self, event: lldb.SBEvent) -> bool: + """Each plan is asked from youngest to oldest if it "explains" the stop. The first plan to claim the stop wins. + + Args: + event (lldb.SBEvent): The process stop event. + + Returns: + bool: `True` if this stop could be claimed by this thread plan, `False` otherwise. + Defaults to `True`. + """ + return True + + def is_stale(self) -> bool: + """If your plan is no longer relevant (for instance, you were stepping in a particular stack frame, but some other operation pushed that frame off the stack) return True and your plan will get popped. + + Returns: + bool: `True` if this thread plan is stale, `False` otherwise. + Defaults to `False`. + """ + return False + + def should_stop(self, event: lldb.SBEvent) -> bool: + """Whether this thread plan should stop and return control to the user. + If your plan is done at this point, call SetPlanComplete on your thread plan instance. Also, do any work you need here to set up the next stage of stepping. + + Args: + event (lldb.SBEvent): The process stop event. + + Returns: + bool: `True` if this plan wants to stop and return control to the user at this point, `False` otherwise. + Defaults to `False`. + """ + self.thread_plan.SetPlanComplete(True) + return True + + def should_step(self) -> bool: + """Whether this thread plan should instruction step one instruction, or continue till the next breakpoint is hit. + + Returns: + bool: `True` if this plan will instruction step one instruction, `False` otherwise. + Defaults to `True`. + """ + return True + + def stop_description(self, stream: lldb.SBStream) -> None: + """Customize the thread plan stop reason when the thread plan is complete. + + Args: + stream (lldb.SBStream): The stream containing the stop description. + """ + pass _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
