This is the mail archive of the
gdb-patches@sources.redhat.com
mailing list for the GDB project.
[RFC/doc] Interpreters documentation
- From: Keith Seitz <keiths at redhat dot com>
- To: gdb-patches at sources dot redhat dot com
- Date: Wed, 28 Aug 2002 13:52:42 -0700 (PDT)
- Subject: [RFC/doc] Interpreters documentation
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