CLI and GDB/MI documentation patch

CLI and GDB/MI documentation patch

[Bob Rossi]

[-- Attachment #1: Type: text/plain, Size: 176 bytes --]

Hi all,

I hope this looks correct. Please let me know otherwise. I think it's 
an improvement over what is there now, and could save others valuable
research time.

Bob Rossi

[-- Attachment #2: gdb.texinfo.diff --]
[-- Type: text/plain, Size: 3882 bytes --]

Index: ChangeLog
===================================================================
RCS file: /cvs/src/src/gdb/doc/ChangeLog,v
retrieving revision 1.575
diff -u -r1.575 ChangeLog
--- ChangeLog	5 May 2006 22:48:14 -0000	1.575
+++ ChangeLog	12 May 2006 01:15:02 -0000
@@ -1,3 +1,8 @@
+2006-05-11  Bob Rossi  <bob_rossi@cox.net>
+
+	* gdb.texinfo (GDB/MI Compatibility with CLI): Document how CLI
+	commands and GDB/MI interface.
+
 2006-05-05  Jim Blandy  <jimb@codesourcery.com>
 
 	* gdb.texinfo (General Query Packets): Document conventions for
Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.328
diff -u -r1.328 gdb.texinfo
--- gdb.texinfo	5 May 2006 22:48:14 -0000	1.328
+++ gdb.texinfo	12 May 2006 01:15:05 -0000
@@ -17377,16 +17377,43 @@
 
 @cindex compatibility, @sc{gdb/mi} and CLI
 @cindex @sc{gdb/mi}, compatibility with CLI
-To help users familiar with @value{GDBN}'s existing CLI interface, @sc{gdb/mi}
-accepts existing CLI commands.  As specified by the syntax, such
-commands can be directly entered into the @sc{gdb/mi} interface and @value{GDBN} will
-respond.
-
-This mechanism is provided as an aid to developers of @sc{gdb/mi}
-clients and not as a reliable interface into the CLI.  Since the command
-is being interpreteted in an environment that assumes @sc{gdb/mi}
-behaviour, the exact output of such commands is likely to end up being
-an un-supported hybrid of @sc{gdb/mi} and CLI output.
+Initially, the @sc{gdb/mi} interface accepted CLI commands to help users
+familiar with @value{GDBN}'s existing CLI interface.  As specified by the 
+syntax, such commands can be directly entered into the @sc{gdb/mi} interface 
+and @value{GDBN} will respond.
+
+This mechanism was originally provided as an aid to developers of @sc{gdb/mi}
+clients and not as a reliable interface into the CLI. The output of these
+commands were likely to end up being an un-supported hybrid of @sc{gdb/mi} 
+and CLI output.  This was the case until some time in the @sc{gdb/mi} version
+2 protocol.
+
+Somewhere in the @sc{gdb/mi} version 2 protocol, the command 
+@code{-interpreter-exec} was added to @value{GDBN}.  This provided the 
+capability to allow @sc{gdb/mi} clients to execute CLI commands in a way 
+that would provide supported @sc{gdb/mi} output.  Since this feature was 
+so useful, and @sc{gdb/mi} clients historically passed CLI commands directly 
+into the @sc{gdb/mi} interface, @value{GDBN} was modified to accept CLI 
+commands directly into the @sc{gdb/mi} interpreter.  @value{GDBN} takes
+the CLI command, and internally uses the @code{-interpreter-exec} @sc{gdb/mi}
+command to ensure that the CLI command the user passed in has supported 
+@sc{gdb/mi} output.
+
+So, entering CLI commands directly into the @sc{gdb/mi} interpreter is now
+essentially the same as using the @sc{gdb/mi} @code{-interpreter-exec} 
+command.  There may be a small difference in the @sc{gdb/mi} output between 
+directly typing the CLI command into the @sc{gdb/mi} interpreter or by using 
+the @code{-interpreter-exec} command, however, both ways should provide 
+valid @sc{gdb/mi} output.
+
+One current major difference between entering a CLI command directly into
+the @sc{gdb/mi} interpreter and entering the corresponding @sc{gdb/mi} 
+command into the interpreter is that the CLI command will not have the 
+asynchronous output that the @sc{gdb/mi} command will have. For instance,
+typing @code{run} as a CLI command, you will not get the @code{*stopped}
+response that @sc{gdb/mi} will provide if you enter the @code{-exec-run}
+command.  This is currently considered a limitation of @sc{gdb/mi} that 
+will be fixed in future versions of @value{GDBN}.
 
 @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 @node GDB/MI Output Records

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Thu, 11 May 2006 21:17:30 -0400
> From: Bob Rossi <bob_rossi@cox.net>
> 
> I hope this looks correct. Please let me know otherwise. I think it's 
> an improvement over what is there now, and could save others valuable
> research time.

Sorry, I don't understand what you are trying to say here, exactly.
Explaining why we did something in the past does not belong in the
manual (except maybe in a footnote, if it is _very_ important to
mention history).

Perhaps I wasn't following the thread closely enough, so I missed
something important.  Can you state what information is missing from
the current text in this section?  You say above that the changes
``could save others valuable research time''--what did you need to
research, and why, and what did you find that wasn't described in the
manual?

Re: CLI and GDB/MI documentation patch

[Vladimir Prus]

Eli Zaretskii wrote:

>> Date: Thu, 11 May 2006 21:17:30 -0400
>> From: Bob Rossi <bob_rossi@cox.net>
>> 
>> I hope this looks correct. Please let me know otherwise. I think it's
>> an improvement over what is there now, and could save others valuable
>> research time.
> 
> Sorry, I don't understand what you are trying to say here, exactly.
> Explaining why we did something in the past does not belong in the
> manual (except maybe in a footnote, if it is _very_ important to
> mention history).
> 
> Perhaps I wasn't following the thread closely enough, so I missed
> something important.  Can you state what information is missing from
> the current text in this section?  You say above that the changes
> ``could save others valuable research time''--what did you need to
> research, and why, and what did you find that wasn't described in the
> manual?

I'd agree with Eli that the proposed text sounds a bit like history, but it
documents some important points:

- That you can type CLI commands into MI, and this is not longer considered
  to work just by accident
- That typing CLI command has the same effect as -interpreter-exec console
- That CLI command don't produce async notifications

Those points are important to have documented, IMO.

- Volodya

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> From:  Vladimir Prus <ghost@cs.msu.su>
> Date:  Fri, 12 May 2006 12:13:24 +0400
> 
> I'd agree with Eli that the proposed text sounds a bit like history, but it
> documents some important points:
> 
> - That you can type CLI commands into MI, and this is not longer considered
>   to work just by accident
> - That typing CLI command has the same effect as -interpreter-exec console
> - That CLI command don't produce async notifications
> 
> Those points are important to have documented, IMO.

I agree.

Bob, are there any other points you wanted to make?  If so, please
tell what they are.

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Fri, May 12, 2006 at 02:30:32PM +0300, Eli Zaretskii wrote:
> > From:  Vladimir Prus <ghost@cs.msu.su>
> > Date:  Fri, 12 May 2006 12:13:24 +0400
> > 
> > I'd agree with Eli that the proposed text sounds a bit like history, but it
> > documents some important points:
> > 
> > - That you can type CLI commands into MI, and this is not longer considered
> >   to work just by accident
> > - That typing CLI command has the same effect as -interpreter-exec console
> > - That CLI command don't produce async notifications
> > 
> > Those points are important to have documented, IMO.
> 
> I agree.
> 
> Bob, are there any other points you wanted to make?  If so, please
> tell what they are.

haha. I am the worst at writing documentation, but I try anyways!

I think it's important to mention that mi2 supports receiving CLI 
commands directly into the interpreter, but only after a certain
point in it's development. Early on it wasn't supported, so the 
only safe way of passing CLI commands directly is to use 
-interpreter-exec.

> > - That you can type CLI commands into MI, and this is not longer considered
> >   to work just by accident
This was never considered to be used be the FE before.

> > - That CLI command don't produce async notifications
I think it's important to mention that this will most likely change in
the future and that currently this is a lack of a feature.

Thanks,
Bob Rossi

Re: CLI and GDB/MI documentation patch

[Daniel Jacobowitz]

On Fri, May 12, 2006 at 10:53:43AM +0300, Eli Zaretskii wrote:
> Sorry, I don't understand what you are trying to say here, exactly.
> Explaining why we did something in the past does not belong in the
> manual (except maybe in a footnote, if it is _very_ important to
> mention history).

While I agree about "why", I think "what" we did in the past does
belong in the manual in some cases.  Not so much for the CLI, which is
covered by most of the manual, but for the remote protocol and GDB/MI
where most everyone interested in them will be interested in supporting
multiple versions of GDB...

-- 
Daniel Jacobowitz
CodeSourcery

Re: CLI and GDB/MI documentation patch

[Daniel Jacobowitz]

On Fri, May 12, 2006 at 10:53:43AM +0300, Eli Zaretskii wrote:
> Sorry, I don't understand what you are trying to say here, exactly.
> Explaining why we did something in the past does not belong in the
> manual (except maybe in a footnote, if it is _very_ important to
> mention history).

While I agree about "why", I think "what" we did in the past does
belong in the manual in some cases.  Not so much for the CLI, which is
covered by most of the manual, but for the remote protocol and GDB/MI
where most everyone interested in them will be interested in supporting
multiple versions of GDB...

-- 
Daniel Jacobowitz
CodeSourcery

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Fri, 12 May 2006 08:49:40 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> On Fri, May 12, 2006 at 10:53:43AM +0300, Eli Zaretskii wrote:
> > Sorry, I don't understand what you are trying to say here, exactly.
> > Explaining why we did something in the past does not belong in the
> > manual (except maybe in a footnote, if it is _very_ important to
> > mention history).
> 
> While I agree about "why", I think "what" we did in the past does
> belong in the manual in some cases.  Not so much for the CLI, which is
> covered by most of the manual, but for the remote protocol and GDB/MI
> where most everyone interested in them will be interested in supporting
> multiple versions of GDB...

In general, if some external package needs to support multiple GDB
versions, their authors will need to look in the manuals of those
older versions.

In those cases where it is very important, the "what" should be in a
@footnote.

This reminds me: perhaps we should mention major incompatible changes
in NEWS, suitably marked to the effect that they break backward
compatibility.

Re: CLI and GDB/MI documentation patch

[Daniel Jacobowitz]

On Fri, May 12, 2006 at 04:53:28PM +0300, Eli Zaretskii wrote:
> In general, if some external package needs to support multiple GDB
> versions, their authors will need to look in the manuals of those
> older versions.

Is there somewhere appropriate to record this sort of change, in
more detail than would fit in NEWS, if you think that the manual is not
the place for it?  This sort of information is incredibly useful when
e.g. upgrading; there's no easy way for users to "diff" the manual.

> This reminds me: perhaps we should mention major incompatible changes
> in NEWS, suitably marked to the effect that they break backward
> compatibility.

Yes, certainly.

-- 
Daniel Jacobowitz
CodeSourcery

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Fri, May 12, 2006 at 09:58:02AM -0400, Daniel Jacobowitz wrote:
> On Fri, May 12, 2006 at 04:53:28PM +0300, Eli Zaretskii wrote:
> > In general, if some external package needs to support multiple GDB
> > versions, their authors will need to look in the manuals of those
> > older versions.
> 
> Is there somewhere appropriate to record this sort of change, in
> more detail than would fit in NEWS, if you think that the manual is not
> the place for it?  This sort of information is incredibly useful when
> e.g. upgrading; there's no easy way for users to "diff" the manual.

I propose putting in the manual all of the changes since the last
version of MI, in a new section. So this way, users can easily
understand what changed. If they are upgrading from an older version,
they can look at that manual.

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Fri, 12 May 2006 10:03:14 -0400
> From: Bob Rossi <bob_rossi@cox.net>
> 
> I propose putting in the manual all of the changes since the last
> version of MI, in a new section.

The manual is too colossal for this.  This information should be
easily found.  So I think NEWS is where we should put it.

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Fri, 12 May 2006 09:58:02 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> On Fri, May 12, 2006 at 04:53:28PM +0300, Eli Zaretskii wrote:
> > In general, if some external package needs to support multiple GDB
> > versions, their authors will need to look in the manuals of those
> > older versions.
> 
> Is there somewhere appropriate to record this sort of change, in
> more detail than would fit in NEWS, if you think that the manual is not
> the place for it?

NEWS is the best place, IMO.  It can list the incompatible changes,
and point to the sections in the manual which describe the new
behavior in detail.  If you think this will not be good enough, please
tell why.

As a data point, the Emacs NEWS has special sections for incompatible
changes.  Emacs is a much larger package than GDB, and with much
slower release rate, the amount of incompatible changes is also much
larger.  And yet this scheme works well for many years, and users came
to depend on it and demand that any incompatible changes be mentioned.

> This sort of information is incredibly useful when e.g. upgrading;
> there's no easy way for users to "diff" the manual.

Sure; that's the main purpose of having NEWS in the first place.

Re: CLI and GDB/MI documentation patch

[Daniel Jacobowitz]

On Fri, May 12, 2006 at 09:32:26PM +0300, Eli Zaretskii wrote:
> NEWS is the best place, IMO.  It can list the incompatible changes,
> and point to the sections in the manual which describe the new
> behavior in detail.  If you think this will not be good enough, please
> tell why.
> 
> As a data point, the Emacs NEWS has special sections for incompatible
> changes.  Emacs is a much larger package than GDB, and with much
> slower release rate, the amount of incompatible changes is also much
> larger.  And yet this scheme works well for many years, and users came
> to depend on it and demand that any incompatible changes be mentioned.

So, for someone who must support multiple versions of GDB, they would
have to read NEWS looking for changes, find the new behavior in the
current manual, and find the old (hopefully documented) behavior in the
old manual?

Our current NEWS is basically bullet-points.  That would definitely
need a change.  OK, reasonable enough, I suppose, although it seems
awkward when we know that many of the people reading this chapter in
the manual will be interested in precisely this historical information.

Many shipping GDB frontends work on any version of GDB released in the
last several years and shipped by a large package distributor; that's a
lot of versions of GDB.  I'm not sure the two cases are readily
comparable, though I realize that Emacs LISP programs probably have
similar issues.

-- 
Daniel Jacobowitz
CodeSourcery

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Fri, 12 May 2006 14:37:23 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> So, for someone who must support multiple versions of GDB, they would
> have to read NEWS looking for changes, find the new behavior in the
> current manual, and find the old (hopefully documented) behavior in the
> old manual?

No.  I propose to have a special section devoted to incompatible
changes in the remote protocol, and another one for incompatible
changes in MI.  Thus, no searching is necessary.

As for old behavior, since the old versions of protocol/MI is already
supported by the tools whose authors are the audience of these NEWS
sections, I'd expect them to be well acquainted with the old behavior.
So I don't think they will need to look for that.

> Our current NEWS is basically bullet-points.  That would definitely
> need a change.

Yes.  We will have to subdivide into sections.

> OK, reasonable enough, I suppose, although it seems
> awkward when we know that many of the people reading this chapter in
> the manual will be interested in precisely this historical information.
> 
> Many shipping GDB frontends work on any version of GDB released in the
> last several years and shipped by a large package distributor; that's a
> lot of versions of GDB.  I'm not sure the two cases are readily
> comparable, though I realize that Emacs LISP programs probably have
> similar issues.

If you feel we should tell how to create a front end and/or a stub
that supports several versions of GDB/MI or remote protocol, that's
fine by me, but let's have sections whose focus is to provide tips to
such programmers, not to tell the history of MI or the protocol's
evolution.  That's quite a different attitude than what Bob wrote.

Re: CLI and GDB/MI documentation patch

[Daniel Jacobowitz]

On Fri, May 12, 2006 at 09:55:38PM +0300, Eli Zaretskii wrote:
> > Date: Fri, 12 May 2006 14:37:23 -0400
> > From: Daniel Jacobowitz <drow@false.org>
> > 
> > So, for someone who must support multiple versions of GDB, they would
> > have to read NEWS looking for changes, find the new behavior in the
> > current manual, and find the old (hopefully documented) behavior in the
> > old manual?
> 
> No.  I propose to have a special section devoted to incompatible
> changes in the remote protocol, and another one for incompatible
> changes in MI.  Thus, no searching is necessary.

New sections in NEWS, you mean?  I see.

> As for old behavior, since the old versions of protocol/MI is already
> supported by the tools whose authors are the audience of these NEWS
> sections, I'd expect them to be well acquainted with the old behavior.
> So I don't think they will need to look for that.

No, I can't support that assumption.  New tools, written today, are
probably written against a fairly current manual.  Then someone
approaches you and says "I'd like to use your nice IDE on our stable
enterprise platform from three years ago which has an older GDB".  The
range of supported GDBs does not only grow forwards.

> If you feel we should tell how to create a front end and/or a stub
> that supports several versions of GDB/MI or remote protocol, that's
> fine by me, but let's have sections whose focus is to provide tips to
> such programmers, not to tell the history of MI or the protocol's
> evolution.  That's quite a different attitude than what Bob wrote.

I do think that such a section would be useful.  I'm not entirely sure
about the distinction you are drawing, though.  Is it a "what" versus
"why" difference?

-- 
Daniel Jacobowitz
CodeSourcery

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

> > As for old behavior, since the old versions of protocol/MI is already
> > supported by the tools whose authors are the audience of these NEWS
> > sections, I'd expect them to be well acquainted with the old behavior.
> > So I don't think they will need to look for that.
> 
> No, I can't support that assumption.  New tools, written today, are
> probably written against a fairly current manual.  Then someone
> approaches you and says "I'd like to use your nice IDE on our stable
> enterprise platform from three years ago which has an older GDB".  The
> range of supported GDBs does not only grow forwards.

This is definatly true. I had to make CGDB work with GNAT GDB 3.14p 
cause I'm forced to use that compiler at work. That GDB is many years
old. (This was using annotate 2 however).

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Fri, 12 May 2006 15:01:52 -0400
> From: Daniel Jacobowitz <drow@false.org>
> 
> New tools, written today, are probably written against a fairly
> current manual.  Then someone approaches you and says "I'd like to
> use your nice IDE on our stable enterprise platform from three years
> ago which has an older GDB".

I don't see any practical solution for such a situation.  To cater to
it, we'd need to convert the MI and Remote Protocol parts of the
manual into a kind of a very detailed ChangeLog, where every change
gets documented (together with its precise date, since ``there are so
many snapshots in use out there'', as Bob says), but the description
of the previous behavior is never removed, for those unfortunate souls
that will need to interface to it as you describe.  Just saying
``previous versions of GDB behaved like this'' will not solve the
problem, since there's no information about when the change(s) became
effective.

> The range of supported GDBs does not only grow forwards.

In my experience, the only way to extend it backwards is to read the
sources and experiment.  That's because, as users come up with
suggestions and requests to expand and extend the manual, we only do
that for the current version; the old behavior stays undocumented.
It's impractical to ask us to document the past behavior, for every
new piece of documentation we add to the manual.

If you see any practical solution for this kind of situations, please
tell what can we reasonably do in the manual.

> > If you feel we should tell how to create a front end and/or a stub
> > that supports several versions of GDB/MI or remote protocol, that's
> > fine by me, but let's have sections whose focus is to provide tips to
> > such programmers, not to tell the history of MI or the protocol's
> > evolution.  That's quite a different attitude than what Bob wrote.
> 
> I do think that such a section would be useful.  I'm not entirely sure
> about the distinction you are drawing, though.  Is it a "what" versus
> "why" difference?

No.  When you write a Tips section, you in essence write a cookbook,
and the logic of the text (i.e. what you tell, how, and in which
order) is in accordance with that.  That is, you pick up an issue and
give tips relevant to that issue, and while at that, you also say
things like ``Note that versions of GDB older than X.YZ didn't support
the -mi-frobnicate command, so you will have to use -mi-hack as a
workaround with those versions, which has this-and-that
disadvantage.''  Then you pick up another issue, etc.

By contrast, the logic of text posted by Bob was chronological: ``In
the beginning, we did this; later we started to do that; so now you
could solve this with such-and-such methods.''  Do you see the
difference?

Re: CLI and GDB/MI documentation patch

[Daniel Jacobowitz]

On Sat, May 13, 2006 at 12:21:32PM +0300, Eli Zaretskii wrote:
> > > If you feel we should tell how to create a front end and/or a stub
> > > that supports several versions of GDB/MI or remote protocol, that's
> > > fine by me, but let's have sections whose focus is to provide tips to
> > > such programmers, not to tell the history of MI or the protocol's
> > > evolution.  That's quite a different attitude than what Bob wrote.
> > 
> > I do think that such a section would be useful.  I'm not entirely sure
> > about the distinction you are drawing, though.  Is it a "what" versus
> > "why" difference?
> 
> No.  When you write a Tips section, you in essence write a cookbook,
> and the logic of the text (i.e. what you tell, how, and in which
> order) is in accordance with that.  That is, you pick up an issue and
> give tips relevant to that issue, and while at that, you also say
> things like ``Note that versions of GDB older than X.YZ didn't support
> the -mi-frobnicate command, so you will have to use -mi-hack as a
> workaround with those versions, which has this-and-that
> disadvantage.''  Then you pick up another issue, etc.
> 
> By contrast, the logic of text posted by Bob was chronological: ``In
> the beginning, we did this; later we started to do that; so now you
> could solve this with such-and-such methods.''  Do you see the
> difference?

I think so.  Thanks.

Anyway, there is absolutely no chance that I will have time to work on
this, so from my point of view it's somewhat hypothetical.

-- 
Daniel Jacobowitz
CodeSourcery

Re: CLI and GDB/MI documentation patch

[PAUL GILLIAM]

On Fri, 2006-05-12 at 21:55 +0300, Eli Zaretskii wrote:

> If you feel we should tell how to create a front end and/or a stub
> that supports several versions of GDB/MI or remote protocol, that's
> fine by me, but let's have sections whose focus is to provide tips to
> such programmers, not to tell the history of MI or the protocol's
> evolution.  That's quite a different attitude than what Bob wrote.

Why not have a section in the internals manual: something like 
"How to (and not to) write frontends for GDB"?

-=# Paul #=-

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> From: PAUL GILLIAM <pgilliam@us.ibm.com>
> Cc: gdb-patches@sourceware.org
> Date: Fri, 12 May 2006 12:03:52 -0700
> 
> On Fri, 2006-05-12 at 21:55 +0300, Eli Zaretskii wrote:
> 
> > If you feel we should tell how to create a front end and/or a stub
> > that supports several versions of GDB/MI or remote protocol, that's
> > fine by me, but let's have sections whose focus is to provide tips to
> > such programmers, not to tell the history of MI or the protocol's
> > evolution.  That's quite a different attitude than what Bob wrote.
> 
> Why not have a section in the internals manual: something like 
> "How to (and not to) write frontends for GDB"?

That was the essence of my suggestion.  The manual in which that
section will appear is less important.

FWIW, I feel that it should be in the user manual, since gdbint
describes the GDB internals, which this issue isn't part of.  Also,
since both the remote protocol and MI are described in the user
manual, the reader interested in writing a stub or a front end will
naturally look for this stuff in the same document.

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Fri, May 12, 2006 at 10:53:43AM +0300, Eli Zaretskii wrote:
> > Date: Thu, 11 May 2006 21:17:30 -0400
> > From: Bob Rossi <bob_rossi@cox.net>
> > 
> > I hope this looks correct. Please let me know otherwise. I think it's 
> > an improvement over what is there now, and could save others valuable
> > research time.
> 
> Sorry, I don't understand what you are trying to say here, exactly.
> Explaining why we did something in the past does not belong in the
> manual (except maybe in a footnote, if it is _very_ important to
> mention history).

Well, I see your point, and you are the expert in this area. The reason
I put this in the manual is because I think it's important front end
developers know what will happen when they enter CLI commands into mi2.

Old versions of mi2 will act incorrectly, where as new versions of mi2 
will work better.

> Perhaps I wasn't following the thread closely enough, so I missed
> something important.  Can you state what information is missing from
> the current text in this section?  You say above that the changes
> ``could save others valuable research time''--what did you need to
> research, and why, and what did you find that wasn't described in the
> manual?

Well, first off, this is incorrect:

    This mechanism is provided as an aid to developers of @sc{gdb/mi}
    clients and not as a reliable interface into the CLI.

So I thought it was important to describe that it is OK to pass CLI
commands to the MI interpreter for now. However, using -interpreter-exec
is a better approach.

Also, look at Vladimir's comments. None of this information is intuitive
using the MI interface. You have to slowly figure it out.

Thanks,
Bob Rossi

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Fri, 12 May 2006 08:54:33 -0400
> From: Bob Rossi <bob_rossi@cox.net>
> Cc: gdb-patches@sources.redhat.com
> 
> Old versions of mi2 will act incorrectly, where as new versions of mi2 
> will work better.

In what release of GDB were those problems fixed?

> Well, first off, this is incorrect:
> 
>     This mechanism is provided as an aid to developers of @sc{gdb/mi}
>     clients and not as a reliable interface into the CLI.

What would you suggest to say instead?  In your patch, all you did
was add the word ``originally'':

  This mechanism was originally provided as an aid to developers of @sc{gdb/mi}
  clients and not as a reliable interface into the CLI. The output of these

But you never say what's its role _now_.

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Fri, May 12, 2006 at 04:59:46PM +0300, Eli Zaretskii wrote:
> > Date: Fri, 12 May 2006 08:54:33 -0400
> > From: Bob Rossi <bob_rossi@cox.net>
> > Cc: gdb-patches@sources.redhat.com
> > 
> > Old versions of mi2 will act incorrectly, where as new versions of mi2 
> > will work better.
> 
> In what release of GDB were those problems fixed?

I'm not sure if it helps to think of things in terms of releases in
regards to GDB/MI. Unfortunatly, many distros package a CVS release of
GDB. So, any given snapshot of GDB could have this feature or not.

However, with that said, Nick posted this:

    2005-02-20  Andrew Cagney  <cagney@gnu.org>

            * mi/mi-main.c (captured_mi_execute_command): Use
            mi_cmd_interpreter_exec.

So I believe that's the day when it started working nice. Eli, the real
problem is, mi2 is the currently supported protocol, and certain
versions of mi2 work and certain version don't, so I'm not sure this is
a historical issue.

> > Well, first off, this is incorrect:
> > 
> >     This mechanism is provided as an aid to developers of @sc{gdb/mi}
> >     clients and not as a reliable interface into the CLI.
> 
> What would you suggest to say instead?  In your patch, all you did
> was add the word ``originally'':
> 
>   This mechanism was originally provided as an aid to developers of @sc{gdb/mi}
>   clients and not as a reliable interface into the CLI. The output of these
> 
> But you never say what's its role _now_.

I thought I did, but apparently I was unclear. The next 2 paragraphs
were supposed to describe what it's role is now, I'm sorry to see it was
written so unclear.

Bob Rossi

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Fri, 12 May 2006 10:21:35 -0400
> From: Bob Rossi <bob_rossi@cox.net>
> Cc: gdb-patches@sources.redhat.com
> 
> I'm not sure if it helps to think of things in terms of releases in
> regards to GDB/MI. Unfortunatly, many distros package a CVS release of
> GDB. So, any given snapshot of GDB could have this feature or not.

People who use GDB snapshots are on their own when some feature
evolves during development.  So I'm not bothered by this.

> However, with that said, Nick posted this:
> 
>     2005-02-20  Andrew Cagney  <cagney@gnu.org>
> 
>             * mi/mi-main.c (captured_mi_execute_command): Use
>             mi_cmd_interpreter_exec.

Thanks for the reference.

> So I believe that's the day when it started working nice. Eli, the real
> problem is, mi2 is the currently supported protocol, and certain
> versions of mi2 work and certain version don't, so I'm not sure this is
> a historical issue.

It's history from the point view of someone who reads the manual with
your patches: the old behavior is already gone in the GDB version that
goes with that manual.

> I thought I did, but apparently I was unclear. The next 2 paragraphs
> were supposed to describe what it's role is now, I'm sorry to see it was
> written so unclear.

Thanks for the clarifications.  I will try to come up with some text
that adds the necessary information.

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Fri, May 12, 2006 at 09:27:21PM +0300, Eli Zaretskii wrote:
> > Date: Fri, 12 May 2006 10:21:35 -0400
> > From: Bob Rossi <bob_rossi@cox.net>
> > Cc: gdb-patches@sources.redhat.com
> > 
> > I'm not sure if it helps to think of things in terms of releases in
> > regards to GDB/MI. Unfortunatly, many distros package a CVS release of
> > GDB. So, any given snapshot of GDB could have this feature or not.
> 
> People who use GDB snapshots are on their own when some feature
> evolves during development.  So I'm not bothered by this.

Please please don't say this. It's just not a practical statement to
make. Many of the distrobutions use CVS snapshots.

> > However, with that said, Nick posted this:
> > 
> >     2005-02-20  Andrew Cagney  <cagney@gnu.org>
> > 
> >             * mi/mi-main.c (captured_mi_execute_command): Use
> >             mi_cmd_interpreter_exec.
> 
> Thanks for the reference.
> 
> > So I believe that's the day when it started working nice. Eli, the real
> > problem is, mi2 is the currently supported protocol, and certain
> > versions of mi2 work and certain version don't, so I'm not sure this is
> > a historical issue.
> 
> It's history from the point view of someone who reads the manual with
> your patches: the old behavior is already gone in the GDB version that
> goes with that manual.
> 
> > I thought I did, but apparently I was unclear. The next 2 paragraphs
> > were supposed to describe what it's role is now, I'm sorry to see it was
> > written so unclear.
> 
> Thanks for the clarifications.  I will try to come up with some text
> that adds the necessary information.

Thanks Eli!

Bob Rossi

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Fri, 12 May 2006 15:16:40 -0400
> From: Bob Rossi <bob_rossi@cox.net>
> Cc: gdb-patches@sources.redhat.com
> 
> On Fri, May 12, 2006 at 09:27:21PM +0300, Eli Zaretskii wrote:
> > > Date: Fri, 12 May 2006 10:21:35 -0400
> > > From: Bob Rossi <bob_rossi@cox.net>
> > > Cc: gdb-patches@sources.redhat.com
> > > 
> > > I'm not sure if it helps to think of things in terms of releases in
> > > regards to GDB/MI. Unfortunatly, many distros package a CVS release of
> > > GDB. So, any given snapshot of GDB could have this feature or not.
> > 
> > People who use GDB snapshots are on their own when some feature
> > evolves during development.  So I'm not bothered by this.
> 
> Please please don't say this. It's just not a practical statement to
> make. Many of the distrobutions use CVS snapshots.

I'm sorry, but it's impractical for us to cater to users of all the
snapshots out there.  There simply isn't any practical way to have in
the manual a detailed description of the MI evolution during
development.  People who bump into problems with snapshots will have
to ask for help on the GDB mailing list, if they cannot firgure it out
themselves.

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Sat, May 13, 2006 at 11:03:43AM +0300, Eli Zaretskii wrote:
> > Date: Fri, 12 May 2006 15:16:40 -0400
> > From: Bob Rossi <bob_rossi@cox.net>
> > Cc: gdb-patches@sources.redhat.com
> > 
> > On Fri, May 12, 2006 at 09:27:21PM +0300, Eli Zaretskii wrote:
> > > > Date: Fri, 12 May 2006 10:21:35 -0400
> > > > From: Bob Rossi <bob_rossi@cox.net>
> > > > Cc: gdb-patches@sources.redhat.com
> > > > 
> > > > I'm not sure if it helps to think of things in terms of releases in
> > > > regards to GDB/MI. Unfortunatly, many distros package a CVS release of
> > > > GDB. So, any given snapshot of GDB could have this feature or not.
> > > 
> > > People who use GDB snapshots are on their own when some feature
> > > evolves during development.  So I'm not bothered by this.
> > 
> > Please please don't say this. It's just not a practical statement to
> > make. Many of the distrobutions use CVS snapshots.
> 
> I'm sorry, but it's impractical for us to cater to users of all the
> snapshots out there.  There simply isn't any practical way to have in
> the manual a detailed description of the MI evolution during
> development.  People who bump into problems with snapshots will have
> to ask for help on the GDB mailing list, if they cannot firgure it out
> themselves.

OK, maybe we agree then. You agree that the FE's should be allowed to
work with CVS snapshots, however, FE developers will not get the benefit
of a nice manual for those snapshots. Correct?

Thanks,
Bob Rossi

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Sat, 13 May 2006 06:59:46 -0400
> From: Bob Rossi <bob_rossi@cox.net>
> Cc: gdb-patches@sources.redhat.com
> 
> You agree that the FE's should be allowed to work with CVS
> snapshots, however, FE developers will not get the benefit of a nice
> manual for those snapshots. Correct?

Yes, except that instead of a ``nice manual'' I mean a ``manual that
includes a full detailed description of what was the behavior on any
given date''.

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

> > I thought I did, but apparently I was unclear. The next 2 paragraphs
> > were supposed to describe what it's role is now, I'm sorry to see it was
> > written so unclear.
> 
> Thanks for the clarifications.  I will try to come up with some text
> that adds the necessary information.

Hi Eli,

Where you going to look into this? or is this something I should do?

(I'm not worried about time here, just ping'ing).
Bob Rossi

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> Date: Mon, 29 May 2006 08:28:59 -0400
> From: Bob Rossi <bob_rossi@cox.net>
> Cc: gdb-patches@sources.redhat.com
> 
> > > I thought I did, but apparently I was unclear. The next 2 paragraphs
> > > were supposed to describe what it's role is now, I'm sorry to see it was
> > > written so unclear.
> > 
> > Thanks for the clarifications.  I will try to come up with some text
> > that adds the necessary information.
> 
> Hi Eli,
> 
> Where you going to look into this?

Yes, it's still on my todo.

Re: CLI and GDB/MI documentation patch

[Nick Roberts]

> I'd agree with Eli that the proposed text sounds a bit like history, but it
> documents some important points:

I'm not sure I like it because:

> - That you can type CLI commands into MI, and this is not longer considered
>   to work just by accident

It was never just by accident, just more of a hack.

> - That typing CLI command has the same effect as -interpreter-exec console

Its not quite the same, the latter goes through mi_cmd_execute but the
former doesn't.

> - That CLI command don't produce async notifications

They don't *currently* produce async notifications but I'm trying to change
that with my branch.

> Those points are important to have documented, IMO.

Putting these things in the manual just makes it harder to change GDB.
I would rather say: "Its there.  Use it at your own risk".  Or at least:


  For the developers convenience CLI commands can be entered directly.
  However this feature may be removed at some stage in the future and
  it is recommended that front ends use the @code{-interpreter exec} command.
  @xref{GDB/MI Miscellaneous Commands}.




-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: CLI and GDB/MI documentation patch

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Sun, 14 May 2006 00:43:41 +1200
> Cc: gdb-patches@sources.redhat.com
> 
> > - That typing CLI command has the same effect as -interpreter-exec console
> 
> Its not quite the same, the latter goes through mi_cmd_execute but the
> former doesn't.

Bob described the minor differences:

            There may be a small difference in the @sc{gdb/mi} output between 
  directly typing the CLI command into the @sc{gdb/mi} interpreter or by using 
  the @code{-interpreter-exec} command, however, both ways should provide 
  valid @sc{gdb/mi} output.

(``small differences in output'' is too vague; I'd like a more precise
and clear description of the differences.)

And later:

  One current major difference between entering a CLI command directly into
  the @sc{gdb/mi} interpreter and entering the corresponding @sc{gdb/mi} 
  command into the interpreter is that the CLI command will not have the 
  asynchronous output that the @sc{gdb/mi} command will have. For instance,
  typing @code{run} as a CLI command, you will not get the @code{*stopped}
  response that @sc{gdb/mi} will provide if you enter the @code{-exec-run}
  command.

Are there any other differences?  If so, let's describe them.

> > Those points are important to have documented, IMO.
> 
> Putting these things in the manual just makes it harder to change GDB.
> I would rather say: "Its there.  Use it at your own risk".  Or at least:
> 
> 
>   For the developers convenience CLI commands can be entered directly.
>   However this feature may be removed at some stage in the future and
>   it is recommended that front ends use the @code{-interpreter exec} command.
>   @xref{GDB/MI Miscellaneous Commands}.

Do we indeed intend to remove this feature any time soon?  If so, I
agree that we should add a warning about that.  But, other than that,
why do you say that describing the CLI support in mi in more detail
will make it harder to change GDB?

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Fri, May 12, 2006 at 05:05:51PM +0300, Eli Zaretskii wrote:
> > From: Nick Roberts <nickrob@snap.net.nz>
> > Date: Sun, 14 May 2006 00:43:41 +1200
> > Cc: gdb-patches@sources.redhat.com
> > 
> > > - That typing CLI command has the same effect as -interpreter-exec console
> > 
> > Its not quite the same, the latter goes through mi_cmd_execute but the
> > former doesn't.
> 
> Bob described the minor differences:
> 
>             There may be a small difference in the @sc{gdb/mi} output between 
>   directly typing the CLI command into the @sc{gdb/mi} interpreter or by using 
>   the @code{-interpreter-exec} command, however, both ways should provide 
>   valid @sc{gdb/mi} output.
> 
> (``small differences in output'' is too vague; I'd like a more precise
> and clear description of the differences.)
> 
> And later:
> 
>   One current major difference between entering a CLI command directly into
>   the @sc{gdb/mi} interpreter and entering the corresponding @sc{gdb/mi} 
>   command into the interpreter is that the CLI command will not have the 
>   asynchronous output that the @sc{gdb/mi} command will have. For instance,
>   typing @code{run} as a CLI command, you will not get the @code{*stopped}
>   response that @sc{gdb/mi} will provide if you enter the @code{-exec-run}
>   command.
> 
> Are there any other differences?  If so, let's describe them.
> 
> > > Those points are important to have documented, IMO.
> > 
> > Putting these things in the manual just makes it harder to change GDB.
> > I would rather say: "Its there.  Use it at your own risk".  Or at least:
> > 
> > 
> >   For the developers convenience CLI commands can be entered directly.
> >   However this feature may be removed at some stage in the future and
> >   it is recommended that front ends use the @code{-interpreter exec} command.
> >   @xref{GDB/MI Miscellaneous Commands}.
> 
> Do we indeed intend to remove this feature any time soon?  If so, I
> agree that we should add a warning about that.  But, other than that,
> why do you say that describing the CLI support in mi in more detail
> will make it harder to change GDB?

IMO, we don't intend to remove it soon. I attempted to remove it with 
this statement:
  I'm thinking it would be a good idea to remove the ability to enter
  CLI commands into the MI interpreter. Does anyone disagree?

and this was the response from Nick:
  No one is forcing you to use it.  Why would you want to force others
  not to use it?
from Daniel
  No way.  The fact is, the MI command set is not complete, and
  -interpreter-exec is still recent.  I would expect most front ends
  to still require this support, for the indefinite future.

So, with that in mind, I'm assuming it won't be dropped for a very long
time.

Bob Rossi

Re: CLI and GDB/MI documentation patch

[Nick Roberts]

 > > Putting these things in the manual just makes it harder to change GDB.
 > > I would rather say: "Its there.  Use it at your own risk".  Or at least:
 > > 
 > > 
 > >   For the developers convenience CLI commands can be entered directly.
 > >   However this feature may be removed at some stage in the future and
 > >   it is recommended that front ends use the @code{-interpreter exec} command.
 > >   @xref{GDB/MI Miscellaneous Commands}.
 > 
 > Do we indeed intend to remove this feature any time soon?  If so, I
 > agree that we should add a warning about that.  

I don't know about any time soon buts it's clearly irregular and I guess
could interfere with the design of MI.  Also it doesn't have to stay as
-interpreter exec provides an alternative.
 >                                                But, other than that,
 > why do you say that describing the CLI support in mi in more detail
 > will make it harder to change GDB?

Because if people write a front end that relies on a feature then understanably
they are upset when it is changed or removed, just as I was when it appeared
that annotations would be removed.   The one advantage of Emacs long
release cycle is that it gives you more time to get everything right before
its released.  GDB goes out about every six months along with an expectation
that its behaviour will some level of maintenance.



-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: CLI and GDB/MI documentation patch

[Bob Rossi]

On Sat, May 13, 2006 at 09:52:47AM +1200, Nick Roberts wrote:
>  > > Putting these things in the manual just makes it harder to change GDB.
>  > > I would rather say: "Its there.  Use it at your own risk".  Or at least:
>  > > 
>  > > 
>  > >   For the developers convenience CLI commands can be entered directly.
>  > >   However this feature may be removed at some stage in the future and
>  > >   it is recommended that front ends use the @code{-interpreter exec} command.
>  > >   @xref{GDB/MI Miscellaneous Commands}.
>  > 
>  > Do we indeed intend to remove this feature any time soon?  If so, I
>  > agree that we should add a warning about that.  
> 
> I don't know about any time soon buts it's clearly irregular and I guess
> could interfere with the design of MI.  Also it doesn't have to stay as
> -interpreter exec provides an alternative.
>  >                                                But, other than that,
>  > why do you say that describing the CLI support in mi in more detail
>  > will make it harder to change GDB?
> 
> Because if people write a front end that relies on a feature then understanably
> they are upset when it is changed or removed, just as I was when it appeared
> that annotations would be removed.   The one advantage of Emacs long
> release cycle is that it gives you more time to get everything right before
> its released.  GDB goes out about every six months along with an expectation
> that its behaviour will some level of maintenance.

I agree with you completly. What if we released mi3 with the
next release of GDB. We could remove the direct CLI commands then. I
think there would be some advantages to releasing mi3 anyways.

The good news for FE developers, is that a very quick fix on there side
should allow them to be working again.

Bob Rossi

Re: CLI and GDB/MI documentation patch

[Nick Roberts]

 > > Because if people write a front end that relies on a feature then
 > > understanably they are upset when it is changed or removed, just as I was
 > > when it appeared that annotations would be removed.  The one advantage of
 > > Emacs long release cycle is that it gives you more time to get everything
 > > right before its released.  GDB goes out about every six months along
 > > with an expectation that its behaviour will some level of maintenance.
 > 
 > I agree with you completly. What if we released mi3 with the
 > next release of GDB. We could remove the direct CLI commands then. I
 > think there would be some advantages to releasing mi3 anyways.

AFAICS the only changes to MI since 6.4 have been to add the fullname field
to breakpoint related commands and to generate an error record for directly
entered CLI commands.  I think we only need to bump the number when an
incompatible change change is made that will break existing front ends.

I also think it will prove too difficult to maintain functionality for old
levels in general (mi0 or mi1 might be an exception) but clearly new front
ends will be able to work with more than one level if they want (old ones will
break with the new level).  We did start to talk about what changes could be
made within one level: new commands, extra fields etc which I think we need to
document so that developers know what to expect.  I think at some stage we
should also document our thoughts changing MI level.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: CLI and GDB/MI documentation patch

[Daniel Jacobowitz]

On Sun, May 14, 2006 at 09:06:56PM +1200, Nick Roberts wrote:
> AFAICS the only changes to MI since 6.4 have been to add the fullname field
> to breakpoint related commands and to generate an error record for directly
> entered CLI commands.  I think we only need to bump the number when an
> incompatible change change is made that will break existing front ends.

Right.  I have at least one such change in mind - I posted about the
mess of quoting and backslash processing on gdb@ some time ago though I
have no idea when I'll have time to get back to it.  The asynchronous
changes you've been working with may also require an MI level bump.

> break with the new level).  We did start to talk about what changes could be
> made within one level: new commands, extra fields etc which I think we need to
> document so that developers know what to expect.  I think at some stage we
> should also document our thoughts changing MI level.

I invite you :-)

-- 
Daniel Jacobowitz
CodeSourcery