Issue 080128.1: Clarify recommendations for filenames

Author: Cary Coutant
Champion: Cary Coutant
Date submitted: 2008-01-28
Date revised:
Date closed:
Type: Improvement
Status: Accepted with modification
DWARF Version: 4
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.