Issue 080128.1: Clarify recommendations for filenames
Revised 2008-05-30. Previous version can be found at
http://www.dwarfstd.org/issues/080128.1-1.html
Section: 3.1.1, 6.2.4, 6.2.5.3, 7.5.4
Page: 40, 97, 103, 138
Background
(A) In Section 3.1.1, "Normal and Partial Compilation Unit Entries,"
on page 40, the current spec says (in non-normative text):
The suggested form for the value of the DW_AT_comp_dir attribute on
UNIX systems is "hostname:pathname". If no hostname is available, the
suggested form is ":pathname".
This suggestion is incompatible with DOS filenames, and is rarely
used. It would seem better to provide a separate attribute,
DW_AT_host, to provide the hostname in the unusual cases where it
needs to be specified.
(B) In Section 6.2.4, "The Line Number Program Header," item 10,
"include_directories", it says "Each path entry is either a full path
name or is relative to the current directory of the compilation." But
later in the same paragraph, it says "Each entry is a null-terminated
string containing a full path name." For consistency, we should change
the second sentence to make it clear that a relative pathname is
allowed.
(C) We've found that gdb currently has a problem when the filename as
specified in DW_AT_comp_dir + DW_AT_name doesn't exactly match the
filename as specified by the directory and file name entries in the
line number program. Gdb attempts to canonicalize the names before
comparing them, but this is problematic in the case of mount points
and symbolic links, and it doesn't always work right if the producer
doesn't output the names consistently. We should at least recommend
(if not require) that the pathnames and filenames used in the
.debug_info sections are consistent with the pathnames and filenames
used in the .debug_line sections.
Proposal
(A) In Section 3.1.1, "Normal and Partial Compilation Unit Entries,"
on page 40, remove the following non-normative text:
The suggested form for the value of the DW_AT_comp_dir
attribute on UNIX systems is "hostname:pathname". If no
hostname is available, the suggested form is ":pathname".
Insert the following additional bullet item immediately following item
6 (renumbering the following items appropriately):
7. A DW_AT_host attribute whose value is a
null-terminated string containing the hostname where the
source files are stored. If a hostname is unavailable or
unnecessary, this attribute may be omitted.
In Section 7.5.4, "Attribute Encodings," on page 138, add the
following row to Figure 20:
Attribute name Value Classes
-------------- ----- -------
DW_AT_host 0x?? string
(Assign the next available attribute value, which would be 0x69 based
on the latest draft of the DWARF-3 specification.)
(B) In Section 6.2.4, "The Line Number Program Header," item 10,
"include_directories", on page 97, replace this sentence:
Each entry is a null-terminated string containing a full
path name.
with this:
Each entry is a null-terminated string containing the full
or relative path name of a directory where source files
may be located.
(C) In Section 6.2.4, "The Line Number Program Header," item 11,
"file_names", on page 97, replace the first two bullet items with the
following:
* A null-terminated string containing the full or relative
path name of a source file. If the entry contains a simple
file name or a relative path name, the file is located
relative to either the compilation directory (as specified
by the DW_AT_comp_dir attribute given in the compilation
unit) or one of the directories listed in the
include_directories section.
* An unsigned LEB128 number representing the directory
index of a directory in the include_directories section.
Following the fourth bullet item, add the following paragraph:
The primary source file should be described by an entry
whose path name exactly matches that given in the
DW_AT_name attribute given in the compilation unit, and
whose directory index is 0.
In Section 6.2.5.3, "Extended Opcodes," item 3, "DW_LNE_define_file,"
on page 103, replace the first two numbered items with the following:
1. A null-terminated string containing the full or relative
path name of a source file. If the entry contains a simple
file name or a relative path name, the file is located
relative to either the compilation directory (as specified
by the DW_AT_comp_dir attribute given in the compilation
unit) or one of the directories listed in the
include_directories section.
2. An unsigned LEB128 number representing the directory
index of a directory in the include_directories section.
Following the fourth item, add the following paragraph:
The primary source file should be described by an entry
whose path name exactly matches that given in the
DW_AT_name attribute given in the compilation unit, and
whose directory index is 0.
========
Accepted, except for DW_AT_host, which is removed.