From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 7941 invoked by alias); 14 May 2002 21:15:33 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 7929 invoked from network); 14 May 2002 21:15:30 -0000 Received: from unknown (HELO zwingli.cygnus.com) (208.245.165.35) by sources.redhat.com with SMTP; 14 May 2002 21:15:30 -0000 Received: by zwingli.cygnus.com (Postfix, from userid 442) id 0B2C35EA11; Tue, 14 May 2002 16:15:28 -0500 (EST) To: gdb-patches@sources.redhat.com Cc: Neil Booth Subject: Re: RFA: document macro support References: <20020513233504.BE1495EA11@zwingli.cygnus.com> <20020514065015.GA22717@daikokuya.demon.co.uk> From: Jim Blandy Date: Tue, 14 May 2002 14:15:00 -0000 In-Reply-To: <20020514065015.GA22717@daikokuya.demon.co.uk> Message-ID: User-Agent: Gnus/5.09 (Gnus v5.9.0) Emacs/21.1 MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-SW-Source: 2002-05/txt/msg00560.txt.bz2 Here is a revised macro documentation patch that uses @option and @command where appropriate, and makes some other minor revisions. I've noticed that these directives aren't used elsewhere in GDB's documentation; is there any policy on their use? 2002-05-13 Jim Blandy * gdbint.texinfo (C Preprocessor Macros): New chapter. Include it in the main menu. (Contributors): Credit Jim Blandy with macro support. (Compilation): Explain how to get macro information into the executable. (Expressions): Note that preprocessor macros are expanded. Index: gdb/doc/gdb.texinfo =================================================================== RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v retrieving revision 1.98 diff -c -r1.98 gdb.texinfo *** gdb/doc/gdb.texinfo 4 May 2002 16:00:30 -0000 1.98 --- gdb/doc/gdb.texinfo 14 May 2002 21:13:18 -0000 *************** *** 128,133 **** --- 128,134 ---- * Stack:: Examining the stack * Source:: Examining source files * Data:: Examining data + * Macros:: Preprocessor Macros * Tracepoints:: Debugging remote targets non-intrusively * Overlays:: Debugging programs that use overlays *************** *** 462,467 **** --- 463,470 ---- Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David Zuhn have made contributions both large and small. + Jim Blandy added support for preprocessor macros, while working for Red + Hat. @node Sample Session @chapter A Sample @value{GDBN} Session *************** *** 1609,1614 **** --- 1612,1627 ---- To request debugging information, specify the @samp{-g} option when you run the compiler. + Most compilers do not include information about preprocessor macros in + the debugging information if you specify the @option{-g} flag alone, + because this information is rather large. Version 3.1 of @value{NGCC}, + the @sc{gnu} C compiler, provides macro information if you specify the + options @option{-gdwarf-2} and @option{-g3}; the former option requests + debugging information in the Dwarf 2 format, and the latter requests + ``extra information''. In the future, we hope to find more compact ways + to represent macro information, so that it can be included with + @option{-g} alone. + Many C compilers are unable to handle the @samp{-g} and @samp{-O} options together. Using those compilers, you cannot generate optimized executables containing debugging information. *************** *** 4414,4422 **** @code{print} and many other @value{GDBN} commands accept an expression and compute its value. Any kind of constant, variable or operator defined by the programming language you are using is valid in an expression in ! @value{GDBN}. This includes conditional expressions, function calls, casts ! and string constants. It unfortunately does not include symbols defined ! by preprocessor @code{#define} commands. @value{GDBN} supports array constants in expressions input by the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, --- 4427,4435 ---- @code{print} and many other @value{GDBN} commands accept an expression and compute its value. Any kind of constant, variable or operator defined by the programming language you are using is valid in an expression in ! @value{GDBN}. This includes conditional expressions, function calls, ! casts, string constants. It also includes preprocessor macros, if you ! compiled your program to include this information; see @ref{Compilation}. @value{GDBN} supports array constants in expressions input by the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, *************** *** 5773,5778 **** --- 5786,6015 ---- the @var{bias} argument is applied. @end table + + @node Macros + @chapter C Preprocessor Macros + + Some languages, such as C and C++, provide a way to define and invoke + ``preprocessor macros'' which expand into strings of tokens. + @value{GDBN} can evaluate expressions containing macro invocations, show + the result of macro expansion, and show a macro's definition, including + where it was defined. + + You may need to compile your program specially to provide @value{GDBN} + with information about preprocessor macros. Most compilers do not + include macros in their debugging information, even when you compile + with the @option{-g} flag. @xref{Compilation}. + + A program may define a macro at one point, remove that definition later, + and then provide a different definition after that. Thus, at different + points in the program, a macro may have different definitions, or have + no definition at all. If there is a current stack frame, @value{GDBN} + uses the macros in scope at that frame's source code line. Otherwise, + @value{GDBN} uses the macros in scope at the current listing location; + see @ref{List}. + + At the moment, @value{GDBN} does not support the @code{##} + token-splicing operator, the @code{#} stringification operator, or + variable-arity macros. + + Whenever @value{GDBN} evaluates an expression, it always expands any + macro invocations present in the expression. @value{GDBN} also provides + the following commands for working with macros explicitly. + + @table @code + + @kindex macro expand + @cindex macro expansion, showing the results of preprocessor + @cindex preprocessor macro expansion, showing the results of + @cindex expanding preprocessor macros + @item macro expand @var{expression} + @itemx macro exp @var{expression} + Show the results of expanding all preprocessor macro invocations in + @var{expression}. Since @value{GDBN} simply expands macros, but does + not parse the result, @var{expression} need not be a valid expression; + it can be any string of tokens. + + @kindex macro expand-once + @item macro expand-once @var{expression} + @itemx macro exp1 @var{expression} + @i{(This command is not yet implemented.)} Show the results of + expanding those preprocessor macro invocations that appear explicitly in + @var{expression}. Macro invocations appearing in that expansion are + left unchanged. This command allows you to see the effect of a + particular macro more clearly, without being confused by further + expansions. Since @value{GDBN} simply expands macros, but does not + parse the result, @var{expression} need not be a valid expression; it + can be any string of tokens. + + @kindex show macro + @cindex macro definition, showing + @cindex definition, showing a macro's + @item show macro @var{macro} + Show the definition of the macro named @var{macro}, and describe the + source location where that definition was established. + + @kindex macro define + @cindex user-defined macros + @cindex defining macros interactively + @cindex macros, user-defined + @item macro define @var{macro} @var{replacement-list} + @itemx macro define @var{macro}(@var{arglist}) @var{replacement-list} + @i{(This command is not yet implemented.)} Introduce a definition for a + preprocessor macro named @var{macro}, invocations of which are replaced + by the tokens given in @var{replacement-list}. The first form of this + command defines an ``object-like'' macro, which takes no arguments; the + second form defines a ``function-like'' macro, which takes the arguments + given in @var{arglist}. + + A definition introduced by this command is in scope in every expression + evaluated in @value{GDBN}, until it is removed with the @command{macro + undef} command, described below. The definition overrides all + definitions for @var{macro} present in the program being debugged, as + well as any previous user-supplied definition. + + @kindex macro undef + @item macro undef @var{macro} + @i{(This command is not yet implemented.)} Remove any user-supplied + definition for the macro named @var{macro}. This command only affects + definitions provided with the @command{macro define} command, described + above; it cannot remove definitions present in the program being + debugged. + + @end table + + @cindex macros, example of debugging with + Here is a transcript showing the above commands in action. First, we + show our source files: + + @example + $ cat sample.c + #include + #include "sample.h" + + #define M 42 + #define ADD(x) (M + x) + + main () + @{ + #define N 28 + printf ("Hello, world!\n"); + #undef N + printf ("We're so creative.\n"); + #define N 1729 + printf ("Goodbye, world!\n"); + @} + $ cat sample.h + #define Q < + $ + @end example + + Now, we compile the program using the @sc{gnu} C compiler, @value{NGCC}. + We pass the @option{-gdwarf-2} and @option{-g3} flags to ensure the + compiler includes information about preprocessor macros in the debugging + information. + + @example + $ gcc -gdwarf-2 -g3 sample.c -o sample + $ + @end example + + Now, we start @value{GDBN} on our sample program: + + @example + $ gdb -nw sample + GNU gdb 2002-05-06-cvs + Copyright 2002 Free Software Foundation, Inc. + GDB is free software, @dots{} + (gdb) + @end example + + We can expand macros and examine their definitions, even when the + program is not running. @value{GDBN} uses the current listing position + to decide which macro definitions are in scope: + + @example + (gdb) list main + 3 + 4 #define M 42 + 5 #define ADD(x) (M + x) + 6 + 7 main () + 8 @{ + 9 #define N 28 + 10 printf ("Hello, world!\n"); + 11 #undef N + 12 printf ("We're so creative.\n"); + (gdb) show macro ADD + Defined at /home/jimb/gdb/macros/play/sample.c:5 + #define ADD(x) (M + x) + (gdb) show macro Q + Defined at /home/jimb/gdb/macros/play/sample.h:1 + included at /home/jimb/gdb/macros/play/sample.c:2 + #define Q < + (gdb) macro expand ADD(1) + expands to: (42 + 1) + (gdb) macro expand-once ADD(1) + expands to: once (M + 1) + (gdb) + @end example + + In the example above, note that @command{macro expand-once} expands only + the macro invocation explicit in the original text --- the invocation of + @code{ADD} --- but does not expand the invocation of the macro @code{M}, + which was introduced by @code{ADD}. + + Once the program is running, GDB uses the macro definitions in force at + the source line of the current stack frame: + + @example + (gdb) break main + Breakpoint 1 at 0x8048370: file sample.c, line 10. + (gdb) run + Starting program: /home/jimb/gdb/macros/play/sample + + Breakpoint 1, main () at sample.c:10 + 10 printf ("Hello, world!\n"); + (gdb) + @end example + + At line 10, the definition of the macro @code{N} at line 9 is in force: + + @example + (gdb) show macro N + Defined at /home/jimb/gdb/macros/play/sample.c:9 + #define N 28 + (gdb) macro expand N Q M + expands to: 28 < 42 + (gdb) print N Q M + $1 = 1 + (gdb) + @end example + + As we step over directives that remove @code{N}'s definition, and then + give it a new definition, @value{GDBN} finds the definition (or lack + thereof) in force at each point: + + @example + (gdb) next + Hello, world! + 12 printf ("We're so creative.\n"); + (gdb) show macro N + The symbol `N' has no definition as a C/C++ preprocessor macro + at /home/jimb/gdb/macros/play/sample.c:12 + (gdb) next + We're so creative. + 14 printf ("Goodbye, world!\n"); + (gdb) show macro N + Defined at /home/jimb/gdb/macros/play/sample.c:13 + #define N 1729 + (gdb) macro expand N Q M + expands to: 1729 < 42 + (gdb) print N Q M + $2 = 0 + (gdb) + @end example + @node Tracepoints @chapter Tracepoints