[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
https://github.com/jimingham closed https://github.com/llvm/llvm-project/pull/86593 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
https://github.com/jimingham updated https://github.com/llvm/llvm-project/pull/86593 >From 1886d705aee10cf608b4c452bea6ea3e47c4b25d Mon Sep 17 00:00:00 2001 From: Jim Ingham Date: Mon, 25 Mar 2024 15:31:50 -0700 Subject: [PATCH 1/2] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs. This has been available for years now, so it should be safe to always use it. --- lldb/docs/use/python-reference.rst | 30 +++--- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst index e5195a2471d9af..bafbe812383d69 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, 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 +This form is deprecated 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 | +---++--+ >From 0a246c1ec13986d5fb819258b2c2ae2b93ea8508 Mon Sep 17 00:00:00 2001 From: Jim Ingham Date: Mon, 25 Mar 2024 16:06:00 -0700 Subject: [PATCH 2/2] Address review comments; give a date for 3.5.2 not just a version. --- lldb/docs/use/python-reference.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst index bafbe812383d69..795e38fab3794b 100644 --- a/lldb/docs/use/python-reference.rst +++ b/lldb/docs/use/python-reference.rst @@ -511,15 +511,15 @@ when providing "long help" for your command, as in: though providing help can also be done programmatically (see below). -Prior to lldb 3.5.2, LLDB Python command definitions didn't take the SBExecutionContext +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, result, internal_dict): # Your code goes here -This form is deprecated because it can only operate on the "currently selected" +Using this form is strongly discouraged because it can only operate on the "currently
[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
@@ -491,34 +491,42 @@ 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: :: def command_function(debugger, command, result, internal_dict): """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, 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 +This form is deprecated 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. bulbazord wrote: You wrote that it's deprecated at the beginning of the paragraph, but LLDB never removes functions nor removes working implementations of deprecated functions. I would recommend wording the conclusion more strongly, e.g. `In that case, this command definition form can't do the right thing and is therefore highly discouraged from use.` https://github.com/llvm/llvm-project/pull/86593 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
@@ -491,34 +491,42 @@ 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: :: def command_function(debugger, command, result, internal_dict): """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, 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): + bulbazord wrote: nit: Spurious whitespace https://github.com/llvm/llvm-project/pull/86593 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
https://github.com/bulbazord approved this pull request. LGTM https://github.com/llvm/llvm-project/pull/86593 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
https://github.com/bulbazord edited https://github.com/llvm/llvm-project/pull/86593 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
https://github.com/chelcassanova approved this pull request. https://github.com/llvm/llvm-project/pull/86593 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
llvmbot wrote: @llvm/pr-subscribers-lldb Author: None (jimingham) Changes This has been available for years now, so it should be safe to always use it. --- Full diff: https://github.com/llvm/llvm-project/pull/86593.diff 1 Files Affected: - (modified) lldb/docs/use/python-reference.rst (+19-11) ``diff diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst index e5195a2471d9af..bafbe812383d69 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, 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 +This form is deprecated 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 | +---++--+ `` https://github.com/llvm/llvm-project/pull/86593 ___ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
[Lldb-commits] [lldb] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs (PR #86593)
https://github.com/jimingham created https://github.com/llvm/llvm-project/pull/86593 This has been available for years now, so it should be safe to always use it. >From 1886d705aee10cf608b4c452bea6ea3e47c4b25d Mon Sep 17 00:00:00 2001 From: Jim Ingham Date: Mon, 25 Mar 2024 15:31:50 -0700 Subject: [PATCH] Make the correct (5 argument) form of the command definition be the primary one suggested in the docs. This has been available for years now, so it should be safe to always use it. --- lldb/docs/use/python-reference.rst | 30 +++--- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/lldb/docs/use/python-reference.rst b/lldb/docs/use/python-reference.rst index e5195a2471d9af..bafbe812383d69 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, 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 +This form is deprecated 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
