Re: [PATCH] doc: Add table of MI versions

[Simon Marchi <simon.marchi@ericsson.com>]

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1: Type: text/plain; charset="utf-8", Size: 6477 bytes --]

On 2019-01-16 12:03 p.m., Eli Zaretskii wrote:
>> Date: Tue, 15 Jan 2019 15:37:45 -0500
>> From: Simon Marchi <simon.marchi@polymtl.ca>
>> Cc: simon.marchi@ericsson.com, gdb-patches@sourceware.org
>>
>> Since @sc{gdb/mi} is used by a variety of front ends to
>> @value{GDBN}, changes to the MI interface may break existing usage.
>> This section describes how the protocol changes and how to request
>> previous version of the protocol when it does.
> 
> OK, thanks.
> 
>>>   new versions of the MI protocol are not compatible with the old
>>>   versions
>>
>> I thought this was quite obvious by the fact that we say that we 
>> introduce a new version when we make breaking changes.  But I can add 
>> this sentence, which would result in this:
>>
>> If the changes are likely to break front ends, the MI version level
>> will be increased by one.  The new versions of the MI protocol are not 
>> compatible
>> with the old versions.  Old versions of MI remain available, allowing 
>> front ends
>> to keep using them until they are modified to use the latest MI version.
> 
> Fine by me.
> 
>>>> About the idea itself, I don't think we need to implement this.
>>>
>>> We don't need to agree with it, we just need to preserve the
>>> suggestion.
>>
>> I have opened [1], is it fine to remove the comment from gdb.texinfo?
> 
> No objections from me.

I have updated and pushed the patch (see below for final version, hopefully
I didn't miss anything), thanks.


From 1fea0d5379be553f9bcee7c50fba4cff00176d1b Mon Sep 17 00:00:00 2001
From: Simon Marchi <simon.marchi@ericsson.com>
Date: Wed, 16 Jan 2019 14:32:13 -0500
Subject: [PATCH] doc: Add table of MI versions

This patch adds a table summarizing the history or MI versions:

- The version number
- Which GDB version introduced it
- Breaking changes compared to the previous version

The goal of the table is to help writers of front ends know which
version of MI they can use with a given GDB version.  It will also help
them update their code to work against a newer MI version.

Right now, we just have 1 and 2, but we expect to add an entry for 3
soon.  I did a bit of archelogy and reverse engineering of the code to
come up with the breaking changes for MI 2.

I did some changes to the text around it, some things that I thought
needed to be clarified, seemed a bit dated or seemed just wrong
(especially "Apart from mi0, new versions of @value{GDBN} will not
support old versions of MI").

gdb/doc/ChangeLog:

	* gdb.texinfo (GDB/MI Development and Front Ends): Add table of
	MI versions.  Update text around it.
---
 gdb/doc/ChangeLog   |  5 ++++
 gdb/doc/gdb.texinfo | 59 ++++++++++++++++++++++++++++++++++++---------
 2 files changed, 53 insertions(+), 11 deletions(-)

diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog
index eec6e3e76d6..d38d4625c48 100644
--- a/gdb/doc/ChangeLog
+++ b/gdb/doc/ChangeLog
@@ -1,3 +1,8 @@
+2019-01-16  Simon Marchi  <simon.marchi@ericsson.com>
+
+	* gdb.texinfo (GDB/MI Development and Front Ends): Add table of
+	MI versions.  Update text around it.
+
 2019-01-14  Pedro Franco de Carvalho  <pedromfc@linux.ibm.com>

 	* gdb.texinfo (PowerPC Features): Document the alias
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 064ac90b596..173d18be6f7 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -27761,11 +27761,10 @@ recommended that front ends use the @code{-interpreter-exec} command
 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.
+Since @sc{gdb/mi} is used by a variety of front ends to @value{GDBN}, changes
+to the MI interface may break existing usage.  This section describes how the
+protocol changes and how to request previous version of the protocol when it
+does.

 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
@@ -27791,13 +27790,51 @@ The range of values for fields with specified values, e.g.,
 @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.
+will be increased by one.  The new versions of the MI protocol are not compatible
+with the old versions.  Old versions of MI remain available, allowing front ends
+to keep using them until they are modified to use the latest MI version.

-@c Starting with mi3, add a new command -mi-version that prints the MI
-@c version?
+Since @code{--interpreter=mi} always points to the latest MI version, it is
+recommended that front ends request a specific version of MI when launching
+@value{GDBN} (e.g. @code{--interpreter=mi2}) to make sure they get an
+interpreter with the MI version they expect.
+
+The following table gives a summary of the the released versions of the MI
+interface: the version number, the version of GDB in which it first appeared
+and the breaking changes compared to the previous version.
+
+@multitable @columnfractions .05 .05 .9
+@headitem MI version @tab GDB version @tab Breaking changes
+
+@item
+@center 1
+@tab
+@center 5.1
+@tab
+None
+
+@item
+@center 2
+@tab
+@center 6.0
+@tab
+
+@itemize
+@item
+The @code{-environment-pwd}, @code{-environment-directory} and
+@code{-environment-path} commands now returns values using the MI output
+syntax, rather than CLI output syntax.
+
+@item
+@code{-var-list-children}'s @code{children} result field is now a list, rather
+than a tuple.
+
+@item
+@code{-var-update}'s @code{changelist} result field is now a list, rather than
+a tuple.
+@end itemize
+
+@end multitable

 The best way to avoid unexpected changes in MI that might break your front
 end is to make your project known to @value{GDBN} developers and
-- 
2.20.1


\x16º&Öéj×!zÊÞ¶êçםøóÙb²Ö«r\x18\x1dn–­r\x17¬