{PATCH] MI Doco [was Re: CLI and GDB/MI...]

[Nick Roberts <nickrob at snap dot net dot nz>]

 > >                          ...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