Patchwork [doc] compile: missing bits [Re: [PATCH v2 7/9] compile: New 'compile print']

login
register
mail settings
Submitter Jan Kratochvil
Date April 9, 2015, 5:39 p.m.
Message ID <20150409173950.GA3400@host1.jankratochvil.net>
Download mbox | patch
Permalink /patch/6118/
State New
Headers show

Comments

Jan Kratochvil - April 9, 2015, 5:39 p.m.
Hi Eli,

On Thu, 09 Apr 2015 09:39:46 +0200, Eli Zaretskii wrote:
> So I think we should tell the story in the manual, yes.

there were various missing bits for the 'compile' feature so adding them here.


Thanks,
Jan
gdb/doc/
2015-04-09  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* gdb.texinfo (Compiling and Injecting Code): Describe set debug 
	compile, show debug compile.  New subsection Compilation options for 
	the compile command.  New subsection Compiler search for the compile
	command.
Eli Zaretskii - April 9, 2015, 6:12 p.m.
> Date: Thu, 9 Apr 2015 19:39:50 +0200
> From: Jan Kratochvil <jan.kratochvil@redhat.com>
> Cc: Paul_Koning@dell.com, gdb-patches@sourceware.org, pmuldoon@redhat.com
> 
> On Thu, 09 Apr 2015 09:39:46 +0200, Eli Zaretskii wrote:
> > So I think we should tell the story in the manual, yes.
> 
> there were various missing bits for the 'compile' feature so adding them here.

Thanks.

> +@value{GDBN} needs to specify the right compilation options for the code
> +to be injected.  In part to make its ABI compatible with the inferior
> +and in part to make the injected code compatible with GDB's injecting
> +process.

The second sentence is not a complete sentence; suggest to make it
part of the first (as in "...to be injected, in part to make its
ABI...").

Also, there's a bare "GDB" there.

> +@value{NGCC} (since version 4.7) stores the options used for compilation
> +into @code{DW_AT_producer} part of DWARF debugging information according
> +to the @value{NGCC} option @code{-grecord-gcc-switches}.  One has to
> +explicitly specify @code{-g} during inferior compilation otherwise
> +@value{NGCC} produces no DWARF.

Hmm...  Are you sure -g always produces DWARF?  Maybe we should say
that for targets where DWARF is not the default, -gdwarf-N should be
used, and also that -gstabs etc. should _not_ be used?

> +@item set compile-args
> +@value{GDBN} contains default compilation options to set and possibly
> +override the options required for proper injection of the compiled code.
> +@end table
> +
> +@noindent
> +The options mentioned last can be specified with command:
> +
> +@table @code
> +@item set compile-args

This is slightly confusing.  I suggest the following text instead:

 @item compilation options set by @code{set compile-args}
 @end table

 @noindent
 You can override compilation options using the following command:

 @table @code
 @item set compile-args
 @cindex compile command options override
 Set compilation options used for compiling and injecting code with the
 @code{compile} commands.  These options override any conflicting ones
 from the target architecture and/or options stored during inferior
 compilation.
 
 @item show compile-args
 Displays the current state of compilation options override.
 This does not show all the options actually used during compilation,
 use @ref{set debug compile} for that.
 @end table

> +@value{GDBN} needs to find @value{NGCC} for the inferior being debugged which
> +may not be obvious for remote targets of different architecture than where
> +@value{GDBN} is running.  Environment variable @code{PATH} (@code{PATH} from
> +shell that executed @value{GDBN}, not the one set by @value{GDBN}
> +command @code{set environment}.  @xref{Environment}.  @code{PATH} on

There's a right parenthesis missing here.

> +Specifically @code{PATH} is searched for binaries matching regular expression
> +@code{@var{ARCH}(-[^-]*)?-@var{OS}-gcc} according to the inferior target being
> +debugged.  @code{@var{ARCH}} is processor name - multiarch is supported,

Please don't up-case ARCH and OS, makeinfo will do that when needed.

Also, please use "---" instead of just one dash.

> +for pattern @code{s390x?}.  @code{OS} is currently supported only for
>                              ^^^^^^^^^

@var{os}.

Patch

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index d794893..ac50ea8 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -17223,6 +17223,66 @@  compile file /home/user/example.c
 @end smallexample
 @end table
 
+@noindent
+The process of compiling and injecting the code can be inspected using:
+
+@table @code
+@anchor{set debug compile}
+@item set debug compile
+@cindex compile command debugging info
+Turns on or off display of @value{GDBN} process of compiling and
+injecting the code.  The default is off.
+
+@item show debug compile
+Displays the current state of displaying @value{GDBN} process of
+compiling and injecting the code.
+@end table
+
+@subsection Compilation options for the @code{compile} command
+
+@value{GDBN} needs to specify the right compilation options for the code
+to be injected.  In part to make its ABI compatible with the inferior
+and in part to make the injected code compatible with GDB's injecting
+process.
+
+@noindent
+The options used, in increasing precedence:
+
+@table @asis
+@item target architecture and OS options (@code{gdbarch})
+These options depend on target processor type and target operating
+system, usually they specify at least 32-bit (@code{-m32}) or 64-bit
+(@code{-m64}) compilation option.
+
+@item compilation options recorded in the target
+@value{NGCC} (since version 4.7) stores the options used for compilation
+into @code{DW_AT_producer} part of DWARF debugging information according
+to the @value{NGCC} option @code{-grecord-gcc-switches}.  One has to
+explicitly specify @code{-g} during inferior compilation otherwise
+@value{NGCC} produces no DWARF.
+
+@item set compile-args
+@value{GDBN} contains default compilation options to set and possibly
+override the options required for proper injection of the compiled code.
+@end table
+
+@noindent
+The options mentioned last can be specified with command:
+
+@table @code
+@item set compile-args
+@cindex compile command options override
+Set compilation options used for compiling and injecting code with the
+@code{compile} commands.  These options override any conflicting ones
+from the target architecture and/or options stored during inferior
+compilation.
+
+@item show compile-args
+Displays the current state of compilation options override.
+This does not show all the options actually used during compilation,
+use @ref{set debug compile} for that.
+@end table
+
 @subsection Caveats when using the @code{compile} command
 
 There are a few caveats to keep in mind when using the @code{compile}
@@ -17380,6 +17440,24 @@  Access to those variables will generate a compiler error which @value{GDBN}
 will print to the console.
 @end table
 
+@subsection Compiler search for the @code{compile} command
+
+@value{GDBN} needs to find @value{NGCC} for the inferior being debugged which
+may not be obvious for remote targets of different architecture than where
+@value{GDBN} is running.  Environment variable @code{PATH} (@code{PATH} from
+shell that executed @value{GDBN}, not the one set by @value{GDBN}
+command @code{set environment}.  @xref{Environment}.  @code{PATH} on
+@value{GDBN} host is searched for @value{NGCC} binary matching the
+target architecture and operating system.
+
+Specifically @code{PATH} is searched for binaries matching regular expression
+@code{@var{ARCH}(-[^-]*)?-@var{OS}-gcc} according to the inferior target being
+debugged.  @code{@var{ARCH}} is processor name - multiarch is supported,
+so for example both @code{i386} and @code{x86_64} targets look for pattern
+@code{(x86_64|i.86)} and both @code{s390} and @code{s390x} targets look
+for pattern @code{s390x?}.  @code{OS} is currently supported only for
+pattern @code{linux(-gnu)?}.
+
 @node GDB Files
 @chapter @value{GDBN} Files