This is the mail archive of the
gdb-patches@sourceware.org
mailing list for the GDB project.
[PATCH] doc: Add table of MI versions
- From: Simon Marchi <simon dot marchi at ericsson dot com>
- To: "gdb-patches at sourceware dot org" <gdb-patches at sourceware dot org>
- Cc: Simon Marchi <simon dot marchi at ericsson dot com>
- Date: Mon, 14 Jan 2019 20:39:16 +0000
- 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/gdb.texinfo | 57 ++++++++++++++++++++++++++++++++++++---------
1 file changed, 46 insertions(+), 11 deletions(-)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index 064ac90b596..091afb20050 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -27761,11 +27761,8 @@ 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.
+The MI interface is versioned, allowing it to evolve while avoiding breaking
+existing front ends.
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 +27788,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. Previous 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 to 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.
+
+@item
+@code{-var-list-children}'s @code{children} result field is a now 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