[binutils-gdb] Extend description of --add-gnu-debuglink option to explain why the file must exist.

[Nick Clifton <nickc at sourceware dot org>]

https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=4fd77a3d12291cd9351e1f776a5ade11f99a28ac

commit 4fd77a3d12291cd9351e1f776a5ade11f99a28ac
Author: Nick Clifton <nickc@redhat.com>
Date:   Thu Mar 5 16:45:15 2015 +0000

    Extend description of --add-gnu-debuglink option to explain why the file must exist.
    
    	PR binutils/18064
    	* doc/binutils.texi (objcopy): Extend description of
    	--add-gnu-debuglink option to explain that the separate debug info
    	file must exist.  Add a description of what to do if the debug
    	info file is built in one place but then installed into a separate
    	location.

Diff:
---
 binutils/ChangeLog         |  9 +++++++++
 binutils/doc/binutils.texi | 38 ++++++++++++++++++++++++++++++++++++--
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/binutils/ChangeLog b/binutils/ChangeLog
index 6b28bf9..1124122 100644
--- a/binutils/ChangeLog
+++ b/binutils/ChangeLog
@@ -1,5 +1,14 @@
 2015-03-05  Nick Clifton  <nickc@redhat.com>
 
+	PR binutils/18064
+	* doc/binutils.texi (objcopy): Extend description of
+	--add-gnu-debuglink option to explain that the separate debug info
+	file must exist.  Add a description of what to do if the debug
+	info file is built in one place but then installed into a separate
+	location.
+
+2015-03-05  Nick Clifton  <nickc@redhat.com>
+
 	PR binutils/17994
 	* dlltool.c (temp_file_to_remove): New local array.
 	(unlink_temp_files): New functions - unlinks any file in the
diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi
index d63c04c..22d54be 100644
--- a/binutils/doc/binutils.texi
+++ b/binutils/doc/binutils.texi
@@ -1684,8 +1684,42 @@ Prefix all the names of all allocated sections in the output file with
 @var{string}.
 
 @item --add-gnu-debuglink=@var{path-to-file}
-Creates a .gnu_debuglink section which contains a reference to @var{path-to-file}
-and adds it to the output file.
+Creates a .gnu_debuglink section which contains a reference to
+@var{path-to-file} and adds it to the output file.  Note: the file at
+@var{path-to-file} must exist.  Part of the process of adding the
+.gnu_debuglink section involves embedding a checksum of the contents
+of the debug info file into the section.
+
+If the debug info file is built in one location but it is going to be
+installed at a later time into a different location then do not use
+the path to the installed location.  The @option{--add-gnu-debuglink}
+option will fail because the installed file does not exist yet.
+Instead put the debug info file in the current directory and use the
+@option{--add-gnu-debuglink} option without any directory components,
+like this:
+
+@smallexample
+ objcopy --add-gnu-debuglink=foo.debug
+@end smallexample
+ 
+At debug time the debugger will attempt to look for the separate debug
+info file in a set of known locations.  The exact set of these
+locations varies depending upon the distribution being used, but it
+typically includes:
+
+@table @code
+
+@item * The same directory as the executable.
+
+@item * A sub-directory of the directory containing the executable
+called .debug
+
+@item * A global debug directory such as /usr/lib/debug.
+@end table
+
+As long as the debug info file has been installed into one of these
+locations before the debugger is run everything should work
+correctly.
 
 @item --keep-file-symbols
 When stripping a file, perhaps with @option{--strip-debug} or