OpenE2K
/
binutils-gdb
12
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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.
This commit is contained in:
Simon Marchi 2019-01-16 14:32:13 -05:00
parent e7b47f2e68
commit 1fea0d5379
2 changed files with 53 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
gdb/doc/ChangeLog
View File

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

59
gdb/doc/gdb.texinfo
View File

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