Author: jimingham Date: 2024-03-25T16:06:51-07:00 New Revision: b6dfaf4c291ee186481f6c1dcab03874d931c307
URL: https://github.com/llvm/llvm-project/commit/b6dfaf4c291ee186481f6c1dcab03874d931c307 DIFF: https://github.com/llvm/llvm-project/commit/b6dfaf4c291ee186481f6c1dcab03874d931c307.diff LOG: Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (#86593) This has been available for years now, so it should be safe to always use it. Added: Modified: lldb/docs/use/python-reference.rst Removed: ################################################################################ diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst index e5195a2471d9af..795e38fab3794b 100644 --- a/lldb/docs/use/python-reference.rst +++ b/lldb/docs/use/python-reference.rst @@ -491,14 +491,17 @@ which will work like all the natively defined lldb commands. This provides a very flexible and easy way to extend LLDB to meet your debugging requirements. To write a python function that implements a new LLDB command define the -function to take four arguments as follows: +function to take five arguments as follows: :: - def command_function(debugger, command, result, internal_dict): + def command_function(debugger, command, exe_ctx, result, internal_dict): # Your code goes here -Optionally, you can also provide a Python docstring, and LLDB will use it when providing help for your command, as in: +The meaning of the arguments is given in the table below. + +If you provide a Python docstring in your command function LLDB will use it +when providing "long help" for your command, as in: :: @@ -506,19 +509,24 @@ Optionally, you can also provide a Python docstring, and LLDB will use it when p """This command takes a lot of options and does many fancy things""" # Your code goes here -Since lldb 3.5.2, LLDB Python commands can also take an SBExecutionContext as an -argument. This is useful in cases where the command's notion of where to act is -independent of the currently-selected entities in the debugger. +though providing help can also be done programmatically (see below). -This feature is enabled if the command-implementing function can be recognized -as taking 5 arguments, or a variable number of arguments, and it alters the -signature as such: +Prior to lldb 3.5.2 (April 2015), LLDB Python command definitions didn't take the SBExecutionContext +argument. So you may still see commands where the command definition is: :: - def command_function(debugger, command, exe_ctx, result, internal_dict): + def command_function(debugger, command, result, internal_dict): # Your code goes here +Using this form is strongly discouraged because it can only operate on the "currently selected" +target, process, thread, frame. The command will behave as expected when run +directly on the command line. But if the command is used in a stop-hook, breakpoint +callback, etc. where the response to the callback determines whether we will select +this or that particular process/frame/thread, the global "currently selected" +entity is not necessarily the one the callback is meant to handle. In that case, this +command definition form can't do the right thing. + +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ | Argument | Type | Description | +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+ _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
