[PATCH] Add support for `user-defined` python commands

[PATCH] Add support for `user-defined` python commands

[Scott J. Goldman]

For codebases with a large pre-existing set of legacy gdb macros, it's
nice to be able to use `help user-defined`, to refresh your memory wrt
to existing macros. Currently, python gdb commands can't put themselves
under the `user-defined` category. This patch aims to rectify that.
---
 gdb/ChangeLog       |    6 ++++++
 gdb/doc/ChangeLog   |    4 ++++
 gdb/doc/gdb.texinfo |   10 +++++++++-
 gdb/python/py-cmd.c |    6 ++++--
 4 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/gdb/ChangeLog b/gdb/ChangeLog
index 3103398..9f9fade 100644
--- a/gdb/ChangeLog
+++ b/gdb/ChangeLog
@@ -1,3 +1,9 @@
+2011-05-18  Scott J. Goldman <scottjg@vmware.com>
+
+	Add support to define python commands as 'user-defined'
+	* py-cmd.c (gdbpy_initialize_commands): support COMMAND_USER type
+	(cmdpy_init): support class_user
+
 2011-05-18  Tom Tromey  <tromey@redhat.com>
 
 	* dwarf2read.c (dwarf2_add_field): Constify.
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index 0469b0a..d21c9ef 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,7 @@
+2011-05-18 Scott J. Goldman <scottjg@vmware.com>
+
+	* gdb.texinfo: Document COMMAND_USER python command type
+
 2011-05-17  Pedro Alves  <pedro@codesourcery.com>
 
 	* gdb.texinfo (Remote Protocol) <Overview>: Mention vCont is
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 584a520..8b15ed2 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -21124,7 +21124,7 @@ to handle this case.  Example:
 >class HelloWorld (gdb.Command):
 >  """Greet the whole world."""
 >  def __init__ (self):
->    super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_OBSCURE)
+>    super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER)
 >  def invoke (self, args, from_tty):
 >    argv = gdb.string_to_argv (args)
 >    if len (argv) != 0:
@@ -22450,6 +22450,14 @@ The command is only useful to @value{GDBN} maintainers.  The
 @code{maintenance} and @code{flushregs} commands are in this category.
 Type @kbd{help internals} at the @value{GDBN} prompt to see a list of
 commands in this category.
+
+@findex COMMAND_USER
+@findex gdb.COMMAND_USER
+@item COMMAND_USER
+The command is considered user-defined.  Old-style @value{GDBN}
+command macros always fall under this category.
+Type @kbd{help user-defined} at the @value{GDBN} prompt to see a list
+of commands in this category.
 @end table
 
 A new command can use a predefined completion function, either by
diff --git a/gdb/python/py-cmd.c b/gdb/python/py-cmd.c
index c0e3291..8b8e384 100644
--- a/gdb/python/py-cmd.c
+++ b/gdb/python/py-cmd.c
@@ -436,7 +436,7 @@ cmdpy_init (PyObject *self, PyObject *args, PyObject *kw)
       && cmdtype != class_files && cmdtype != class_support
       && cmdtype != class_info && cmdtype != class_breakpoint
       && cmdtype != class_trace && cmdtype != class_obscure
-      && cmdtype != class_maintenance)
+      && cmdtype != class_maintenance && cmdtype != class_user)
     {
       PyErr_Format (PyExc_RuntimeError, _("Invalid command class argument."));
       return -1;
@@ -576,7 +576,9 @@ gdbpy_initialize_commands (void)
       || PyModule_AddIntConstant (gdb_module, "COMMAND_OBSCURE",
 				  class_obscure) < 0
       || PyModule_AddIntConstant (gdb_module, "COMMAND_MAINTENANCE",
-				  class_maintenance) < 0)
+				  class_maintenance) < 0
+      || PyModule_AddIntConstant (gdb_module, "COMMAND_USER", class_user) < 0)
+
     return;
 
   for (i = 0; i < N_COMPLETERS; ++i)
-- 
1.7.4.1

Re: [PATCH] Add support for `user-defined` python commands

[Doug Evans]

On Wed, May 18, 2011 at 4:26 PM, Scott J. Goldman <scottjg@vmware.com> wrote:
> For codebases with a large pre-existing set of legacy gdb macros, it's
> nice to be able to use `help user-defined`, to refresh your memory wrt
> to existing macros. Currently, python gdb commands can't put themselves
> under the `user-defined` category. This patch aims to rectify that.

I think there's a problem to solve here (finding one's way in the
myriad of available commands), but I'm not sure this is the way to go.
[Maybe it is though.]

What does "help user-defined" buy?
It *does* buy a way to see a list of a particular set of available
commands, but the list isn't categorized along functional lines (like
managing breakpoints or examining data).  What the user will get is a
list of a random set of commands.

For completeness sake, prefix commands provide another way of
categorizing commands - one *could* put a set of new commands in a
prefix command, and then "help <prefix>" would list all of the
commands.  But it doesn't always fit what one wants to do.  E.g. it
wouldn't list anything added as a set/show or info command (python
commands mightn't be able to be implemented as set/show/info today, I
forget, but it seems like a useful thing to at least not preclude).

Question: What if we had the ability to add new command classes?
And what if "help <foo>"  could print all the commands in that command class?
Then one could add a whole suite of python commands to deal with foo
(which needn't necessarily match any existing command class), and
"help foo" would list them all.

Just a thought.

RE: [PATCH] Add support for `user-defined` python commands

[Scott Goldman]

Hi Doug. 

> I think there's a problem to solve here (finding one's way in the
> myriad of available commands), but I'm not sure this is the way to go.
> [Maybe it is though.]

I think you made some interesting points. From what I make of your email, the question you've proposed is something like "should we even have user-defined category at all?". I'm sure there will be a lot of opinions on this. UI debates are tougher for me than technical ones :)

I can see the discussion branching in two directions:
1) Yes, we should have a user-defined category, but we also want to either: subdivide the user-defined commands into prefix categories, or have additional custom categories.

In this case, I think it follows that my patch should be applied pretty much as-is (pending any necessary refactoring as requested). If legacy gdb macros can enter the `user-defined` category, I don't see why new python gdb macros should be excluded. Further patches can add the support for additional custom categories, and this patch would be the first step: allowing python macros to be classified as `user-defined` at all.

2) No, we should not have a user-defined category, and it should be replaced by custom categories or prefix categories.

In this case, my patch is pretty irrelevant. 


At work, the macros I deal with are intended for kernel debugging on ESXi. I was in the process of introducing our first python macro, but realized that all of our macros are indexed in `help user-defined` but, for whatever reason, the gdb python api has excluded that as one of the possible categories. My interim solution was to simply wrap some python gdb functions in legacy gdb macros (yuck!). 

Personally, though I would prefer #1, and here's why:

> Question: What if we had the ability to add new command classes?
> And what if "help <foo>"  could print all the commands in that command class?
> Then one could add a whole suite of python commands to deal with foo
> (which needn't necessarily match any existing command class), and
> "help foo" would list them all.

This is a nice idea, and we actually do have enough macros that categorizing them would probably be smart. That being said, this doesn't necessarily preclude having a catch-all `user-defined` category (or at least, the ability to list all user-defined macros). I imagine (hypothetically) trying to find a macro and not being able to determine which obvious category I should list. 

> (python commands mightn't be able to be implemented as set/show/info
> today, I forget, but it seems like a useful thing to at least not preclude).

At least `info` falls under the `status` category, which a python command can currently declare itself under.

-sjg

________________________________________
From: Doug Evans [dje@google.com]
Sent: Wednesday, May 18, 2011 6:58 PM
To: Scott Goldman
Cc: gdb-patches@sourceware.org
Subject: Re: [PATCH] Add support for `user-defined` python commands

On Wed, May 18, 2011 at 4:26 PM, Scott J. Goldman <scottjg@vmware.com> wrote:
> For codebases with a large pre-existing set of legacy gdb macros, it's
> nice to be able to use `help user-defined`, to refresh your memory wrt
> to existing macros. Currently, python gdb commands can't put themselves
> under the `user-defined` category. This patch aims to rectify that.

I think there's a problem to solve here (finding one's way in the
myriad of available commands), but I'm not sure this is the way to go.
[Maybe it is though.]

What does "help user-defined" buy?
It *does* buy a way to see a list of a particular set of available
commands, but the list isn't categorized along functional lines (like
managing breakpoints or examining data).  What the user will get is a
list of a random set of commands.

For completeness sake, prefix commands provide another way of
categorizing commands - one *could* put a set of new commands in a
prefix command, and then "help <prefix>" would list all of the
commands.  But it doesn't always fit what one wants to do.  E.g. it
wouldn't list anything added as a set/show or info command (python
commands mightn't be able to be implemented as set/show/info today, I
forget, but it seems like a useful thing to at least not preclude).

Question: What if we had the ability to add new command classes?
And what if "help <foo>"  could print all the commands in that command class?
Then one could add a whole suite of python commands to deal with foo
(which needn't necessarily match any existing command class), and
"help foo" would list them all.

Just a thought.

Re: [PATCH] Add support for `user-defined` python commands

[Doug Evans]

On Wed, May 18, 2011 at 7:54 PM, Scott Goldman <scottjg@vmware.com> wrote:
> Hi Doug.
>
>> I think there's a problem to solve here (finding one's way in the
>> myriad of available commands), but I'm not sure this is the way to go.
>> [Maybe it is though.]
>
> I think you made some interesting points. From what I make of your email, the question you've proposed is something like "should we even have user-defined category at all?". I'm sure there will be a lot of opinions on this. UI debates are tougher for me than technical ones :)
>
> I can see the discussion branching in two directions:
> 1) Yes, we should have a user-defined category, but we also want to either: subdivide the user-defined commands into prefix categories, or have additional custom categories.
>
> In this case, I think it follows that my patch should be applied pretty much as-is (pending any necessary refactoring as requested). If legacy gdb macros can enter the `user-defined` category, I don't see why new python gdb macros should be excluded. Further patches can add the support for additional custom categories, and this patch would be the first step: allowing python macros to be classified as `user-defined` at all.
>
> 2) No, we should not have a user-defined category, and it should be replaced by custom categories or prefix categories.
>
> In this case, my patch is pretty irrelevant.

I'm not sure it's either/or.
One *could* have both python "user-defined" commands and the ability
to add new command classes.
I don't think I would ever use "user-defined" except as a throwaway
for when I couldn't think of something better. :-)
But your patch could *still* be useful enough to add.

I think the absence of user-defined python commands is either an
oversight or just left out pending an actual need.
I only bring this up because after reading your patch, it made me
wonder if there isn't a more general problem here.
[At a former employer I think we did add user-specifiable command
classes - we added a lot of commands: gdb macros, lots of new
simulator commands, and commands from dlopen'd libraries.  The need
for organizing them was clear.]

Re: [PATCH] Add support for `user-defined` python commands

[Tom Tromey]

>>>>> "Scott" == Scott J Goldman <scottjg@vmware.com> writes:

Scott> For codebases with a large pre-existing set of legacy gdb macros, it's
Scott> nice to be able to use `help user-defined`, to refresh your memory wrt
Scott> to existing macros. Currently, python gdb commands can't put themselves
Scott> under the `user-defined` category. This patch aims to rectify that.

Thanks.

The code bits look ok.  I could not tell from the ensuing thread whether
Doug objected to this patch or not.  So, my approval is conditional on
him not objecting.

Do you have a copyright assignment in place?  This patch probably
requires one.  If not, let me know, and I can get you started on that.

This needs a doc review.

Tom

RE: [PATCH] Add support for `user-defined` python commands

[Scott Goldman]

Hi Tom.

> The code bits look ok.  I could not tell from the ensuing thread
> whether Doug objected to this patch or not.  So, my approval 
> is conditional on him not objecting.

My understanding of the discussion is that Doug was suggesting that we might want to support custom categories as a follow-on change (I don't think it was an objection to this patch).

> Do you have a copyright assignment in place?  This patch probably
> requires one.  If not, let me know, and I can get you started on that.

I do not, please forward me the documents. I just have to run them by the legal dept. 

> This needs a doc review.

That's not a separate mailing list, is it?

Thanks,
-sjg

Re: [PATCH] Add support for `user-defined` python commands

[Tom Tromey]

Tom> This needs a doc review.

Scott> That's not a separate mailing list, is it?

Nope, it will happen here.

I will send you the paperwork stuff off-list.

Tom

Re: [PATCH] Add support for `user-defined` python commands

[Doug Evans]

On Thu, May 19, 2011 at 12:27 PM, Scott Goldman <scottjg@vmware.com> wrote:
> My understanding of the discussion is that Doug was suggesting that we might want to support custom categories as a follow-on change (I don't think it was an objection to this patch).

Correct.
No objection to the patch (or at least the concept :-) I didn't review
it with a fine tooth comb for checkinability).