[PATCH] expand -fdebug-prefix-map documentation

[PATCH] expand -fdebug-prefix-map documentation

[Jim Wilson]

[-- Attachment #1: Type: text/plain, Size: 334 bytes --]

The current documentation doesn't explain what the option is for, or
how one might use it.  The attached patch expands the documentation a
bit to try to explain this.

Tested with a make doc, and verifying that the gcc.info file looks OK.
 And tested by verifying that the option works the way I think it does..

OK?

Jim

[-- Attachment #2: debug-prefix-map.txt --]
[-- Type: text/plain, Size: 1028 bytes --]

2017-10-25  Jim Wilson  <wilson@tuliptree.org>

	gcc/
	* doc/invoke.texi (-fdebug-prefix-map): Expand documentation.

Index: gcc/doc/invoke.texi
===================================================================
--- gcc/doc/invoke.texi	(revision 254023)
+++ gcc/doc/invoke.texi	(working copy)
@@ -6981,7 +6981,12 @@ link processing time.  Merging is enabled by defau
 @item -fdebug-prefix-map=@var{old}=@var{new}
 @opindex fdebug-prefix-map
 When compiling files in directory @file{@var{old}}, record debugging
-information describing them as in @file{@var{new}} instead.
+information describing them as in @file{@var{new}} instead.  This can be
+used to replace a build time path with an install time path in the debug info.
+It can also be used to change an absolute path to a relative path by using
+@file{.} for @var{new}.  This can give more reproducible builds, which are
+location independent, but may require an extra command to tell gdb where to
+find the source files.
 
 @item -fvar-tracking
 @opindex fvar-tracking

Re: [PATCH] expand -fdebug-prefix-map documentation

[Sandra Loosemore]

On 10/25/2017 06:26 PM, Jim Wilson wrote:

> Index: gcc/doc/invoke.texi
> ===================================================================
> --- gcc/doc/invoke.texi	(revision 254023)
> +++ gcc/doc/invoke.texi	(working copy)
> @@ -6981,7 +6981,12 @@ link processing time.  Merging is enabled by defau
>  @item -fdebug-prefix-map=@var{old}=@var{new}
>  @opindex fdebug-prefix-map
>  When compiling files in directory @file{@var{old}}, record debugging
> -information describing them as in @file{@var{new}} instead.
> +information describing them as in @file{@var{new}} instead.  This can be
> +used to replace a build time path with an install time path in the debug info.

build-time path, install-time path

> +It can also be used to change an absolute path to a relative path by using
> +@file{.} for @var{new}.  This can give more reproducible builds, which are
> +location independent, but may require an extra command to tell gdb where to
> +find the source files.
>
>  @item -fvar-tracking
>  @opindex fvar-tracking

OK with that tweak to the hyphenation.

-Sandra

Re: [PATCH] expand -fdebug-prefix-map documentation

[Gerald Pfeifer]

[-- Attachment #1: Type: text/plain, Size: 698 bytes --]

On Wed, 25 Oct 2017, Jim Wilson wrote:
> The current documentation doesn't explain what the option is for, or
> how one might use it.  The attached patch expands the documentation a
> bit to try to explain this.

> OK?

Thanks you for fleshing this out, Jim!

This looks fine to me (modula Sandra's note).  Just a question: would
we refer to GDB instead of gdb here?  It feels a little in between to
me, whether we are referring to the tool or the actual binary.  I'm
sure Sandra will have guidance for us. ;-)

+@file{.} for @var{new}.  This can give more reproducible builds, which are
+location independent, but may require an extra command to tell gdb where to
+find the source files.
 
Gerald

Re: [PATCH] expand -fdebug-prefix-map documentation

[Sandra Loosemore]

On 10/26/2017 11:47 AM, Gerald Pfeifer wrote:
> On Wed, 25 Oct 2017, Jim Wilson wrote:
>> The current documentation doesn't explain what the option is for, or
>> how one might use it.  The attached patch expands the documentation a
>> bit to try to explain this.
>
>> OK?
>
> Thanks you for fleshing this out, Jim!
>
> This looks fine to me (modula Sandra's note).  Just a question: would
> we refer to GDB instead of gdb here?  It feels a little in between to
> me, whether we are referring to the tool or the actual binary.  I'm
> sure Sandra will have guidance for us. ;-)

Hmmm, yes.  "GDB" is the preferred spelling elsewhere in the manual.

-Sandra

Re: [PATCH] expand -fdebug-prefix-map documentation

[Jim Wilson]

On Thu, 2017-10-26 at 12:35 -0600, Sandra Loosemore wrote:
> On 10/26/2017 11:47 AM, Gerald Pfeifer wrote:
> > Thanks you for fleshing this out, Jim!
> > 
> > This looks fine to me (modula Sandra's note).  Just a question:
> > would
> > we refer to GDB instead of gdb here?  It feels a little in between
> > to
> > me, whether we are referring to the tool or the actual binary.  I'm
> > sure Sandra will have guidance for us. ;-)
> Hmmm, yes.  "GDB" is the preferred spelling elsewhere in the manual.

Checked in with the two corrections.

Jim