TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$(GDBMI_DIR):$$TEXINPUTS
# Files which should be generated via 'info' and installed by 'install-info'
-INFO_DEPS = gdb.info gdbint.info stabs.info
+INFO_DEPS = gdb.info gdbint.info stabs.info annotate.info
# There may be alternate predefined collections of switches to configure
# the GDB manual. Normally this is not done in synch with the software
$(STABS_DOC_SOURCE_INCLUDES) \
$(STABS_DOC_BUILD_INCLUDES)
+# Annotate migration document
+ANNOTATE_DOC_SOURCE_INCLUDES = \
+ $(srcdir)/fdl.texi
+ANNOTATE_DOC_BUILD_INCLUDES = \
+ gdb-cfg.texi
+ANNOTATE_DOC_FILES = \
+ $(srcdir)/annotate.texinfo \
+ $(ANNOTATE_DOC_SOURCE_INCLUDES) \
+ $(ANNOTATE_DOC_BUILD_INCLUDES)
+
#### Host, target, and site specific Makefile fragments come in here.
###
all:
info: $(INFO_DEPS)
-dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi
-ps: gdb.ps gdbint.ps stabs.ps refcard.ps
-html: gdb_toc.html gdbint_toc.html stabs_toc.html
-pdf: gdb.pdf gdbint.pdf stabs.pdf
+dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi annotate.dvi
+ps: gdb.ps gdbint.ps stabs.ps refcard.ps annotate.ps
+html: gdb_toc.html gdbint_toc.html stabs_toc.html annotate.html
+pdf: gdb.pdf gdbint.pdf stabs.pdf annotate.pdf
all-doc: info dvi ps # pdf
diststuff: info
rm -f $(STABS_TEX_TMPS)
$(SET_TEXINPUTS) $(TEXI2DVI) --pdf $(srcdir)/stabs.texinfo
+# Clean these up before each run. Avoids a catch 22 with not being
+# able to re-generate these files (to fix a corruption) because these
+# files contain a corruption.
+ANNOTATE_TEX_TMPS = annotate.aux annotate.cp* annotate.fn* annotate.ky* \
+ annotate.log annotate.pg* annotate.toc annotate.tp* annotate.vr*
+
+# ANNOTATE DOCUMENTATION: TeX dvi file
+annotate.dvi : $(ANNOTATE_DOC_FILES)
+ rm -f $(ANNOTATE_TEX_TMPS)
+ $(SET_TEXINPUTS) $(TEXI2DVI) $(srcdir)/annotate.texinfo
+
+annotate.ps: annotate.dvi
+ $(DVIPS) -o $@ $?
+
+annotate.pdf: $(ANNOTATE_DOC_FILES)
+ rm -f $(ANNOTATE_TEX_TMPS)
+ $(SET_TEXINPUTS) $(TEXI2DVI) --pdf $(srcdir)/annotate.texinfo
+
+annotate.info: $(ANNOTATE_DOC_FILES)
+ $(MAKEINFO) -I $(srcdir) -o annotate.info $(srcdir)/annotate.texinfo
+
+annotate_toc.html: $(ANNOTATE_DOC_FILES)
+ $(MAKEHTML) $(MAKEHTMLFLAGS) $(srcdir)/annotate.texinfo
+
force:
Makefile: Makefile.in $(host_makefile_frag) $(target_makefile_frag) config.status
rm -f $(GDB_TEX_TMPS)
rm -f $(GDBINT_TEX_TMPS)
rm -f $(STABS_TEX_TMPS)
+ rm -f $(ANNOTATE_TEX_TMPS)
rm -f sedref.dvi sedref.tex tmp.sed
clean: mostlyclean
-@c \input texinfo @c -*-texinfo-*-
-@c @c %**start of header
-@c @setfilename annotate.info
-@c @settitle GDB Annotations
-@c @setchapternewpage off
-@c @c %**end of header
-
-@c @set EDITION 0.5
-@c @set DATE May 1994
-
-@c @ifinfo
-@c This file documents GDB annotations.
-
-@c This is Edition @value{EDITION}, @value{DATE}, of @cite{GDB
-@c Annotations}. Copyright 1994,1995,2000,2001 Free Software Foundation, Inc.
-
-@c Permission is granted to copy, distribute and/or modify this document
-@c under the terms of the GNU Free Documentation License, Version 1.1 or
-@c any later version published by the Free Software Foundation; with no
-@c Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
-@c and with the Back-Cover Texts as in (a) below.
-
-@c (a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-@c this GNU Manual, like GNU software. Copies published by the Free
-@c Software Foundation raise funds for GNU development.''
-@c @end ifinfo
-
-@c @titlepage
-@c @title GDB Annotations
-@c @subtitle Edition @value{EDITION}
-@c @subtitle @value{DATE}
-@c @author Cygnus Support
-@c @page
-@c @vskip 0pt plus 1filll
-@c Permission is granted to make and distribute verbatim copies of
-@c this manual provided the copyright notice and this permission notice
-@c are preserved on all copies.
-
-@c Copyright @copyright{} 1994,1995,2000,2001 Free Software Foundation
-@c @end titlepage
-
-@c @ifinfo
-@c @node Top
-@c @top GDB Annotations
-
-@c @syncodeindex fn cp
-
-@node Annotations
-@chapter @value{GDBN} Annotations
-
-This chapter describes annotations in @value{GDBN}. Annotations are
-designed to interface @value{GDBN} to graphical user interfaces or
-other similar programs which want to interact with @value{GDBN} at a
-relatively high level.
+\input texinfo @c -*-texinfo-*-
+@c %**start of header
+@setfilename annotate.info
+@c
+@include gdb-cfg.texi
+@c
+@settitle @value{GDBN}'s Obsolete Annotations
+@setchapternewpage off
+@c %**end of header
+
+@set EDITION 1.0
+@set DATE July 2003
+
+@c NOTE: cagney/2003-07-28:
+@c Don't make this migration doccument an appendix of GDB's user guide.
+@c By keeping this separate, the size of the user guide is contained. If
+@c the user guide to get much bigger it would need to switch to a larger,
+@c more expensive, form factor and would drive up the manuals publication
+@c cost. Having a smaller cheaper manual helps the GNU Press with its sales.
+
+@ifinfo
+This file documents @value{GDBN}'s obsolete annotations.
+
+Copyright 1994, 1995, 2000, 2001, 2003 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+
+@end ifinfo
+
+@titlepage
+@title @value{GDBN}'s Obsolete Annotations
+@subtitle Edition @value{EDITION}
+@subtitle @value{DATE}
+@author Free Software Foundation
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1994, 1995, 2000, 2001, 2003 Free Software
+Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts. A copy of the license is included in the section entitled ``GNU
+Free Documentation License''.
+@end titlepage
+
+@ifinfo
+@node Top
+@top GDB Annotations
+
+This document describes the obsolete level two annotation interface
+implemented in older @value{GDBN} versions.
@ignore
This is Edition @value{EDITION}, @value{DATE}.
@end ignore
+@end ifinfo
@menu
* Annotations Overview:: What annotations are; the general syntax.
+* Limitations:: Limitations of the annotation interface.
+* Migrating to GDB/MI:: Migrating to GDB/MI
* Server Prefix:: Issuing a command without affecting user state.
* Value Annotations:: Values are marked as such.
* Frame Annotations:: Stack frames are annotated.
* Annotations for Running::
Whether the program is running, how it stopped, etc.
* Source Annotations:: Annotations describing source code.
-* TODO:: Annotations which might be added in the future.
+
+* GNU Free Documentation License::
@end menu
+@contents
+
@node Annotations Overview
-@section What is an Annotation?
+@chapter What is an Annotation?
@cindex annotations
-To produce annotations, start @value{GDBN} with the @code{--annotate=2} option.
+To produce obsolete level two annotations, start @value{GDBN} with the
+@code{--annotate=2} option.
Annotations start with a newline character, two @samp{control-z}
characters, and the name of the annotation. If there is no additional
denotes a @samp{control-z} character) are annotations; the rest is
output from @value{GDBN}.
+@node Limitations
+@chapter Limitations of the Annotation Interface
+
+The level two annotations mechanism is known to have a number of
+technical and architectural limitations. As a consequence, in 2001,
+with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi},
+the annotation interface was marked as deprecated.
+
+This chapter discusses the known problems.
+
+@section Dependant on @sc{cli} output
+
+The annotation interface works by interspersing markups with
+@value{GDBN} normal command-line interpreter output. Unfortunatly, this
+makes the annotation client dependant on not just the annotations, but
+also the @sc{cli} output. This is because the client is forced to
+assume that specific @value{GDBN} commands provide specific information.
+Any change to @value{GDBN}'s @sc{cli} output modifies or removes that
+information and, consequently, likely breaks the client.
+
+Since the @sc{gdb/mi} output is independant of the @sc{cli}, it does not
+have this problem.
+
+@section Scalability
+
+The annotation interface relies on value annotations (@pxref{Value
+Annotations}) and the display mechanism as a way of obtaining up-to-date
+value information. These mechanisms are not scalable.
+
+In a graphical environment, where many values can be displayed
+simultaneously, a serious performance problem occurs when the client
+tries to first extract from @value{GDBN}, and then re-display, all those
+values. The client should instead only request and update the values
+that changed.
+
+The @sc{gdb/mi} Variable Objects provide just that mechanism.
+
+@section Correctness
+
+The annotation interface assumes that a variable's value can only be
+changed when the target is running. This assumption is not correct. A
+single assignment to a single variable can result in the entire target,
+and all displayed values, needing an update.
+
+The @sc{gdb/mi} Variable Objects include a mechanism for efficiently
+reporting such changes.
+
+@section Reliability
+
+The @sc{gdb/mi} interface includes a dedicated test directory
+(@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include
+testsuite changes.
+
+@section Maintainability
+
+The annotation mechanism was implemented by interspersing @sc{cli} print
+statements with various annotations. As a consequence, any @sc{cli}
+output change can alter the annotation output.
+
+Since the @sc{gdb/mi} output is independant of the @sc{cli}, and the
+@sc{gdb/mi} is increasingly implemented independant of the @sc{cli}
+code, its long term maintenance is much easier.
+
+@node Migrating to GDB/MI
+@chapter Migrating to @sc{gdb/mi}
+
+By using the @samp{interp mi} command, it is possible for annotation
+clients to invoke @sc{gdb/mi} commands, and hence access the
+@sc{gdb/mi}. By doing this, existing annotation clients have a
+migration path from this obsolete interface to @sc{gdb/mi}.
+
@node Server Prefix
-@section The Server Prefix
+@chapter The Server Prefix
@cindex server prefix for annotations
To issue a command to @value{GDBN} without affecting certain aspects of
use the @code{output} command instead of the @code{print} command.
@node Value Annotations
-@section Values
+@chapter Values
+
+@emph{Value Annotations have been removed. @sc{gdb/mi} instead provides
+Variable Objects.}
@cindex annotations for values
When a value is printed in various contexts, @value{GDBN} uses
@end smallexample
@node Frame Annotations
-@section Frames
+@chapter Frames
+
+@emph{Value Annotations have been removed. @sc{gdb/mi} instead provides
+a number of frame commands.}
+
+@emph{Frame annotations are no longer available. The @sc{gdb/mi}
+provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and
+@samp{-stack-list-frames} commands.}
@cindex annotations for frames
Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies
@end itemize
@node Displays
-@section Displays
+@chapter Displays
+
+@emph{Display Annotations have been removed. @sc{gdb/mi} instead
+provides Variable Objects.}
@findex display-begin
@findex display-number-end
and @var{value} is the actual value being displayed.
@node Prompting
-@section Annotation for @value{GDBN} Input
+@chapter Annotation for @value{GDBN} Input
@cindex annotations for prompts
When @value{GDBN} prompts for input, it annotates this fact so it is possible
@end table
@node Errors
-@section Errors
+@chapter Errors
@cindex annotations for errors, warnings and interrupts
@findex quit
@c range_error(), and possibly other places.
@node Breakpoint Info
-@section Information on Breakpoints
+@chapter Information on Breakpoints
+
+@emph{Breakpoint Annotations have been removed. @sc{gdb/mi} instead
+provides breakpoint commands.}
@cindex annotations for breakpoints
The output from the @code{info breakpoints} command is annotated as follows:
@end smallexample
@node Invalidation
-@section Invalidation Notices
+@chapter Invalidation Notices
@cindex annotations for invalidation messages
The following annotations say that certain pieces of state may have
@end table
@node Annotations for Running
-@section Running the Program
+@chapter Running the Program
@cindex annotations for running programs
@findex starting
@end table
@node Source Annotations
-@section Displaying Source
+@chapter Displaying Source
@cindex annotations for source display
@findex source
followed by one or more lowercase hex digits (note that this does not
depend on the language).
-@node TODO
-@section Annotations We Might Want in the Future
-
-@format
- - target-invalid
- the target might have changed (registers, heap contents, or
- execution status). For performance, we might eventually want
- to hit `registers-invalid' and `all-registers-invalid' with
- greater precision
-
- - systematic annotation for set/show parameters (including
- invalidation notices).
-
- - similarly, `info' returns a list of candidates for invalidation
- notices.
-@end format
+@include fdl.texi
@ignore
@node Index
@printindex fn
@end ignore
-@c @bye
+@bye
OSDN Git Service
