RFA: document macro support

RFA: document macro support

[Jim Blandy]

2002-05-13  Jim Blandy  <jimb@redhat.com>

	* 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	13 May 2002 23:32:03 -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 @samp{-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 @samp{-gdwarf-2} and @samp{-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
+ @samp{-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 @samp{-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 @code{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 @code{macro defined} 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 <stdio.h>
+ #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 @samp{-gdwarf-2} and @samp{-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 @code{expand-once} expands only the
+ macro invocation explicit in the original text --- the invocation of
+ @code{ADD} --- but does not expand the invocation of @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

Re: RFA: document macro support

[Neil Booth]

Jim Blandy wrote:-

> 
> 2002-05-13  Jim Blandy  <jimb@redhat.com>
> 
> 	* 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.

Hi Jim,

Just a minor nit: in GCC, we're quite picky now about using
@command and @option correctly.

Is there any progress on using libcpp, or is that on the back burner?

Neil.

Re: RFA: document macro support

[Jim Blandy]

Neil Booth <neil@daikokuya.demon.co.uk> writes:
> Jim Blandy wrote:-
> 
> > 
> > 2002-05-13  Jim Blandy  <jimb@redhat.com>
> > 
> > 	* 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.
> 
> Hi Jim,
> 
> Just a minor nit: in GCC, we're quite picky now about using
> @command and @option correctly.

I didn't even know those directives existed!  I'll read the texinfo
manual, and post a revised patch shortly.

> Is there any progress on using libcpp, or is that on the back burner?

Well, first libcpp needs to be disentangled from GCC.  Right now it
shares its configury and build files with GCC, and lives in the `gcc'
directory.  All of this makes it rather difficult to share libcpp
between the gcc and sourceware repositories.  Zack W. has volunteered
to disintegrate libcpp, but apparently the 3.2 release process hinders
this.

I'll be posting GDB tests for the macro support in the next few days.
They will include tests for the bugs you pointed out in my macro
expander, so the issues with token marking won't be forgotten.

Re: RFA: document macro support

[Neil Booth]

Jim Blandy wrote:-

> > Is there any progress on using libcpp, or is that on the back burner?
> 
> Well, first libcpp needs to be disentangled from GCC.  Right now it
> shares its configury and build files with GCC, and lives in the `gcc'
> directory.  All of this makes it rather difficult to share libcpp
> between the gcc and sourceware repositories.  Zack W. has volunteered
> to disintegrate libcpp, but apparently the 3.2 release process hinders
> this.
> 
> I'll be posting GDB tests for the macro support in the next few days.
> They will include tests for the bugs you pointed out in my macro
> expander, so the issues with token marking won't be forgotten.

OK, great.  IIRC Zack indicated he might be able to move CPP before
3.2, but let's see.  I have no idea if he has time.

Neil.

Re: RFA: document macro support

[Eli Zaretskii]

> From: Jim Blandy <jimb@redhat.com>
> Date: 14 May 2002 15:03:48 -0500
> 
> > Just a minor nit: in GCC, we're quite picky now about using
> > @command and @option correctly.
> 
> I didn't even know those directives existed!  I'll read the texinfo
> manual, and post a revised patch shortly.

Jim, you are welcome to use those directives, now that we require
Texinfo 4.0 or later, but AFAIK there's no policy in GDB to disallow
use of their older equivalents.

Your docs patch is approved.  Sorry I didn't do that before, we had a
nasty problem with our mail server down here, so I never knew about
your original message until now (had to catch up via list archives).

Re: RFA: document macro support

[Jim Blandy]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:
> Your docs patch is approved.  Sorry I didn't do that before, we had a
> nasty problem with our mail server down here, so I never knew about
> your original message until now (had to catch up via list archives).

No problem.  I'll commit them when the corresponding code is
completely committed.  I'm letting each patch sit for a week before
committing it, unless there's discussion.

Re: RFA: document macro support

[Jim Blandy]

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  <jimb@redhat.com>

	* 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 <stdio.h>
+ #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

Re: RFA: document macro support

[Andrew Cagney]

+ @example

Btw, that should be @smallexample.

enjoy.
Andrew

Re: RFA: document macro support

[Eli Zaretskii]

> Date: Tue, 14 May 2002 17:27:03 -0400
> From: Andrew Cagney <ac131313@cygnus.com>
> 
> + @example
> 
> Btw, that should be @smallexample.

True; but in this case, the lines are so short that it doesn't
matter, I think.

Re: RFA: document macro support

[Jim Blandy]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:

> > Date: Tue, 14 May 2002 17:27:03 -0400
> > From: Andrew Cagney <ac131313@cygnus.com>
> > 
> > + @example
> > 
> > Btw, that should be @smallexample.
> 
> True; but in this case, the lines are so short that it doesn't
> matter, I think.

If you want me to change it, I'll be happy to do so.  The lines in the
examples do generally seem short, though.

Re: RFA: document macro support

[Eli Zaretskii]

On 15 May 2002, Jim Blandy wrote:

> > > Btw, that should be @smallexample.
> > 
> > True; but in this case, the lines are so short that it doesn't
> > matter, I think.
> 
> If you want me to change it, I'll be happy to do so.  The lines in the
> examples do generally seem short, though.

Andrew pointed out that the manual uses smallexample throughout, so 
please do change that.

Re: RFA: document macro support

[Jim Blandy]

Eli Zaretskii <eliz@is.elta.co.il> writes:

> On 15 May 2002, Jim Blandy wrote:
> 
> > > > Btw, that should be @smallexample.
> > > 
> > > True; but in this case, the lines are so short that it doesn't
> > > matter, I think.
> > 
> > If you want me to change it, I'll be happy to do so.  The lines in the
> > examples do generally seem short, though.
> 
> Andrew pointed out that the manual uses smallexample throughout, so 
> please do change that.

Okay.  Here is the revised patch:

2002-05-13  Jim Blandy  <jimb@redhat.com>

	* gdb.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.99
diff -c -r1.99 gdb.texinfo
*** gdb/doc/gdb.texinfo	14 May 2002 04:26:25 -0000	1.99
--- gdb/doc/gdb.texinfo	16 May 2002 20:40:16 -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,4436 ----
  @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 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 ****
--- 5787,6016 ----
  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:
+ 
+ @smallexample
+ $ cat sample.c
+ #include <stdio.h>
+ #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 smallexample
+ 
+ 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.
+ 
+ @smallexample
+ $ gcc -gdwarf-2 -g3 sample.c -o sample
+ $
+ @end smallexample
+ 
+ Now, we start @value{GDBN} on our sample program:
+ 
+ @smallexample
+ $ gdb -nw sample
+ GNU gdb 2002-05-06-cvs
+ Copyright 2002 Free Software Foundation, Inc.
+ GDB is free software, @dots{}
+ (gdb)
+ @end smallexample
+ 
+ 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:
+ 
+ @smallexample
+ (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 smallexample
+ 
+ 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:
+ 
+ @smallexample
+ (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 smallexample
+ 
+ At line 10, the definition of the macro @code{N} at line 9 is in force:
+ 
+ @smallexample
+ (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 smallexample
+ 
+ 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:
+ 
+ @smallexample
+ (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 smallexample
+ 
  
  @node Tracepoints
  @chapter Tracepoints

Re: RFA: document macro support

[Eli Zaretskii]

> From: Jim Blandy <jimb@redhat.com>
> Date: 16 May 2002 15:42:43 -0500
> 
> Eli Zaretskii <eliz@is.elta.co.il> writes:
> 
> > Andrew pointed out that the manual uses smallexample throughout, so 
> > please do change that.
> 
> Okay.  Here is the revised patch:
> 
> 2002-05-13  Jim Blandy  <jimb@redhat.com>

Thanks, please commit this.

Re: RFA: document macro support

[Jim Blandy]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:

> > From: Jim Blandy <jimb@redhat.com>
> > Date: 16 May 2002 15:42:43 -0500
> > 
> > Eli Zaretskii <eliz@is.elta.co.il> writes:
> > 
> > > Andrew pointed out that the manual uses smallexample throughout, so 
> > > please do change that.
> > 
> > Okay.  Here is the revised patch:
> > 
> > 2002-05-13  Jim Blandy  <jimb@redhat.com>
> 
> Thanks, please commit this.

Committed.

Re: RFA: document macro support

[Eli Zaretskii]

> From: Jim Blandy <jimb@redhat.com>
> Date: 14 May 2002 16:15:28 -0500
> 
> Here is a revised macro documentation patch that uses @option and
> @command where appropriate, and makes some other minor revisions.

Approved, thanks.

> I've noticed that these directives aren't used elsewhere in GDB's
> documentation; is there any policy on their use?

They are not used because those directives were introduced in Texinfo
4.0, and before GDB 5.1, the manuals didn't require anything newer
than Texinfo 3.12 to build.

> 2002-05-13  Jim Blandy  <jimb@redhat.com>
> 
> 	* gdbint.texinfo (C Preprocessor Macros): New chapter.
          ^^^^^^^^^^^^^^
That's not the file you are patching ;-)

Re: RFA: document macro support

[Jim Blandy]

"Eli Zaretskii" <eliz@is.elta.co.il> writes:
> > 2002-05-13  Jim Blandy  <jimb@redhat.com>
> > 
> > 	* gdbint.texinfo (C Preprocessor Macros): New chapter.
>           ^^^^^^^^^^^^^^
> That's not the file you are patching ;-)

Ah!  Force of habit.  Thank you.