[Lldb-commits] [lldb] b6dfaf4 - Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (#86593)

[via lldb-commits]

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                                                                                                                      |
 +-------------------+--------------------------------+----------------------------------------------------------------------------------------------------------------------------------+