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 6b28bf943b3f17d1164b7a23857546f722bfbce8..1124122722e9522028ba16bd1b61b341f75a1411 100644 (file)
--- 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 d63c04ca6c089b6dc2952aaff382e2382cf1f65b..22d54bebfede058bf0021e6df30f9a625d65867e 100644 (file)
--- 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