From 4fd77a3d12291cd9351e1f776a5ade11f99a28ac Mon Sep 17 00:00:00 2001 From: Nick Clifton Date: Thu, 5 Mar 2015 16:45:15 +0000 Subject: 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. --- 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 + 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 + 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 -- cgit v1.1