Date: Tue, 21 Jan 2003 19:02:21 +0000
From: Nick Roberts <nick@nick.uklinux.net>
To: Jim Blandy <jimb@redhat.com>
Cc: rms@gnu.org
Subject: obsoleting the annotate level 2 interface
Message-ID: <15917.39229.935851.920452@nick.uklinux.net>
References: <vt265sjj6vi.fsf@zenia.red-bean.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-length: 3257


There is a mode in the Emacs CVS repository (gdb-ui.el) that I have written
(based on gdba.el by Tom Lord and Jim Kingdon) that uses annotation level 2.
I did try to use GDB/MI when I started writing it but gave up because it
wasn't complete at the time (March/April last year). There was some discussion
on the mailing list and I felt that the folks working on the Eclipse project
became similarly disillusioned (I think that they might also currently use
annotation level 2). Additionally there was a debate about whether the command
line interface would be suported through GDB/MI as Richard Stallman was
anxious to keep the GUD buffer. Also, I think that DDD uses annotation level 1.

I had presumed that development on annotations had ceased and not that it
would be taken out. It has appeared quite robust to me and Andrew Cagney has
said as much. It would be a shame to lose it before GDB/MI has gained proven
acceptance.

Anyway, I'm sure that Richard will have something further to add.

Jim Blandy writes:
 > 
 > GDB seems to support two different ways of doing detailed annotations
 > of its output for consumption by other programs: MI and 'set annotate
 > 2'.  I don't think annotation level 2 has many active users, if any at
 > all.  It pervades GDB's code.  Would it make sense to put 'set
 > annotate 2' on the path to obsolescence?
 > 
 > Some background: the 'set annotate' command sets the
 > 'annotation_level' variable.  There are only three distinguished
 > values for this variable:
 > 
 > 0: nothing special, GDB behaves normally.
 > 1: in source.c:line_info and stack.c:print_frame_info, when we print
 >    the source line, we print out something extra that helps Emacs pop
 >    up the source code in a window.
 > 2 or greater: we enable around 250 calls to a variety of functions in
 >    annotate.c to mark and identify lots of things GDB prints.
 > 
 > I think we should keep level 1, since the standard Emacs GDB interface
 > uses it, and it's not very much code.
 > 
 > I'd like to see GDB dump level 2, since it duplicates MI, badly.  MI's
 > design ensures that whoever's trying to parse GDB's output gets
 > something that's well-formed, whereas annotate just sticks escape
 > codes into the outgoing stream of text.  This means that, if you
 > change the way anything prints, you may break an annotate level 2
 > client.  But to break an MI client, you actually have to change a
 > ui_out call, whose sole purpose is to produce output for clients to
 > read.  So MI is a much more maintainable approach, because it's easier
 > for people to see what they're doing.
 > 
 > If folks agree that annotate level 2 should go, we could:
 > - announce that annotate level 2 will be disabled in the release after
 >   next;
 > - in that release, disable the code, but leave it there, to see if
 >   anyone complains, and whether they can be persuaded to switch to MI;
 >   and
 > - in the release after that, if all goes well, remove the code to
 >   support annotation level 2.
 > 
 > Personally, I'd like to see Emacs switch from annotation level 1 to
 > MI, too; then we could get rid of annotation altogether.  But I think
 > it makes sense to tackle level 2 first, since I don't think it has
 > many users (if any).
 >