[RFC/doc] Interpreters documentation

Keith Seitz
2002-08-28T20:50:06Z

Hi,

This is the small documentation that I have regarding interpreters in gdb.
(Okay, it's going to mention MI2 stuff, which hasn't been committed yet.)

Comments? Corrections? (I'm still a texinfo newbie.)

Keith

ChangeLog
2002-08-28 Keith Seitz <keiths@redhat.com>

* gdb.texinfo: Add chapter on interpreters. Refer the
command-line option "-i"/"--interpreter" to this chapter.

Patch
Index: doc/gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.115
diff -p -r1.115 gdb.texinfo
*** doc/gdb.texinfo 25 Aug 2002 19:10:15 -0000 1.115
--- doc/gdb.texinfo 28 Aug 2002 20:48:32 -0000
*************** Do not use this option if you run @value
*** 1122,1133 ****
@cindex @code{--interpreter}
Use the interpreter @var{interp} for interface with the controlling
program or device. This option is meant to be set by programs which
! communicate with @value{GDBN} using it as a back end.
!
! @samp{--interpreter=mi} (or @samp{--interpreter=mi1}) causes
! @value{GDBN} to use the @dfn{gdb/mi interface} (@pxref{GDB/MI, , The
! @sc{gdb/mi} Interface}). The older @sc{gdb/mi} interface, included in
! @value{GDBN} version 5.0 can be selected with @samp{--interpreter=mi0}.

@item -write
@cindex @code{--write}
--- 1122,1129 ----
@cindex @code{--interpreter}
Use the interpreter @var{interp} for interface with the controlling
program or device. This option is meant to be set by programs which
! communicate with @value{GDBN} using it as a back end. @xref{Interpreters, ,
! Command Interpreters}.

@item -write
@cindex @code{--write}
*************** The only backslash-escape sequences that
*** 13093,13098 ****
--- 13089,13149 ----
string are the simple ones that consist of backslash followed by a
letter.
@end table
+
+ @node Interpreters
+ @chapter Command Interpreters
+
+ @value{GDBN} supports multiple command interpreters, and some command
+ infrastructure to allow users or user interface writers to switch between
+ interpreters or run commands in other interpreters.
+
+ @value{GDBN} currently supports two command interpreters, the console
+ interpreter (sometimes called the command-line interpreter or @sc{cli}) and
+ the machine interface interpreter (or @sc{gdb/mi}). This manual describes
+ both of these interfaces in great detail.
+
+ By default, @value{GDBN} will start with the console interpreter. However,
+ the user may choose to start @value{GDBN} with another interpreter by specifying
+ the "-i" or "--interpreter" startup options. Defined interpreters include:
+
+ @table @code
+ @item console
+ The traditional console or command-line interpreter. This is the most often
+ used interpreter with @value{GDBN}. With no interpreter specified at runtime,
+ @value{GDBN} will use this interpreter.
+
+ @item mi
+ The newest @sc{gdb/mi} interface, used primarily by programs wishing to use
+ @value{GDBN} as a backend for a debugger GUI or an IDE. For more information,
+ see @ref{GDB/MI, ,The @sc{gdb/mi} Interface}.
+
+ @item mi2
+ The latest version of the @sc{gdb/mi} interface.
+
+ @item mi1
+ The @sc{gdb/mi} version included in @value{GDBN} version 5.1.
+
+ @item mi0
+ The @sc{gdb/mi} version included in @value{GDBN} version 5.0.
+ @end table
+
+ The interpreter being used by @value{GDBN} may not be dynamically switched at
+ runtime. Although possible, this could lead to a very precarious situation.
+ Consider an IDE using @sc{gdb/mi}. If a user enters the command
+ "interpreter-set console" in a console view, @value{GDBN} would switch
+ to using the console interpreter, rendering the IDE inoperable!
+
+ Although you may only choose a single interpreter at startup, you may execute
+ commands in any interpreter from the current interpreter using the appropriate
+ command. If you are running the console interpreter, simply use the
+ @code{interpreter-exec} command:
+
+ @smallexample
+ interpreter-exec mi "-data-list-register-names"
+ @end smallexample
+
+ @sc{gdb/mi} has a similar command, although it is only available in versions of
+ @value{GDBN} which support @sc{gdb/mi} version 2 (or greater).

@node TUI
@chapter @value{GDBN} Text User Interface