CLI and GDB/MI documentation patch

Bob Rossi
2006-05-12T01:16:56Z

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