Re: stabs.texinfo update for macro define/undefine

David Taylor
2006-10-31T14:18:24Z

> 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).