From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15300 invoked by alias); 31 May 2006 01:20:30 -0000 Received: (qmail 15289 invoked by uid 22791); 31 May 2006 01:20:29 -0000 X-Spam-Check-By: sourceware.org Received: from viper.snap.net.nz (HELO viper.snap.net.nz) (202.37.101.8) by sourceware.org (qpsmtpd/0.31) with ESMTP; Wed, 31 May 2006 01:20:25 +0000 Received: from kahikatea.snap.net.nz (p202-124-112-87.snap.net.nz [202.124.112.87]) by viper.snap.net.nz (Postfix) with ESMTP id 807EC756E41; Wed, 31 May 2006 13:20:22 +1200 (NZST) Received: by kahikatea.snap.net.nz (Postfix, from userid 500) id 00D921D3550; Wed, 31 May 2006 13:19:44 +1200 (NZST) From: Nick Roberts MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <17532.61231.319016.988575@kahikatea.snap.net.nz> Date: Wed, 31 May 2006 03:15:00 -0000 To: Eli Zaretskii Cc: gdb-patches@sources.redhat.com Subject: Re: {PATCH] MI Doco [was Re: CLI and GDB/MI...] In-Reply-To: References: <17509.54397.736467.479414@kahikatea.snap.net.nz> <17509.943.40875.198555@farnswood.snap.net.nz> <20060512221531.GA1741@brasko.net> <17510.62256.102468.268003@kahikatea.snap.net.nz> <20060513154631.GA4941@nevyn.them.org> <17531.61787.895726.198461@kahikatea.snap.net.nz> X-Mailer: VM 7.19 under Emacs 22.0.50.19 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org X-SW-Source: 2006-05/txt/msg00476.txt.bz2 > Thanks. I have a few comments and suggestions: > > > + @node GDB/MI Development and Front Ends > > + @section @sc{gdb/mi} Development and Front Ends > > + > > + The application which takes the MI output and presents the state of the > > + program being debugged to the user is called a @dfn{front end}. > > Please add a @cindex entry here. The text can be the name of the > section, or some permutation thereof. OK > > + section tries to minimise the problems by describing how the protocol > > "minimize", please. We use the US spelling. OK > > + If the changes are such that is considered likely that they would > > + necessarily break a front end OK > I think the following is simpler and more clear: > > If changes are accumulated that are likely to break front ends, ... > > > + to the MI version. Apart from mi0, new versions of GDB will not OK > Please use "@value{GDBN}" instead of a literal "GDB". OK > > + The best way to ensure that unexpected changes which break your front > > + end are not made is > > The best way to avoid changes in MI that might unexpectedly break > your front end is ... I made a similar change. > > is to make your project known to GDB developers and > > + follow development on @email{gdb@@sources.redhat.com} and > > + @email{gdb-patches@@sources.redhat.com}. There is also the mailing list > > + @email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards > > + Group, which has the aim of creating a a more general MI protocol > > + called Debugger Machine Interface (DMI) that will become a standard > > + for all debuggers, not just GDB. > > I suggest an index entry here, something like > > @cindex @sc{gdb/mi} development, mailing lists I added "@cindex @sc{gdb/mi} development" at the start of the node, so I just added "@cindex mailing lists" here. Thanks for the prompt review. -- Nick http://www.inet.net.nz/~nickrob 2006-05-31 Nick Roberts * gdb.texinfo (GDB/MI Development and Front Ends): New Node. *** gdb.texinfo 31 May 2006 13:03:22 +1200 1.332 --- gdb.texinfo 31 May 2006 13:14:09 +1200 *************** This chapter is a specification of the @ *** 17215,17221 **** in the form of a reference manual. Note that @sc{gdb/mi} is still under construction, so some of the ! features described below are incomplete and subject to change. @unnumberedsec Notation and Terminology --- 17215,17222 ---- in the form of a reference manual. Note that @sc{gdb/mi} is still under construction, so some of the ! features described below are incomplete and subject to change ! (@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). @unnumberedsec Notation and Terminology *************** Elena Zannoni. *** 17254,17259 **** --- 17255,17261 ---- @menu * GDB/MI Command Syntax:: * GDB/MI Compatibility with CLI:: + * GDB/MI Development and Front Ends:: * GDB/MI Output Records:: * GDB/MI Command Description Format:: * GDB/MI Breakpoint Table Commands:: *************** behaviour, the exact output of such comm *** 17571,17576 **** --- 17573,17630 ---- an un-supported hybrid of @sc{gdb/mi} and CLI output. @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + @node GDB/MI Development and Front Ends + @section @sc{gdb/mi} Development and Front Ends + @cindex @sc{gdb/mi} development + + The application which takes the MI output and presents the state of the + program being debugged to the user is called a @dfn{front end}. + + Although @sc{gdb/mi} is still incomplete, it is currently being used + by a variety of front ends to @value{GDBN}. This makes it difficult + to introduce new functionality without breaking existing usage. This + section tries to minimize the problems by describing how the protocol + might change. + + Some changes in MI need not break a carefully designed front end, and + for these the MI version will remain unchanged. The following is a + list of changes that may occur within one level, so front ends should + parse MI output in a way that can handle them: + + @itemize @bullet + @item + New MI commands may be added. + + @item + New fields may be added to the output of any MI command. + + @c The format of field's content e.g type prefix, may change so parse it + @c at your own risk. Yes, in general? + + @c The order of fields may change? Shouldn't really matter but it might + @c resolve inconsistencies. + @end itemize + + If the changes are likely to break front ends, the MI version level + will be increased by one. This will allow the front end to parse the + output according to the MI version. Apart from mi0, new versions of + @value{GDBN} will not support old versions of MI and it will be the + responsibility of the front end to work with the new one. + + @c Starting with mi3, add a new command -mi-version that prints the MI + @c version? + + The best way to avoid unexpected changes in MI that might break your front + end is to make your project known to GDB developers and + follow development on @email{gdb@@sources.redhat.com} and + @email{gdb-patches@@sources.redhat.com}. There is also the mailing list + @email{dmi-discuss@@lists.freestandards.org}, hosted by the Free Standards + Group, which has the aim of creating a a more general MI protocol + called Debugger Machine Interface (DMI) that will become a standard + for all debuggers, not just GDB. + @cindex mailing lists + + @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @node GDB/MI Output Records @section @sc{gdb/mi} Output Records