From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 34034 invoked by alias); 14 Jan 2019 20:39:25 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 34008 invoked by uid 89); 14 Jan 2019 20:39:24 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-26.9 required=5.0 tests=BAYES_00,GIT_PATCH_0,GIT_PATCH_1,GIT_PATCH_2,GIT_PATCH_3 autolearn=ham version=3.3.2 spammy=variety, history, presents, UD:gdb.texinfo X-HELO: sessmg22.ericsson.net Received: from sessmg22.ericsson.net (HELO sessmg22.ericsson.net) (193.180.251.58) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with ESMTP; Mon, 14 Jan 2019 20:39:22 +0000 DKIM-Signature: v=1; a=rsa-sha256; d=ericsson.com; s=mailgw201801; c=relaxed/relaxed; q=dns/txt; i=@ericsson.com; t=1547498359; x=1550090359; h=From:Sender:Reply-To:Subject:Date:Message-ID:To:CC:MIME-Version:Content-Type: Content-Transfer-Encoding:Content-ID:Content-Description:Resent-Date:Resent-From: Resent-Sender:Resent-To:Resent-Cc:Resent-Message-ID:In-Reply-To:References:List-Id: List-Help:List-Unsubscribe:List-Subscribe:List-Post:List-Owner:List-Archive; bh=aKXN/7GQmyJ7muzlBn8T3mrThDwhtk0vMh0gbSruGQo=; b=bjFbuGI6cZzkHfV/J+voNjLNSvWN9snL7fh2giQnyD3UlN1FfXd+5AJF4Dm7lr1V Z1WhxVdrUXbnBDH9BiDO1qjRpEKOx5FyvK+VVrhFeH8RCxqfD88lPszGuDxtHST1 UkADXoJ6V2ssSa/XZucfJu0DuhgzFFUxjouE9oItw+g=; Received: from ESESBMB503.ericsson.se (Unknown_Domain [153.88.183.116]) by sessmg22.ericsson.net (Symantec Mail Security) with SMTP id 6F.D8.26412.773FC3C5; Mon, 14 Jan 2019 21:39:19 +0100 (CET) Received: from ESESSMR504.ericsson.se (153.88.183.126) by ESESBMB503.ericsson.se (153.88.183.170) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.1.1466.3; Mon, 14 Jan 2019 21:39:19 +0100 Received: from ESESSMB504.ericsson.se (153.88.183.165) by ESESSMR504.ericsson.se (153.88.183.126) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.1.1466.3; Mon, 14 Jan 2019 21:39:19 +0100 Received: from NAM02-BL2-obe.outbound.protection.outlook.com (153.88.183.157) by ESESSMB504.ericsson.se (153.88.183.165) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256_P256) id 15.1.1466.3 via Frontend Transport; Mon, 14 Jan 2019 21:39:19 +0100 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericsson.com; s=selector1; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=aKXN/7GQmyJ7muzlBn8T3mrThDwhtk0vMh0gbSruGQo=; b=nFIwiwfKojAdmCstf7a8FeU+k9XoQXM/tuTIiOEVzVMcuFkdBfEXNSnCc+zIRyp8PGPFEB2vnLurvD4L/608o4d01M6w0RllTois+5RK2DifVe1UDWLDJh3sEtKg2ddZbiZLLkHSI2TNphFzp6TTkd+bWtIXf8TgFkJGUGANMqE= Received: from BYAPR15MB2390.namprd15.prod.outlook.com (52.135.198.30) by BYAPR15MB2214.namprd15.prod.outlook.com (52.135.196.153) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.1516.19; Mon, 14 Jan 2019 20:39:16 +0000 Received: from BYAPR15MB2390.namprd15.prod.outlook.com ([fe80::a4b4:ea6a:6321:191e]) by BYAPR15MB2390.namprd15.prod.outlook.com ([fe80::a4b4:ea6a:6321:191e%4]) with mapi id 15.20.1516.019; Mon, 14 Jan 2019 20:39:16 +0000 From: Simon Marchi To: "gdb-patches@sourceware.org" CC: Simon Marchi Subject: [PATCH] doc: Add table of MI versions Date: Mon, 14 Jan 2019 20:39:00 -0000 Message-ID: <20190114203902.11490-1-simon.marchi@ericsson.com> received-spf: None (protection.outlook.com: ericsson.com does not designate permitted sender hosts) authentication-results: spf=none (sender IP is ) smtp.mailfrom=simon.marchi@ericsson.com; Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: quoted-printable MIME-Version: 1.0 Return-Path: simon.marchi@ericsson.com X-IsSubscribed: yes X-SW-Source: 2019-01/txt/msg00335.txt.bz2 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{-interpr= eter-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}. =20 -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 breaki= ng +existing front ends. =20 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 val= ues, e.g., @end itemize =20 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, allow= ing +front ends to keep using them until they are modified to use the latest MI +version. =20 -@c Starting with mi3, add a new command -mi-version that prints the MI -@c version? +Since @code{--interpreter=3Dmi} 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=3Dmi2}) to make sure to get an inte= rpreter +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 appear= ed +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, ra= ther +than a tuple. + +@item +@code{-var-update}'s @code{changelist} result field is now a list, rather = than +a tuple. +@end itemize + +@end multitable =20 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 --=20 2.20.1