Re: stabs.texinfo update for macro define/undefine

Re: stabs.texinfo update for macro define/undefine

[David Taylor]

Patch to add information about recording macro define and undefine
information in stabs.

Index: stabs.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/stabs.texinfo,v
retrieving revision 1.18
diff -u -r1.18 stabs.texinfo
--- stabs.texinfo	2 Aug 2006 03:31:21 -0000	1.18
+++ stabs.texinfo	30 Oct 2006 22:19:10 -0000
@@ -67,6 +67,7 @@
 * Constants::			Constants
 * Variables::
 * Types::			Type definitions
+* Macro define and undefine::   Representation of #define and #undef
 * Symbol Tables::		Symbol information in symbol tables
 * Cplusplus::			Stabs specific to C++
 * Stab Types::			Symbol types in a.out files
@@ -2220,6 +2221,69 @@
 The variable defines a new type, 24, which is a pointer to another new
 type, 25, which is a function returning @code{int}.
 
+@node Macro define and undefine
+@chapter Representation of #define and #undef
+
+Macro define and undefine.
+
+This section describes the stabs support for macro define and undefine
+information, supported on some systems.  (e.g., with -g3 -gstabs when
+using gcc).
+
+A @code{#define @var{macro-name} @var{macro-body}} is represented with
+an @code{N_MAC_DEFINE} stab with a string field of
+@code{@var{macro-name} @var{macro-body}}.
+@findex N_MAC_DEFINE
+
+An @code{#undef @var{macro-name}} is represented with an
+@code{N_MAC_UNDEF} stabs with a string field of simply
+@code{@var{macro-name}}.
+@findex N_MAC_UNDEF
+
+For both @code{N_MAC_DEFINE} and @code{N_MAC_UNDEF}, the desc field is
+the line number within the file where the corresponding @code{#define}
+or @code{#undef} occurred.
+@findex N_MAC_DEFINE
+@findex N_MAC_UNDEF
+
+For example, the following C code:
+
+@example
+    #define NONE	42
+    #define TWO(a, b)	(a + (a) + 2 * b)
+    #define ONE(c)	(c + 19)
+
+    main(int argc, char *argv[])
+    @{
+      func(NONE, TWO(10, 11));
+      func(NONE, ONE(23));
+
+    #undef ONE
+    #define ONE(c)	(c + 23)
+
+      func(NONE, ONE(-23));
+
+      return (0);
+    @}
+
+    int global;
+
+    func(int arg1, int arg2)
+    @{
+      global = arg1 + arg2;
+    @}
+@end example
+
+produces the following stabs (as well as many others):
+
+@example
+    .stabs	"NONE 42",54,0,1,0                      # 54 is N_MAC_DEFINE
+    .stabs	"TWO(a,b) (a + (a) + 2 * b)",54,0,2,0   # 54 is N_MAC_DEFINE
+    .stabs	"ONE(c) (c + 19)",54,0,3,0              # 54 is N_MAC_DEFINE
+    .stabs	"ONE",58,0,10,0                         # 58 is N_MAC_UNDEF
+    .stabs	"ONE(c) (c + 23)",54,0,11,0             # 54 is N_MAC_DEFINE
+@end example
+
 @node Symbol Tables
 @chapter Symbol Information in Symbol Tables
 
@@ -3276,11 +3340,17 @@
 @item 0x34     N_NOMAP
 No DST map; see @ref{N_NOMAP}.
 
+@item 0x36     N_MAC_DEFINE
+Name and body of a @code{#define}d macro; see @ref{Macro define and undefine}.
+
 @c FIXME: describe this solaris feature in the body of the text (see
 @c comments in include/aout/stab.def).
 @item 0x38 N_OBJ
 Object file (Solaris2).
 
+@item 0x3a     N_MAC_UNDEF
+Name of an @code{#undef}ed macro; see @ref{Macro define and undefine}.
+
 @c See include/aout/stab.def for (a little) more info.
 @item 0x3c N_OPT
 Debugger options (Solaris2).

Re: stabs.texinfo update for macro define/undefine

[Eli Zaretskii]

> cc: Eli Zaretskii <eliz@gnu.org>
> Date: Mon, 30 Oct 2006 17:25:21 -0500
> From: David Taylor <dtaylor@emc.com>
> 
> Patch to add information about recording macro define and undefine
> information in stabs.

Thanks.

> +@node Macro define and undefine
> +@chapter Representation of #define and #undef
> +
> +Macro define and undefine.

This last sentence is redundant (and actually isn't even a sentence).

> +information, supported on some systems.  (e.g., with -g3 -gstabs when

Please put command-line options in @option.

> +using gcc).

Please use GCC instead of gcc.

> +A @code{#define @var{macro-name} @var{macro-body}} is represented with
> +an @code{N_MAC_DEFINE} stab with a string field of
> +@code{@var{macro-name} @var{macro-body}}.
> +@findex N_MAC_DEFINE
> +
> +An @code{#undef @var{macro-name}} is represented with an
> +@code{N_MAC_UNDEF} stabs with a string field of simply
> +@code{@var{macro-name}}.
> +@findex N_MAC_UNDEF
> +
> +For both @code{N_MAC_DEFINE} and @code{N_MAC_UNDEF}, the desc field is
> +the line number within the file where the corresponding @code{#define}
> +or @code{#undef} occurred.
> +@findex N_MAC_DEFINE
> +@findex N_MAC_UNDEF

It is not useful to have two identical index entries that point to the
same page.  In this case, I don't see the need for the second pair of
@findex entries here.

> +@end example
> +
> +produces the following stabs (as well as many others):

You need a @noindent before this line, since you don't want it to be
indented as if it were a new paragraph.

> +@example
> +    .stabs	"NONE 42",54,0,1,0                      # 54 is N_MAC_DEFINE
> +    .stabs	"TWO(a,b) (a + (a) + 2 * b)",54,0,2,0   # 54 is N_MAC_DEFINE
> +    .stabs	"ONE(c) (c + 19)",54,0,3,0              # 54 is N_MAC_DEFINE
> +    .stabs	"ONE",58,0,10,0                         # 58 is N_MAC_UNDEF
> +    .stabs	"ONE(c) (c + 23)",54,0,11,0             # 54 is N_MAC_DEFINE
> +@end example

These lines are too long: they will overflow the page margin in the
printed version of the manual.  I suggest to remove the comments and
instead explain the meaning of the constants in a separate text.
(Didn't I tell you this when you first posted the suggested text?)

Please also post the ChangeLog entry for the patch.

With these changes, this can go in.  Thanks.

Re: stabs.texinfo update for macro define/undefine

[David Taylor]

> Date: Tue, 31 Oct 2006 06:19:33 +0200
> Message-Id: <uejsp6rsa.fsf@gnu.org>
> From: Eli Zaretskii <eliz@gnu.org>
> To: David Taylor <dtaylor@emc.com>
> Cc: gdb-patches@sourceware.org
> 
> > cc: Eli Zaretskii <eliz@gnu.org>
> > Date: Mon, 30 Oct 2006 17:25:21 -0500
> > From: David Taylor <dtaylor@emc.com>
> > 
> > Patch to add information about recording macro define and undefine
> > information in stabs.
> 
> Thanks.

You're welcome.

> > +@node Macro define and undefine
> > +@chapter Representation of #define and #undef
> > +
> > +Macro define and undefine.
> 
> This last sentence is redundant (and actually isn't even a sentence).

Deleted.

> > +information, supported on some systems.  (e.g., with -g3 -gstabs when
> 
> Please put command-line options in @option.

Done.

> > +using gcc).
> 
> Please use GCC instead of gcc.

Done.

> > +A @code{#define @var{macro-name} @var{macro-body}} is represented with
> > +an @code{N_MAC_DEFINE} stab with a string field of
> > +@code{@var{macro-name} @var{macro-body}}.
> > +@findex N_MAC_DEFINE
> > +
> > +An @code{#undef @var{macro-name}} is represented with an
> > +@code{N_MAC_UNDEF} stabs with a string field of simply
> > +@code{@var{macro-name}}.
> > +@findex N_MAC_UNDEF
> > +
> > +For both @code{N_MAC_DEFINE} and @code{N_MAC_UNDEF}, the desc field is
> > +the line number within the file where the corresponding @code{#define}
> > +or @code{#undef} occurred.
> > +@findex N_MAC_DEFINE
> > +@findex N_MAC_UNDEF
> 
> It is not useful to have two identical index entries that point to the
> same page.  In this case, I don't see the need for the second pair of
> @findex entries here.

In case the second chunk of text ended up on a different page than the
first chunk.  I'll delete it.

> > +@end example
> > +
> > +produces the following stabs (as well as many others):
> 
> You need a @noindent before this line, since you don't want it to be
> indented as if it were a new paragraph.

Done.

> > +@example
> > +    .stabs	"NONE 42",54,0,1,0                      # 54 is N_MAC_DEFINE
> > +    .stabs	"TWO(a,b) (a + (a) + 2 * b)",54,0,2,0   # 54 is N_MAC_DEFINE
> > +    .stabs	"ONE(c) (c + 19)",54,0,3,0              # 54 is N_MAC_DEFINE
> > +    .stabs	"ONE",58,0,10,0                         # 58 is N_MAC_UNDEF
> > +    .stabs	"ONE(c) (c + 23)",54,0,11,0             # 54 is N_MAC_DEFINE
> > +@end example
> 
> These lines are too long: they will overflow the page margin in the
> printed version of the manual.  I suggest to remove the comments and
> instead explain the meaning of the constants in a separate text.
> (Didn't I tell you this when you first posted the suggested text?)

You mentioned it, but I guess I misunderstood.  I ran both `make dvi'
and `make info' and looked at the resulting files.  The info file
stayed in fewer than 80 columns; I didn't see any TeX complaints about
an overfull hbox, nor did the dvi file have a black box on any of
those lines.  So, I guessed that they looked too long but were
actually okay.

In the future, how should I test to make sure that the lines are not
too long?

For this, how about:

    @example
        .stabs  "NONE 42",54,0,1,0
        .stabs  "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0
        .stabs  "ONE(c) (c + 19)",54,0,3,0
        .stabs  "ONE",58,0,10,0
        .stabs  "ONE(c) (c + 23)",54,0,11,0
    @end example

    NOTE: In the example above, @code{54} is @code{N_MAC_DEFINE} and @code{58}
    is @code{N_MAC_UNDEF}.

?  This is the text in the patch attached below.

> Please also post the ChangeLog entry for the patch.

Done.

> With these changes, this can go in.  Thanks.

Thanks.  I don't have write after approval privileges.

Here's an updated patch:

gdb/doc/ChangeLog entry:

2006-10-31  David Taylor  <dtaylor@emc.com>

	* stabs.texinfo (Macro define and undefine): New node describing
	stabs for #define and #undef.

Index: stabs.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/stabs.texinfo,v
retrieving revision 1.18
diff -u -r1.18 stabs.texinfo
--- stabs.texinfo	2 Aug 2006 03:31:21 -0000	1.18
+++ stabs.texinfo	31 Oct 2006 14:12:55 -0000
@@ -67,6 +67,7 @@
 * Constants::			Constants
 * Variables::
 * Types::			Type definitions
+* Macro define and undefine::	Representation of #define and #undef
 * Symbol Tables::		Symbol information in symbol tables
 * Cplusplus::			Stabs specific to C++
 * Stab Types::			Symbol types in a.out files
@@ -2220,6 +2221,70 @@
 The variable defines a new type, 24, which is a pointer to another new
 type, 25, which is a function returning @code{int}.
 
+@node Macro define and undefine
+@chapter Representation of #define and #undef
+
+This section describes the stabs support for macro define and undefine
+information, supported on some systems.  (e.g., with @option{-g3}
+@option{-gstabs} when using GCC).
+
+A @code{#define @var{macro-name} @var{macro-body}} is represented with
+an @code{N_MAC_DEFINE} stab with a string field of
+@code{@var{macro-name} @var{macro-body}}.
+@findex N_MAC_DEFINE
+
+An @code{#undef @var{macro-name}} is represented with an
+@code{N_MAC_UNDEF} stabs with a string field of simply
+@code{@var{macro-name}}.
+@findex N_MAC_UNDEF
+
+For both @code{N_MAC_DEFINE} and @code{N_MAC_UNDEF}, the desc field is
+the line number within the file where the corresponding @code{#define}
+or @code{#undef} occurred.
+
+For example, the following C code:
+
+@example
+    #define NONE	42
+    #define TWO(a, b)	(a + (a) + 2 * b)
+    #define ONE(c)	(c + 19)
+
+    main(int argc, char *argv[])
+    @{
+      func(NONE, TWO(10, 11));
+      func(NONE, ONE(23));
+
+    #undef ONE
+    #define ONE(c)	(c + 23)
+
+      func(NONE, ONE(-23));
+
+      return (0);
+    @}
+
+    int global;
+
+    func(int arg1, int arg2)
+    @{
+      global = arg1 + arg2;
+    @}
+@end example
+
+@noindent
+produces the following stabs (as well as many others):
+
+@example
+    .stabs	"NONE 42",54,0,1,0
+    .stabs	"TWO(a,b) (a + (a) + 2 * b)",54,0,2,0
+    .stabs	"ONE(c) (c + 19)",54,0,3,0
+    .stabs	"ONE",58,0,10,0
+    .stabs	"ONE(c) (c + 23)",54,0,11,0
+@end example
+
+@noindent
+NOTE: In the above example, @code{54} is @code{N_MAC_DEFINE} and
+@code{58} is @code{N_MAC_UNDEF}.
+
 @node Symbol Tables
 @chapter Symbol Information in Symbol Tables
 
@@ -3276,11 +3341,17 @@
 @item 0x34     N_NOMAP
 No DST map; see @ref{N_NOMAP}.
 
+@item 0x36     N_MAC_DEFINE
+Name and body of a @code{#define}d macro; see @ref{Macro define and undefine}.
+
 @c FIXME: describe this solaris feature in the body of the text (see
 @c comments in include/aout/stab.def).
 @item 0x38 N_OBJ
 Object file (Solaris2).
 
+@item 0x3a     N_MAC_UNDEF
+Name of an @code{#undef}ed macro; see @ref{Macro define and undefine}.
+
 @c See include/aout/stab.def for (a little) more info.
 @item 0x3c N_OPT
 Debugger options (Solaris2).

Re: stabs.texinfo update for macro define/undefine

[Eli Zaretskii]

> cc: gdb-patches@sourceware.org
> Date: Tue, 31 Oct 2006 09:18:03 -0500
> From: David Taylor <dtaylor@emc.com>
> 
> You mentioned it, but I guess I misunderstood.  I ran both `make dvi'
> and `make info' and looked at the resulting files.  The info file
> stayed in fewer than 80 columns; I didn't see any TeX complaints about
> an overfull hbox, nor did the dvi file have a black box on any of
> those lines.  So, I guessed that they looked too long but were
> actually okay.

Maybe due to whitespace TeX succeeded to squeeze them in.

> In the future, how should I test to make sure that the lines are not
> too long?

Any line longer than 64 characters in an @example should be shortened.

> For this, how about:
> 
>     @example
>         .stabs  "NONE 42",54,0,1,0
>         .stabs  "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0
>         .stabs  "ONE(c) (c + 19)",54,0,3,0
>         .stabs  "ONE",58,0,10,0
>         .stabs  "ONE(c) (c + 23)",54,0,11,0
>     @end example
> 
>     NOTE: In the example above, @code{54} is @code{N_MAC_DEFINE} and @code{58}
>     is @code{N_MAC_UNDEF}.
> 
> ?  This is the text in the patch attached below.

This is fine; it's exactly what I was suggesting.

> > With these changes, this can go in.  Thanks.
> 
> Thanks.  I don't have write after approval privileges.

I committed the patch for you.  Thanks again for working on this.

Re: stabs.texinfo update for macro define/undefine

[Jim Blandy]

It's clear from the example, but it would be nice if the text
explicitly explained how function-like macro arguments appear in the
N_MAC_DEFINE stabs.  It also should explain how the following are
distinguished:

#define foo x
#define foo() x

With the latter #definition, 'foo' followed by something other than an
opening parenthesis isn't replaced.

Re: stabs.texinfo update for macro define/undefine

[David Taylor]

> From: Jim Blandy <jimb@codesourcery.com>
> Date: Tue, 31 Oct 2006 15:23:29 -0800
> 
> It's clear from the example, but it would be nice if the text
> explicitly explained how function-like macro arguments appear in the
> N_MAC_DEFINE stabs.  It also should explain how the following are
> distinguished:
> 
> #define foo x
> #define foo() x
> 
> With the latter #definition, 'foo' followed by something other than an
> opening parenthesis isn't replaced.

The former shows up as "foo x", the latter as "foo() x".

Yes, the example could be enhanced to illustrate that.  And a little
more about the ``transformation'' from what is found in the *.c file
to the stabs entry.

But, as to the latter -- am I misunderstanding you?  Are you asking
for text about when something is replaced versus when it isn't
replaced?  If yes, that is *WAY* beyond the scope of the file.  The
file deals exclusively with *STABS*.  When something is replaced vs
not replaced is a CPP issue.  It has nothing to do with STABS.

Re: stabs.texinfo update for macro define/undefine

[Jim Blandy]

David Taylor <dtaylor@emc.com> writes:
>> From: Jim Blandy <jimb@codesourcery.com>
>> Date: Tue, 31 Oct 2006 15:23:29 -0800
>> 
>> It's clear from the example, but it would be nice if the text
>> explicitly explained how function-like macro arguments appear in the
>> N_MAC_DEFINE stabs.  It also should explain how the following are
>> distinguished:
>> 
>> #define foo x
>> #define foo() x
>> 
>> With the latter #definition, 'foo' followed by something other than an
>> opening parenthesis isn't replaced.
>
> The former shows up as "foo x", the latter as "foo() x".
>
> Yes, the example could be enhanced to illustrate that.  And a little
> more about the ``transformation'' from what is found in the *.c file
> to the stabs entry.
>
> But, as to the latter -- am I misunderstanding you?  Are you asking
> for text about when something is replaced versus when it isn't
> replaced?  If yes, that is *WAY* beyond the scope of the file.  The
> file deals exclusively with *STABS*.  When something is replaced vs
> not replaced is a CPP issue.  It has nothing to do with STABS.

No, of course not --- we both agree that your text only needs to
describe how to convey all the possible sorts of preprocessor macro
definitions accurately from the compiler to the debugger in STABS.  I
just had two points:

- I think the text ought to actually state all the rules needed to do
  the job correctly, and not leave details to examples.

- There are some cases your examples didn't cover.  (Of course, what's
  a separate case and what's just a specialization of a more general
  thing is sort of a matter of taste.  But it was something I remember
  running into when I did the existing DWARF macro code, so I thought
  I'd mention it.)