From: Nick Clifton <nickc@redhat.com>
Date: Thu, 5 Mar 2015 16:45:15 +0000 (+0000)
Subject: Extend description of --add-gnu-debuglink option to explain why the file must exist.
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=4fd77a3d12291cd9351e1f776a5ade11f99a28ac;p=binutils-gdb.git

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 --git a/binutils/ChangeLog b/binutils/ChangeLog
index 6b28bf943b3..1124122722e 100644
--- a/binutils/ChangeLog
+++ b/binutils/ChangeLog
@@ -1,3 +1,12 @@
+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
diff --git a/binutils/doc/binutils.texi b/binutils/doc/binutils.texi
index d63c04ca6c0..22d54bebfed 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