diff options
| -rw-r--r-- | gdb/doc/ChangeLog | 15 | ||||
| -rw-r--r-- | gdb/doc/Makefile.in | 45 | ||||
| -rw-r--r-- | gdb/doc/annotate.texinfo (renamed from gdb/doc/annotate.texi) | 251 |
3 files changed, 222 insertions, 89 deletions
diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index 81652d4e4c7..a2a8ce8bb0e 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,18 @@ +2003-07-28 Andrew Cagney <cagney@redhat.com> + + * Makefile.in (INFO_DEPS): Add annotate.info. + (dvi, ps, html, pdf): Add annotate. + (ANNOTATE_DOC_SOURCE_INCLUDES): New macro. + (ANNOTATE_DOC_BUILD_INCLUDES): New macro. + (ANNOTATE_DOC_FILES): New macro. + (ANNOTATE_TEX_TMPS): New macro. + (annotate.info, annotate_toc.html): Specify dependencies. + (annotate.ps, annotate.pdf, annotate.dvi): Ditto. + * annotate.texinfo: Rename annotate.texi. Get building. Add + "Migrating to GDB/MI" and "Limitations of the Annotation + Interface" chapters. Mention why it is not part of the user + guide. Update copyright notice. Include "fdl.texi". + 2003-07-26 Stephane Carrez <stcarrez@nerim.fr> * gdb.texinfo (TUI Keys): Document C-x o key to switch active window. diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index eda637cf19d..f5dda01af10 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -67,7 +67,7 @@ SET_TEXINPUTS = \ 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 @@ -131,16 +131,26 @@ STABS_DOC_FILES = \ $(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 @@ -420,6 +430,30 @@ stabs.pdf: $(STABS_DOC_FILES) 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 @@ -434,6 +468,7 @@ mostlyclean: 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 diff --git a/gdb/doc/annotate.texi b/gdb/doc/annotate.texinfo index fc269243578..401657d4a96 100644 --- a/gdb/doc/annotate.texi +++ b/gdb/doc/annotate.texinfo @@ -1,64 +1,71 @@ -@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. @@ -70,14 +77,18 @@ This is Edition @value{EDITION}, @value{DATE}. * 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 @@ -122,8 +133,79 @@ Here @samp{quit} is input to @value{GDBN}; the rest is output from 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 @@ -137,7 +219,10 @@ history; to print a value without recording it into the value history, 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 @@ -268,7 +353,14 @@ ended with @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 @@ -403,7 +495,10 @@ output, not in addition. @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 @@ -442,7 +537,7 @@ to separate the expression from the text that follows for the user, 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 @@ -502,7 +597,7 @@ presence of annotations. @end table @node Errors -@section Errors +@chapter Errors @cindex annotations for errors, warnings and interrupts @findex quit @@ -542,7 +637,10 @@ Warning messages are not yet annotated. @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: @@ -600,7 +698,7 @@ The output ends with @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 @@ -621,7 +719,7 @@ deleted a breakpoint. @end table @node Annotations for Running -@section Running the Program +@chapter Running the Program @cindex annotations for running programs @findex starting @@ -692,7 +790,7 @@ The program hit watchpoint number @var{number}. @end table @node Source Annotations -@section Displaying Source +@chapter Displaying Source @cindex annotations for source display @findex source @@ -714,22 +812,7 @@ source which is being displayed. @var{addr} is in the form @samp{0x} 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 @@ -738,4 +821,4 @@ depend on the language). @printindex fn @end ignore -@c @bye +@bye |