From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 15478 invoked by alias); 30 May 2006 07:17:48 -0000 Received: (qmail 15464 invoked by uid 22791); 30 May 2006 07:17:46 -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; Tue, 30 May 2006 07:17:26 +0000 Received: from kahikatea.snap.net.nz (p293-tnt1.snap.net.nz [202.124.111.39]) by viper.snap.net.nz (Postfix) with ESMTP id 59E73755FB6; Tue, 30 May 2006 19:17:25 +1200 (NZST) Received: by kahikatea.snap.net.nz (Postfix, from userid 500) id E31241D3550; Tue, 30 May 2006 19:16:45 +1200 (NZST) From: Nick Roberts MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <17531.61787.895726.198461@kahikatea.snap.net.nz> Date: Tue, 30 May 2006 15:59:00 -0000 To: Daniel Jacobowitz Cc: gdb-patches@sources.redhat.com Subject: {PATCH] MI Doco [was Re: CLI and GDB/MI...] In-Reply-To: <20060513154631.GA4941@nevyn.them.org> 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> X-Mailer: VM 7.19 under Emacs 22.0.50.18 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/msg00472.txt.bz2 > > ...We did start to talk about what changes could > > be made within one level: new commands, extra fields etc which I think we > > need to document so that developers know what to expect. I think at some > > stage we should also document our thoughts changing MI level. > > I invite you :-) OK, here's something along these lines. Its a bit incomplete but it might be good to put something in now, and develop it as our ideas crystallise. I must say I don't like the term "front end" (or "back end"). It makes me think of all those Carry On films I watched as a child! -- Nick http://www.inet.net.nz/~nickrob *** gdb.texinfo 30 May 2006 18:30:35 +1200 1.332 --- gdb.texinfo 30 May 2006 19:13:48 +1200 *************** *** 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 *************** *** 17246,17259 **** @heading Dependencies @end ignore - @heading Acknowledgments - - In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and - Elena Zannoni. - @menu * GDB/MI Command Syntax:: * GDB/MI Compatibility with CLI:: * GDB/MI Output Records:: * GDB/MI Command Description Format:: * GDB/MI Breakpoint Table Commands:: --- 17247,17256 ---- @heading Dependencies @end ignore @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:: *************** *** 17571,17576 **** --- 17568,17624 ---- 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 + + 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 minimise 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 such that is considered likely that they would + necessarily break a front end, 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 GDB 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 ensure that unexpected changes which break your front + end are not made 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. + + @c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @node GDB/MI Output Records @section @sc{gdb/mi} Output Records