On 2019-01-16 12:03 p.m., Eli Zaretskii wrote: >> Date: Tue, 15 Jan 2019 15:37:45 -0500 >> From: Simon Marchi >> 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 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 + + * gdb.texinfo (GDB/MI Development and Front Ends): Add table of + MI versions. Update text around it. + 2019-01-14 Pedro Franco de Carvalho * 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 &j!z޶םb֫rnr