[Lldb-commits] [lldb] [lldb/docs] Breakdown python reference into multiple files (PR #158331)
via lldb-commits
lldb-commits at lists.llvm.org
Fri Sep 12 10:11:22 PDT 2025
llvmbot wrote:
<!--LLVM PR SUMMARY COMMENT-->
@llvm/pr-subscribers-lldb
Author: Med Ismail Bennani (medismailben)
<details>
<summary>Changes</summary>
This pages improve the LLDB website documentation readability and discoverability by breaking down the very long python-reference page into multiple subpages each explaining a specific topic.
The long term goal is to have tutorials for every scripting extension.
This also converts the pages into markdown, since it's easier to write.
---
Patch is 167.69 KiB, truncated to 20.00 KiB below, full version: https://github.com/llvm/llvm-project/pull/158331.diff
12 Files Affected:
- (modified) lldb/docs/use/python-reference.rst (+18-1123)
- (removed) lldb/docs/use/python.rst (-799)
- (added) lldb/docs/use/tutorials/accessing-documentation.md (+59)
- (added) lldb/docs/use/tutorials/breakpoint-triggered-scripts.md (+85)
- (added) lldb/docs/use/tutorials/creating-custom-breakpoints.md (+128)
- (added) lldb/docs/use/tutorials/custom-frame-recognizers.md (+52)
- (added) lldb/docs/use/tutorials/custom-stepping-behavior.md (+42)
- (added) lldb/docs/use/tutorials/python-embedded-interpreter.md (+66)
- (added) lldb/docs/use/tutorials/python-standalone-scripts.md (+132)
- (added) lldb/docs/use/tutorials/python-stop-hooks.md (+27)
- (added) lldb/docs/use/tutorials/script-driven-debugging.md (+492)
- (added) lldb/docs/use/tutorials/writing-custom-commands.md (+420)
``````````diff
diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst
index 4292714c9c208..1d61cb29ef821 100644
--- a/lldb/docs/use/python-reference.rst
+++ b/lldb/docs/use/python-reference.rst
@@ -10,1126 +10,21 @@ command interpreter (we refer to this for brevity as the embedded interpreter).
Of course, in this context it has full access to the LLDB API - with some
additional conveniences we will call out in the FAQ.
-Documentation
---------------
-
-The LLDB API is contained in a python module named lldb. A useful resource when
-writing Python extensions is the lldb Python classes reference guide.
-
-The documentation is also accessible in an interactive debugger session with
-the following command:
-
-::
-
- (lldb) script help(lldb)
- Help on package lldb:
-
- NAME
- lldb - The lldb module contains the public APIs for Python binding.
-
- FILE
- /System/Library/PrivateFrameworks/LLDB.framework/Versions/A/Resources/Python/lldb/__init__.py
-
- DESCRIPTION
- ...
-
-You can also get help using a module class name. The full API that is exposed
-for that class will be displayed in a man page style window. Below we want to
-get help on the lldb.SBFrame class:
-
-::
-
- (lldb) script help(lldb.SBFrame)
- Help on class SBFrame in module lldb:
-
- class SBFrame(__builtin__.object)
- | Represents one of the stack frames associated with a thread.
- | SBThread contains SBFrame(s). For example (from test/lldbutil.py),
- |
- | def print_stacktrace(thread, string_buffer = False):
- | '''Prints a simple stack trace of this thread.'''
- |
- ...
-
-Or you can get help using any python object, here we use the lldb.process
-object which is a global variable in the lldb module which represents the
-currently selected process:
-
-::
-
- (lldb) script help(lldb.process)
- Help on SBProcess in module lldb object:
-
- class SBProcess(__builtin__.object)
- | Represents the process associated with the target program.
- |
- | SBProcess supports thread iteration. For example (from test/lldbutil.py),
- |
- | # ==================================================
- | # Utility functions related to Threads and Processes
- | # ==================================================
- |
- ...
-
-Embedded Python Interpreter
----------------------------
-
-The embedded python interpreter can be accessed in a variety of ways from
-within LLDB. The easiest way is to use the lldb command script with no
-arguments at the lldb command prompt:
-
-::
-
- (lldb) script
- Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
- >>> 2+3
- 5
- >>> hex(12345)
- '0x3039'
- >>>
-
-This drops you into the embedded python interpreter. When running under the
-script command, lldb sets some convenience variables that give you quick access
-to the currently selected entities that characterize the program and debugger
-state. In each case, if there is no currently selected entity of the
-appropriate type, the variable's IsValid method will return false. These
-variables are:
-
-+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
-| Variable | Type | Equivalent | Description |
-+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
-| ``lldb.debugger`` | `lldb.SBDebugger` | `SBTarget.GetDebugger` | Contains the debugger object whose ``script`` command was invoked. |
-| | | | The `lldb.SBDebugger` object owns the command interpreter |
-| | | | and all the targets in your debug session. There will always be a |
-| | | | Debugger in the embedded interpreter. |
-+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
-| ``lldb.target`` | `lldb.SBTarget` | `SBDebugger.GetSelectedTarget` | Contains the currently selected target - for instance the one made with the |
-| | | | ``file`` or selected by the ``target select <target-index>`` command. |
-| | | `SBProcess.GetTarget` | The `lldb.SBTarget` manages one running process, and all the executable |
-| | | | and debug files for the process. |
-+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
-| ``lldb.process`` | `lldb.SBProcess` | `SBTarget.GetProcess` | Contains the process of the currently selected target. |
-| | | | The `lldb.SBProcess` object manages the threads and allows access to |
-| | | `SBThread.GetProcess` | memory for the process. |
-+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
-| ``lldb.thread`` | `lldb.SBThread` | `SBProcess.GetSelectedThread` | Contains the currently selected thread. |
-| | | | The `lldb.SBThread` object manages the stack frames in that thread. |
-| | | `SBFrame.GetThread` | A thread is always selected in the command interpreter when a target stops. |
-| | | | The ``thread select <thread-index>`` command can be used to change the |
-| | | | currently selected thread. So as long as you have a stopped process, there will be |
-| | | | some selected thread. |
-+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
-| ``lldb.frame`` | `lldb.SBFrame` | `SBThread.GetSelectedFrame` | Contains the currently selected stack frame. |
-| | | | The `lldb.SBFrame` object manage the stack locals and the register set for |
-| | | | that stack. |
-| | | | A stack frame is always selected in the command interpreter when a target stops. |
-| | | | The ``frame select <frame-index>`` command can be used to change the |
-| | | | currently selected frame. So as long as you have a stopped process, there will |
-| | | | be some selected frame. |
-+-------------------+---------------------+-------------------------------------+-------------------------------------------------------------------------------------+
-
-While extremely convenient, these variables have a couple caveats that you
-should be aware of. First of all, they hold the values of the selected objects
-on entry to the embedded interpreter. They do not update as you use the LLDB
-API's to change, for example, the currently selected stack frame or thread.
-
-Moreover, they are only defined and meaningful while in the interactive Python
-interpreter. There is no guarantee on their value in any other situation, hence
-you should not use them when defining Python formatters, breakpoint scripts and
-commands (or any other Python extension point that LLDB provides). For the
-latter you'll be passed an `SBDebugger`, `SBTarget`, `SBProcess`, `SBThread` or
-`SBFrame` instance and you can use the functions from the "Equivalent" column
-to navigate between them.
-
-As a rationale for such behavior, consider that lldb can run in a multithreaded
-environment, and another thread might call the "script" command, changing the
-value out from under you.
-
-To get started with these objects and LLDB scripting, please note that almost
-all of the lldb Python objects are able to briefly describe themselves when you
-pass them to the Python print function:
-
-::
-
- (lldb) script
- Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
- >>> print(lldb.debugger)
- Debugger (instance: "debugger_1", id: 1)
- >>> print(lldb.target)
- a.out
- >>> print(lldb.process)
- SBProcess: pid = 58842, state = stopped, threads = 1, executable = a.out
- >>> print(lldb.thread)
- thread #1: tid = 0x2265ce3, 0x0000000100000334 a.out`main at t.c:2:3, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
- >>> print(lldb.frame)
- frame #0: 0x0000000100000334 a.out`main at t.c:2:3
-
-
-Running a python script when a breakpoint gets hit
---------------------------------------------------
-
-One very powerful use of the lldb Python API is to have a python script run
-when a breakpoint gets hit. Adding python scripts to breakpoints provides a way
-to create complex breakpoint conditions and also allows for smart logging and
-data gathering.
-
-When your process hits a breakpoint to which you have attached some python
-code, the code is executed as the body of a function which takes three
-arguments:
-
-::
-
- def breakpoint_function_wrapper(frame, bp_loc, internal_dict):
- # Your code goes here
-
-or:
-
-::
-
- def breakpoint_function_wrapper(frame, bp_loc, extra_args, internal_dict):
- # Your code goes here
-
-
-+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| Argument | Type | Description |
-+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| ``frame`` | `lldb.SBFrame` | The current stack frame where the breakpoint got hit. |
-| | | The object will always be valid. |
-| | | This ``frame`` argument might *not* match the currently selected stack frame found in the `lldb` module global variable ``lldb.frame``. |
-+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| ``bp_loc`` | `lldb.SBBreakpointLocation` | The breakpoint location that just got hit. Breakpoints are represented by `lldb.SBBreakpoint` |
-| | | objects. These breakpoint objects can have one or more locations. These locations |
-| | | are represented by `lldb.SBBreakpointLocation` objects. |
-+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| ``extra_args`` | `lldb.SBStructuredData` | ``Optional`` If your breakpoint callback function takes this extra parameter, then when the callback gets added to a breakpoint, its |
-| | | contents can parametrize this use of the callback. For instance, instead of writing a callback that stops when the caller is "Foo", |
-| | | you could take the function name from a field in the ``extra_args``, making the callback more general. The ``-k`` and ``-v`` options |
-| | | to ``breakpoint command add`` will be passed as a Dictionary in the ``extra_args`` parameter, or you can provide it with the SB API's. |
-+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-| ``internal_dict`` | ``dict`` | The python session dictionary as a standard python dictionary object. |
-+-------------------+-------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
-
-Optionally, a Python breakpoint command can return a value. Returning False
-tells LLDB that you do not want to stop at the breakpoint. Any other return
-value (including None or leaving out the return statement altogether) is akin
-to telling LLDB to actually stop at the breakpoint. This can be useful in
-situations where a breakpoint only needs to stop the process when certain
-conditions are met, and you do not want to inspect the program state manually
-at every stop and then continue.
-
-An example will show how simple it is to write some python code and attach it
-to a breakpoint. The following example will allow you to track the order in
-which the functions in a given shared library are first executed during one run
-of your program. This is a simple method to gather an order file which can be
-used to optimize function placement within a binary for execution locality.
-
-We do this by setting a regular expression breakpoint that will match every
-function in the shared library. The regular expression '.' will match any
-string that has at least one character in it, so we will use that. This will
-result in one lldb.SBBreakpoint object that contains an
-lldb.SBBreakpointLocation object for each function. As the breakpoint gets hit,
-we use a counter to track the order in which the function at this particular
-breakpoint location got hit. Since our code is passed the location that was
-hit, we can get the name of the function from the location, disable the
-location so we won't count this function again; then log some info and continue
-the process.
-
-Note we also have to initialize our counter, which we do with the simple
-one-line version of the script command.
-
-Here is the code:
-
-::
-
- (lldb) breakpoint set --func-regex=. --shlib=libfoo.dylib
- Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
- (lldb) script counter = 0
- (lldb) breakpoint command add --script-type python 1
- Enter your Python command(s). Type 'DONE' to end.
- > # Increment our counter. Since we are in a function, this must be a global python variable
- > global counter
- > counter += 1
- > # Get the name of the function
- > name = frame.GetFunctionName()
- > # Print the order and the function name
- > print('[%i] %s' % (counter, name))
- > # Disable the current breakpoint location so it doesn't get hit again
- > bp_loc.SetEnabled(False)
- > # No need to stop here
- > return False
- > DONE
-
-The breakpoint command add command above attaches a python script to breakpoint 1. To remove the breakpoint command:
-
-::
-
- (lldb) breakpoint command delete 1
-
-
-Using the python api's to create custom breakpoints
----------------------------------------------------
-
-
-Another use of the Python API's in lldb is to create a custom breakpoint
-resolver. This facility was added in r342259.
-
-It allows you to provide the algorithm which will be used in the breakpoint's
-search of the space of the code in a given Target to determine where to set the
-breakpoint locations - the actual places where the breakpoint will trigger. To
-understand how this works you need to know a little about how lldb handles
-breakpoints.
-
-In lldb, a breakpoint is composed of three parts: the Searcher, the Resolver,
-and the Stop Options. The Searcher and Resolver cooperate to determine how
-breakpoint locations are set and differ between each breakpoint type. Stop
-options determine what happens when a location triggers and includes the
-commands, conditions, ignore counts, etc. Stop options are common between all
-breakpoint types, so for our purposes only the Searcher and Resolver are
-relevant.
-
-The Searcher's job is to traverse in a structured way the code in the current
-target. It proceeds from the Target, to search all the Modules in the Target,
-in each Module it can recurse into the Compile Units in that module, and within
-each Compile Unit it can recurse over the Functions it contains.
-
-The Searcher can be provided with a SearchFilter that it will use to restrict
-this search. For instance, if the SearchFilter specifies a list of Modules, the
-Searcher will not recurse into Modules that aren't on the list. When you pass
-the -s modulename flag to break set you are creating a Module-based search
-filter. When you pass -f filename.c to break set -n you are creating a file
-based search filter. If neither of these is specified, the breakpoint will have
-a no-op search filter, so all parts of the program are searched and all
-locations accepted.
-
-The Resolver has two functions. The most important one is the callback it
-provides. This will get called at the appropriate time in the course of the
-search. The callback is where the job of adding locations to the breakpoint
-gets done.
-
-The other function is specifying to the Searcher at what depth in the above
-described recursion it wants to be called. Setting a search depth also provides
-a stop for the recursion. For instance, if you request a Module depth search,
-then the callback will be called for each Module as it gets added to the
-Target, but the searcher will not recurse into the Compile Units in the module.
-
-One other slight subtlety is that the depth at which you get called back is not
-necessarily the depth at which the SearchFilter is specified. For instance,
-if you are doing symbol searches, it is convenient to use the Module depth for
-the search, since symbols are stored in the module. But the SearchFilter might
-specify some subset of CompileUnits, so not all the symbols you might find in
-each module will pass the search. You don't need to handle this situation
-yourself, since SBBreakpoint::AddLocation will only add locations that pass the
-Search Filter. This API returns an SBError to inform you whether your location
-was added.
-
-When the...
[truncated]
``````````
</details>
https://github.com/llvm/llvm-project/pull/158331
More information about the lldb-commits
mailing list