From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 21374 invoked by alias); 28 Aug 2002 20:50:06 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 21366 invoked from network); 28 Aug 2002 20:50:05 -0000 Received: from unknown (HELO valrhona.uglyboxes.com) (64.1.192.220) by sources.redhat.com with SMTP; 28 Aug 2002 20:50:05 -0000 Received: from localhost.localdomain (IDENT:NABf4gSFHE7UOr6s4n4uOgR4A8iIRCyR@localhost.localdomain [127.0.0.1]) by valrhona.uglyboxes.com (8.11.6/8.11.6) with ESMTP id g7SKqgA16777 for ; Wed, 28 Aug 2002 13:52:43 -0700 Date: Wed, 28 Aug 2002 14:31:00 -0000 From: Keith Seitz X-X-Sender: keiths@valrhona.uglyboxes.com To: gdb-patches@sources.redhat.com Subject: [RFC/doc] Interpreters documentation Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII X-SW-Source: 2002-08/txt/msg00954.txt.bz2 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 * 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