From 7162c0cabe922de558b7f88b975ce9e587c8b69c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sun, 23 Apr 2000 08:15:49 +0000 Subject: [PATCH] * Makefile.in (GDBMI_DIR): New variable. (SET_TEXINPUTS): Add $(GDBMI_DIR). (SFILES_DOC): Add $(GDBMI_DIR)/gdbmi.texinfo. (gdbmi.texinfo): New target, for texi2roff. (gdb.me, gdb.ms, gdb.mm): Depend on gdbmi.texinfo. (gdb.info, gdb_toc.html): Add "-I ${GDBMI_DIR}". * gdb.texinfo (Top): Add GDB/MI to the main menu and @include gdbmi.texinfo. (Mode Options): Add xref to GDB/MI docs and remove a FIXME comment. * gdbmi.texinfo: Lots of changes, to include this document as part of the GDB manual. * TODO, NEWS: Update due to inclusion of gdbmi.texinfo in the GDB manual. --- gdb/ChangeLog | 5 + gdb/NEWS | 6 +- gdb/TODO | 18 - gdb/doc/ChangeLog | 14 + gdb/doc/Makefile.in | 26 +- gdb/doc/gdb.texinfo | 9 +- gdb/mi/ChangeLog-mi | 5 + gdb/mi/gdbmi.texinfo | 3973 ++++++++++++++++++++++++++++-------------- 8 files changed, 2717 insertions(+), 1339 deletions(-) diff --git a/gdb/ChangeLog b/gdb/ChangeLog index 78090d169cb..6275eb32406 100644 --- a/gdb/ChangeLog +++ b/gdb/ChangeLog @@ -1,3 +1,8 @@ +2000-04-23 Eli Zaretskii + + * TODO, NEWS: Update due to inclusion of gdbmi.texinfo in the GDB + manual. + 2000-04-23 Eli Zaretskii * config/djgpp/README: Explain how to unpack using djunpack.bat. diff --git a/gdb/NEWS b/gdb/NEWS index 64cb12c6825..c04c564807d 100644 --- a/gdb/NEWS +++ b/gdb/NEWS @@ -124,9 +124,9 @@ try to find a command that does what you are looking for. A new machine oriented interface (MI) has been added to GDB. This interface is designed for debug environments running GDB as a separate -process. This is part of the long term libGDB project. See -gdb/mi/gdbmi.texinfo for further information. It can be enabled by -configuring with: +process. This is part of the long term libGDB project. See the +"GDB/MI" chapter of the GDB manual for further information. It can be +enabled by configuring with: .../configure --enable-gdbmi diff --git a/gdb/TODO b/gdb/TODO index c10506c51ac..251ff8fbd6f 100644 --- a/gdb/TODO +++ b/gdb/TODO @@ -140,24 +140,6 @@ Mark -- -MI documentation in GDB user guide. (Andrew Cagney, Elena Zannoni, -Stan Shebs, anyone else?) - -> (Are there plans to make gdbmi.texi be part of the manual as well?) - -I'd like to see it go in there sooner rather than later too. Otherwise -you're introducing discrepancies between the manual and the documentation, -and everybody is confused - witness the lack of doc for the tracing -commands still, some two years after they were added... - -Discussion on MI can be found on the thread: [PATCH] GDB command-line -switches and annotations docs -http://sourceware.cygnus.com/ml/gdb-patches/2000-q1/msg00639.html - -MI documentation can be found in the file gdb/mi/gdbmi.texinfo - --- - Revised UDP support (was: Re: [Fwd: [patch] UDP transport support]) http://sourceware.cygnus.com/ml/gdb-patches/2000-04/msg00000.html diff --git a/gdb/doc/ChangeLog b/gdb/doc/ChangeLog index dfc71384e53..5b15a2a67f6 100644 --- a/gdb/doc/ChangeLog +++ b/gdb/doc/ChangeLog @@ -1,3 +1,17 @@ +2000-04-23 Eli Zaretskii + + * Makefile.in (GDBMI_DIR): New variable. + (SET_TEXINPUTS): Add $(GDBMI_DIR). + (SFILES_DOC): Add $(GDBMI_DIR)/gdbmi.texinfo. + (gdbmi.texinfo): New target, for texi2roff. + (gdb.me, gdb.ms, gdb.mm): Depend on gdbmi.texinfo. + (gdb.info, gdb_toc.html): Add "-I ${GDBMI_DIR}". + + * gdb.texinfo (Top): Add GDB/MI to the main menu and @include + gdbmi.texinfo. + (Mode Options): Add xref to GDB/MI docs and remove a FIXME + comment. + 2000-04-17 Elena Zannoni * gdb.texinfo (Files): Update description of add-symbol-file diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in index cef11bf6948..57fac5cb04a 100644 --- a/gdb/doc/Makefile.in +++ b/gdb/doc/Makefile.in @@ -56,7 +56,11 @@ TEXI2ROFF=texi2roff # Traditionally readline is in .. or . READLINE_DIR = ${gdbdir}/../readline/doc -SET_TEXINPUTS = TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$$TEXINPUTS +# The GDB/MI docs come from a sibling directory ../mi +GDBMI_DIR = ${gdbdir}/mi + +SET_TEXINPUTS = \ + TEXINPUTS=${TEXIDIR}:.:$(srcdir):$(READLINE_DIR):$(GDBMI_DIR):$$TEXINPUTS # There may be alternate predefined collections of switches to configure # the GDB manual. Normally this is not done in synch with the software @@ -93,7 +97,7 @@ SFILES_INCLUDED = gdb-cfg.texi $(srcdir)/annotate.texi SFILES_LOCAL = $(srcdir)/gdb.texinfo GDBvn.texi $(SFILES_INCLUDED) -SFILES_DOC = $(SFILES_LOCAL) \ +SFILES_DOC = $(SFILES_LOCAL) $(GDBMI_DIR)/gdbmi.texinfo \ $(READLINE_DIR)/rluser.texinfo $(READLINE_DIR)/inc-hist.texinfo #### Host, target, and site specific Makefile fragments come in here. @@ -233,10 +237,10 @@ gdb.ps: gdb.dvi $(DVIPS) -o $@ $? # GDB MANUAL: info file -# We're using texinfo2, and older makeinfo's may not be able to +# We're using texinfo 3.12; older makeinfo's may not be able to # cope with all the markup. gdb.info: ${SFILES_DOC} - $(MAKEINFO) -I ${READLINE_DIR} -I $(srcdir) -o ./gdb.info gdb.texinfo + $(MAKEINFO) -I ${READLINE_DIR} -I ${GDBMI_DIR} -I $(srcdir) -o ./gdb.info gdb.texinfo # GDB MANUAL: roff translations # Try to use a recent texi2roff. v2 was put on prep in jan91. @@ -275,8 +279,14 @@ inc-hist.texinfo: ${READLINE_DIR}/inc-hist.texinfo ln ${READLINE_DIR}/inc-hist.texinfo . || \ cp ${READLINE_DIR}/inc-hist.texinfo . +gdbmi.texinfo: ${GDBMI_DIR}/gdbmi.texinfo + (test "$$LN_S" = "ln -s" && \ + ln -s ${GDBMI_DIR}/gdbmi.texinfo .) || \ + ln ${GDBMI_DIR}/gdbmi.texinfo . || \ + cp ${GDBMI_DIR}/gdbmi.texinfo . + # gdb manual suitable for [gtn]roff -me -gdb.me: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo +gdb.me: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo gdbmi.texinfo sed -e '/\\input texinfo/d' \ -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ -e '/^@ifinfo/,/^@end ifinfo/d' \ @@ -291,7 +301,7 @@ gdb.me: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo >gdb.me # gdb manual suitable for [gtn]roff -ms -gdb.ms: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo +gdb.ms: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo gdbmi.texinfo sed -e '/\\input texinfo/d' \ -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ -e '/^@ifinfo/,/^@end ifinfo/d' \ @@ -308,7 +318,7 @@ gdb.ms: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo # gdb manual suitable for [tn]roff -mm # '@noindent's removed due to texi2roff-2 mm bug; if yours is newer, # try leaving them in -gdb.mm: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo +gdb.mm: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo gdbmi.texinfo sed -e '/\\input texinfo/d' \ -e '/@c TEXI2ROFF-KILL/,/@c END TEXI2ROFF-KILL/d' \ -e '/^@ifinfo/,/^@end ifinfo/d' \ @@ -326,7 +336,7 @@ gdb.mm: $(SFILES_LOCAL) links2roff rluser.texinfo inc-hist.texinfo # GDB MANUAL: HTML file gdb_toc.html: ${SFILES_DOC} - $(MAKEHTML) $(MAKEHTMLFLAGS) -I ${READLINE_DIR} -I $(srcdir) $(srcdir)/gdb.texinfo + $(MAKEHTML) $(MAKEHTMLFLAGS) -I ${READLINE_DIR} -I ${GDBMI_DIR} -I $(srcdir) $(srcdir)/gdb.texinfo # GDB GUI MANUAL: TeX dvi file gdbgui.dvi : gdbgui.texinfo ${SFILES_DOC} diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo index d909466c5e2..4628dd0323c 100644 --- a/gdb/doc/gdb.texinfo +++ b/gdb/doc/gdb.texinfo @@ -24,6 +24,9 @@ @c readline appendices use @vindex @syncodeindex vr cp +@c gdbmi uses @findex +@syncodeindex fn cp + @c !!set GDB manual's edition---not the same as GDB version! @set EDITION Eighth @@ -142,6 +145,7 @@ Copyright (C) 1988-2000 Free Software Foundation, Inc. * Sequences:: Canned sequences of commands * Emacs:: Using @value{GDBN} under @sc{gnu} Emacs * Annotations:: @value{GDBN}'s annotation interface. +* GDB/MI:: @value{GDBN}'s Machine Interface. * GDB Bugs:: Reporting bugs in @value{GDBN} * Formatting Documentation:: How to format and print @value{GDBN} documentation @@ -1040,9 +1044,7 @@ Use the interpreter @var{interp} for interface with the controlling program or device. This option is meant to be set by programs which communicate with @value{GDBN} using it as a back end. For example, @samp{--interpreter=mi} causes @value{GDBN} to use the @dfn{gdbmi -interface}. -@c FIXME: There should be an @xref here to the GDB/MI docs, but -@c gdbmi.texi doesn't have a single node to reference! +interface} (@pxref{GDB/MI, , The @sc{gdb/mi} Interface}). @item -write @cindex @code{--write} @@ -12204,6 +12206,7 @@ each value is printed in its own window. @end ignore @include annotate.texi +@include gdbmi.texinfo @node GDB Bugs @chapter Reporting Bugs in @value{GDBN} diff --git a/gdb/mi/ChangeLog-mi b/gdb/mi/ChangeLog-mi index f0a3304500f..c03ef58fc09 100644 --- a/gdb/mi/ChangeLog-mi +++ b/gdb/mi/ChangeLog-mi @@ -1,3 +1,8 @@ +2000-04-23 Eli Zaretskii + + * gdbmi.texinfo: Lots of changes, to include this document as part + of the GDB manual. + 2000-03-13 James Ingham * mi-cmd-var.c (mi_cmd_var_create): Add special frame cookie "@" diff --git a/gdb/mi/gdbmi.texinfo b/gdb/mi/gdbmi.texinfo index 8602885caa8..a90c9d40068 100644 --- a/gdb/mi/gdbmi.texinfo +++ b/gdb/mi/gdbmi.texinfo @@ -1,293 +1,375 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename gdbmi.info -@settitle GDB/MI Machine Interface -@setchapternewpage off -@c %**end of header +@c \input texinfo @c -*-texinfo-*- +@c @c %**start of header +@c @setfilename gdbmi.info +@c @settitle GDB/MI Machine Interface +@c @setchapternewpage off +@c @c %**end of header + +@c @ifinfo +@c This file documents GDB/MI, a Machine Interface to GDB. + +@c Copyright (C) 2000, Free Software Foundation, Inc. +@c Contributed by Cygnus Solutions. + +@c Permission is granted to make and distribute verbatim copies of this +@c manual provided the copyright notice and this permission notice are +@c preserved on all copies. + +@c @ignore +@c Permission is granted to process this file through TeX and print the +@c results, provided the printed document carries copying permission notice +@c identical to this one except for the removal of this paragraph (this +@c paragraph not being relevant to the printed manual). + +@c @end ignore +@c Permission is granted to copy and distribute modified versions of this +@c manual under the conditions for verbatim copying, provided also that the +@c entire resulting derived work is distributed under the terms of a +@c permission notice identical to this one. + +@c Permission is granted to copy and distribute translations of this manual +@c into another language, under the above conditions for modified versions. +@c @end ifinfo + +@c @c This title page illustrates only one of the +@c @c two methods of forming a title page. + +@c @titlepage +@c @title GDB/MI +@c @subtitle Version 0.2 +@c @subtitle Feb 2000 +@c @author Andrew Cagney, Fernando Nasser and Elena Zannoni + +@c @c The following two commands +@c @c start the copyright page. +@c @page +@c @vskip 0pt plus 1filll +@c Permission is granted to make and distribute verbatim copies of this +@c manual provided the copyright notice and this permission notice are +@c preserved on all copies. + +@c Copyright @copyright{} 2000, Free Software Foundation, Inc. +@c @end titlepage -@ifinfo -This file documents GDB/MI, a Machine Interface to GDB. +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI +@chapter The @sc{gdb/mi} Interface -Copyright (C) 2000, Free Software Foundation, Inc. -Contributed by Cygnus Solutions. +@unnumberedsec Function and Purpose -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. +@cindex @sc{gdb/mi}, its purpose +@sc{gdb/mi} is a line based machine oriented text interface to GDB. It is +specifically intended to support the development of systems which use +the debugger as just one small component of a larger system. -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission notice -identical to this one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). +This chapter is a specification of the @sc{gdb/mi} interface. It is written +in the form of a reference manual. -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end ifinfo - -@c This title page illustrates only one of the -@c two methods of forming a title page. - -@titlepage -@title GDB/MI -@subtitle Version 0.2 -@subtitle Feb 2000 -@author Andrew Cagney, Fernando Nasser and Elena Zannoni - -@c The following two commands -@c start the copyright page. -@page -@vskip 0pt plus 1filll -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - -Copyright @copyright{} 2000, Free Software Foundation, Inc. -@end titlepage +Note that @sc{gdb/mi} is still under construction, so some of the +features described below are incomplete and subject to change. -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@chapter Overview +@unnumberedsec Notation and Terminology -@heading Function and Purpose +@cindex notational conventions, for @sc{gdb/mi} +This chapter uses the following notation: -GDB/MI is a line based machine oriented text interface to GDB. It is -specifically intended to support the development of systems which use -the debugger as just one small component of a larger system. +@itemize @bullet +@item +@code{|} separates two alternatives. + +@item +@code{[ @var{something} ]} indicates that @var{something} is optional: +it may or may not be given. -@heading This Document +@item +@code{( @var{group} )*} means that @var{group} inside the parentheses +may repeat zero or more times. -This document is a specification of the GDB/MI interface. It is written -in the form of a reference manual. +@item +@code{( @var{group} )+} means that @var{group} inside the parentheses +may repeat one or more times. -@heading Terminology +@item +@code{"@var{string}"} means a literal @var{string}. +@end itemize +@ignore @heading Dependencies +@end ignore @heading Acknowledgments -In alphabetic order: Fernando Nasser, Stan Shebs and Elena Zannoni. - -@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% CHAPTER %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -@chapter Command Syntax +In alphabetic order: Andrew Cagney, Fernando Nasser, Stan Shebs and +Elena Zannoni. + +@menu +* GDB/MI Command Syntax:: +* GDB/MI and CLI:: +* GDB/MI Output Records:: +* GDB/MI Command Description Format:: +* GDB/MI Breakpoint Table Commands:: +* GDB/MI Data Manipulation:: +* GDB/MI Program Control:: +* GDB/MI Misc Commands:: +* GDB/MI Stack Manipulation:: +* GDB/MI Symbol Query:: +* GDB/MI Target Manipulation:: +* GDB/MI Thread Commands:: +* GDB/MI Tracepoint Commands:: +* GDB/MI Variable Objects:: +@end menu + +@c When these are implemented, they should be moved to be between Misc and +@c Stack Manipulation in the above menu. They are now outside the menu +@c because makeinfo 3.12 barfs if it sees @ignore or @comments in the +@c middle of a menu. +@ignore +* GDB/MI Kod Commands:: +* GDB/MI Memory Overlay Commands:: +* GDB/MI Signal Handling Commands:: +@end ignore -@section Input Syntax +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Command Syntax +@section @sc{gdb/mi} Command Syntax -@table @code +@menu +* GDB/MI Input Syntax:: +* GDB/MI Output Syntax:: +* GDB/MI Simple Examples:: +@end menu -@item @expansion{} - | +@node GDB/MI Input Syntax +@subsection @sc{gdb/mi} Input Syntax -@item @expansion{} -[ ] "any existing GDB CLI command" +@cindex input syntax for @sc{gdb/mi} +@cindex @sc{gdb/mi}, input syntax +@table @code +@item @var{command} @expansion{} +@code{@var{cli-command} | @var{mi-command}} -@item @expansion{} -[ ] ``-'' ( `` ''