[patch] doc: Document macros defined from command-line

[patch] doc: Document macros defined from command-line

[Jan Kratochvil]

Hi,

http://sourceware.org/ml/gdb-patches/2009-03/msg00026.html
On Tue, 03 Mar 2009 01:54:30 +0100, Joel Brobecker wrote:
> Regarding whether or not we should print line "0" or "command-line",
> in the absence of further comments from other contributors, I suggest
> we follow your approach of keeping this as is - but with some extra
> documentation just to make it clear what the zero means.  The
> documentation patch can be proposed separately from this patch, since
> it would document the existing behavior.

Here it is.


Thanks,
Jan


gdb/doc/
	* gdb.texinfo (Macros): A new part on coomand-line defined macros.

--- gdb/doc/gdb.texinfo	5 Mar 2009 23:11:11 -0000	1.561
+++ gdb/doc/gdb.texinfo	6 Mar 2009 20:41:17 -0000
@@ -8506,6 +8506,19 @@ $2 = 0
 (@value{GDBP})
 @end smallexample
 
+Printed definition line number will be zero for macros defined from the
+compiler command-line.  Unix compilers use the option @samp{-Dname=value} for
+such definitions.  @value{GDBN} displays in this case a name of the main source
+file being compiled when the macro has been defined:
+
+@smallexample
+(@value{GDBP}) info macro __STDC__
+(gdb) info macro __STDC__
+Defined at /home/jimb/gdb/macros/play/sample.c:0
+#define __STDC__ 1
+(@value{GDBP})
+@end smallexample
+
 
 @node Tracepoints
 @chapter Tracepoints

Re: [patch] doc: Document macros defined from command-line

[Eli Zaretskii]

> Date: Fri, 6 Mar 2009 21:46:31 +0100
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: Joel Brobecker <brobecker@adacore.com>
> 
> +Printed definition line number will be zero for macros defined from the
> +compiler command-line.  Unix compilers use the option @samp{-Dname=value} for
> +such definitions.  @value{GDBN} displays in this case a name of the main source
> +file being compiled when the macro has been defined:

I suggest to reword like this:

  In addition to source files, macros can be defined on the
  compilation command line using the @option{-D@var{name}=@var{value}}
  syntax.  For macros defined in such a way, @value{GDBN} displays the
  location of their definition as line zero of the source file
  submitted to the compiler.

The changes I made are:

  . Tell about the way of defining macros before describing what GDB
    does in that case.
  . Don't qualify the -Dfoo=bar feature by "Unix", since on non-Unix
    platforms GDB supports only GCC-produced debug info.
  . Use @var for meta-syntactic variables that stand for something
    else.

> +@smallexample
> +(@value{GDBP}) info macro __STDC__
> +(gdb) info macro __STDC__

I think this second line is redundant.  At least in my testing, GDB
does not display it.

> +Defined at /home/jimb/gdb/macros/play/sample.c:0
> +#define __STDC__ 1

Should we perhaps show "-D__STDC__=1" here?

Also, perhaps add a short notice of this feature at the beginning of
the section, where "info macro" is described.

Other than that, the patch is fine.

Thanks.

[patch] Better display command-line macros + doc addon [Re: [patch] doc: Document macros defined from command-line]

[Jan Kratochvil]

Hi,

this patch is unrelated to the discussed compiler/DWARF changes.
  http://sourceware.org/ml/gdb-patches/2009-02/threads.html#00397
  http://sourceware.org/ml/gdb-patches/2009-03/threads.html#00026
Just moved the testcase from it into this patch.


On Sat, 07 Mar 2009 10:16:10 +0100, Eli Zaretskii wrote:
>   . Tell about the way of defining macros before describing what GDB
>     does in that case.
>   . Don't qualify the -Dfoo=bar feature by "Unix", since on non-Unix
>     platforms GDB supports only GCC-produced debug info.
>   . Use @var for meta-syntactic variables that stand for something
>     else.

Understood, used your text.


> > +Defined at /home/jimb/gdb/macros/play/sample.c:0
> > +#define __STDC__ 1
> 
> Should we perhaps show "-D__STDC__=1" here?

Good idea, a code patch attached.


> Also, perhaps add a short notice of this feature at the beginning of
> the section, where "info macro" is described.

Made there the change.


Thanks,
Jan


gdb/
2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* macrocmd.c (info_macro_command): Print -Dname=value if LINE is zero.

gdb/doc/
2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* gdb.texinfo (Macros): Note command-line for `info macro'.  Append
	a new part on command-line defined macros.

gdb/testsuite/
2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* gdb.base/macscp.exp: New `options' parameter `-DFROM_COMMANDLINE'.
	(info_macro): Remova `decimal' declaration.  New variable `nonzero'.
	Replace all uses of `decimal' by `nonzero'.
	(info macro FROM_COMMANDLINE): New test.

--- gdb/macrocmd.c	3 Jan 2009 05:57:52 -0000	1.19
+++ gdb/macrocmd.c	9 Mar 2009 00:05:45 -0000
@@ -158,7 +158,10 @@ info_macro_command (char *name, int from
 
       fprintf_filtered (gdb_stdout, "Defined at ");
       show_pp_source_pos (gdb_stdout, file, line);
-      fprintf_filtered (gdb_stdout, "#define %s", name);
+      if (line != 0)
+	fprintf_filtered (gdb_stdout, "#define %s", name);
+      else
+	fprintf_filtered (gdb_stdout, "-D%s", name);
       if (d->kind == macro_function_like)
         {
           int i;
@@ -172,7 +175,10 @@ info_macro_command (char *name, int from
             }
           fputs_filtered (")", gdb_stdout);
         }
-      fprintf_filtered (gdb_stdout, " %s\n", d->replacement);
+      if (line != 0)
+	fprintf_filtered (gdb_stdout, " %s\n", d->replacement);
+      else
+	fprintf_filtered (gdb_stdout, "=%s\n", d->replacement);
     }
   else
     {
--- gdb/doc/gdb.texinfo	5 Mar 2009 23:11:11 -0000	1.561
+++ gdb/doc/gdb.texinfo	9 Mar 2009 00:05:56 -0000
@@ -8341,7 +8341,7 @@ can be any string of tokens.
 @cindex definition, showing a macro's
 @item info macro @var{macro}
 Show the definition of the macro named @var{macro}, and describe the
-source location where that definition was established.
+source location or compiler command-line where that definition was established.
 
 @kindex macro define
 @cindex user-defined macros
@@ -8506,6 +8506,18 @@ $2 = 0
 (@value{GDBP})
 @end smallexample
 
+In addition to source files, macros can be defined on the compilation command
+line using the @option{-D@var{name}=@var{value}} syntax.  For macros defined in
+such a way, @value{GDBN} displays the location of their definition as line zero
+of the source file submitted to the compiler.
+
+@smallexample
+(@value{GDBP}) info macro __STDC__
+Defined at /home/jimb/gdb/macros/play/sample.c:0
+-D__STDC__=1
+(@value{GDBP})
+@end smallexample
+
 
 @node Tracepoints
 @chapter Tracepoints
--- gdb/testsuite/gdb.base/macscp.exp	18 Feb 2009 22:24:37 -0000	1.20
+++ gdb/testsuite/gdb.base/macscp.exp	9 Mar 2009 00:05:57 -0000
@@ -26,7 +26,7 @@ set testfile "macscp"
 set objfile ${objdir}/${subdir}/${testfile}.o
 set binfile ${objdir}/${subdir}/${testfile}
 
-set options { debug }
+set options { debug additional_flags=-DFROM_COMMANDLINE=ARG}
 
 get_compiler_info ${binfile}
 if [test_compiler_info gcc*] {
@@ -67,19 +67,22 @@ gdb_load ${binfile}
 
 proc info_macro {macro} {
     global gdb_prompt
-    global decimal
 
     set filepat {macscp[0-9]+\.[ch]}
     set definition {}
     set location {}
 
+    # Line number zero is set for macros defined from the compiler command-line.
+    # Such macros are not being tested by this function.
+    set nonzero {[1-9][0-9]*}
+
     send_gdb "info macro ${macro}\n"
 
     set debug_me 0
 
     if {$debug_me} {exp_internal 1}
     gdb_expect {
-        -re "Defined at \[^\r\n\]*(${filepat}):${decimal}\[\r\n\]" {
+        -re "Defined at \[^\r\n\]*(${filepat}):${nonzero}\[\r\n\]" {
             # `location' and `definition' should be empty when we see
             # this message.
             if {[llength $location] == 0 && [llength $definition] == 0} {
@@ -101,7 +104,7 @@ proc info_macro {macro} {
                 set definition {}
             }
         }
-        -re "^\[\r\n\]*  included at \[^\r\n\]*(${filepat}):${decimal}\[\r\n\]" {
+        -re "^\[\r\n\]*  included at \[^\r\n\]*(${filepat}):${nonzero}\[\r\n\]" {
             # `location' should *not* be empty when we see this
             # message.  It should have recorded at least the initial
             # `Defined at ' message (for definitions) or ` at' message
@@ -114,7 +117,7 @@ proc info_macro {macro} {
                 set definition {}
             }
         }
-        -re "^\[\r\n\]*at \[^\r\n\]*(${filepat}):${decimal}\[\r\n\]" {
+        -re "^\[\r\n\]*at \[^\r\n\]*(${filepat}):${nonzero}\[\r\n\]" {
             # This appears after a `has no definition' message.
             # `location' should be empty when we see it.
             if {[string compare $definition undefined] == 0 \
@@ -205,6 +208,11 @@ list_and_check_macro macscp2_2 WHERE {ma
 list_and_check_macro macscp3_2 WHERE {macscp3.h macscp1.c {before macscp3_2}}
 
 
+# Assuming the current position inside program by `list' from above.
+gdb_test "info macro FROM_COMMANDLINE" \
+	 "Defined at \[^\r\n\]*:0\r\n-DFROM_COMMANDLINE=ARG"
+
+
 # Although GDB's macro table structures distinguish between multiple
 # #inclusions of the same file, GDB's other structures don't.  So the
 # `list' command here doesn't reliably select one #inclusion or the

Re: [patch] Better display command-line macros + doc addon [Re: [patch] doc: Document macros defined from command-line]

[Eli Zaretskii]

> Date: Mon, 9 Mar 2009 01:14:22 +0100
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: gdb-patches@sourceware.org, Joel Brobecker <brobecker@adacore.com>
> 
> On Sat, 07 Mar 2009 10:16:10 +0100, Eli Zaretskii wrote:
> >   . Tell about the way of defining macros before describing what GDB
> >     does in that case.
> >   . Don't qualify the -Dfoo=bar feature by "Unix", since on non-Unix
> >     platforms GDB supports only GCC-produced debug info.
> >   . Use @var for meta-syntactic variables that stand for something
> >     else.
> 
> Understood, used your text.
> 
> 
> > > +Defined at /home/jimb/gdb/macros/play/sample.c:0
> > > +#define __STDC__ 1
> > 
> > Should we perhaps show "-D__STDC__=1" here?
> 
> Good idea, a code patch attached.
> 
> 
> > Also, perhaps add a short notice of this feature at the beginning of
> > the section, where "info macro" is described.
> 
> Made there the change.

Thank you.

Re: [patch] Better display command-line macros + doc addon [Re: [patch] doc: Document macros defined from command-line]

[Joel Brobecker]

Jan,

Did we (ahem, I) drop the ball on you, on this patch? Sorry about that.
I don't think the change of output was particularly necessary, but I do
think it makes it easier to understand from the user's point of view:
No need to know what line 0 means in DWARF...

> gdb/
> 2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>
> 
> 	* macrocmd.c (info_macro_command): Print -Dname=value if LINE is zero.

> gdb/testsuite/
> 2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>
> 
> 	* gdb.base/macscp.exp: New `options' parameter `-DFROM_COMMANDLINE'.
> 	(info_macro): Remova `decimal' declaration.  New variable `nonzero'.
> 	Replace all uses of `decimal' by `nonzero'.
> 	(info macro FROM_COMMANDLINE): New test.

GDB and testsuite parts look OK to me. Thanks for doing this.

> gdb/doc/
> 2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>
> 
> 	* gdb.texinfo (Macros): Note command-line for `info macro'.  Append
> 	a new part on command-line defined macros.

I can't remember whether Eli approved the doco change or not, though.


-- 
Joel

Re: [patch] Better display command-line macros + doc addon [Re: [patch] doc: Document macros defined from command-line]

[Eli Zaretskii]

> Date: Tue, 28 Apr 2009 13:16:59 -0700
> From: Joel Brobecker <brobecker@adacore.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, gdb-patches@sourceware.org
> 
> > gdb/doc/
> > 2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>
> > 
> > 	* gdb.texinfo (Macros): Note command-line for `info macro'.  Append
> > 	a new part on command-line defined macros.
> 
> I can't remember whether Eli approved the doco change or not, though.

Yes, I did, on March 6th and again on the 9th.

Re: [patch] Better display command-line macros + doc addon [Re: [patch] doc: Document macros defined from command-line]

[Jan Kratochvil]

On Tue, 28 Apr 2009 22:16:59 +0200, Joel Brobecker wrote:
> > gdb/
> > 2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>
> > 
> > 	* macrocmd.c (info_macro_command): Print -Dname=value if LINE is zero.
> 
> > gdb/testsuite/
> > 2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>
> > 
> > 	* gdb.base/macscp.exp: New `options' parameter `-DFROM_COMMANDLINE'.
> > 	(info_macro): Remova `decimal' declaration.  New variable `nonzero'.
> > 	Replace all uses of `decimal' by `nonzero'.
> > 	(info macro FROM_COMMANDLINE): New test.
> 
> GDB and testsuite parts look OK to me. Thanks for doing this.
> 
> > gdb/doc/
> > 2009-03-09  Jan Kratochvil  <jan.kratochvil@redhat.com>
> > 
> > 	* gdb.texinfo (Macros): Note command-line for `info macro'.  Append
> > 	a new part on command-line defined macros.
> 
> I can't remember whether Eli approved the doco change or not, though.
On Wed, 29 Apr 2009 09:17:17 +0200, Eli Zaretskii wrote:
> Yes, I did, on March 6th and again on the 9th.

http://sourceware.org/ml/gdb-patches/2009-03/msg00108.html

Checked it in in its original form.
http://sourceware.org/ml/gdb-cvs/2009-04/msg00203.html


Thanks,
Jan