Issue 260116.1: DWARF Package file (.dwp) .debug_dwp ID

Author:	Mark Wielaard
Champion:
Date submitted:	2026-01-16
Date revised:	2026-03-12
Date closed:	2026-03-30
Type:	Enhancement
Status:	Accepted
DWARF version:	6

Background

DWARF Supplementary Object Files (.sup) and DWARF Package files (.dwp) are both secondary files that are generated (as optimization) from primary files containing DWARF. Neither is produced directly by compilers.

Unlike DWARF Supplementary Object Files, DWARF Package files don't have an ID to look them up or match them. There is only a non-normative hint that the package file is typically placed in the same directory as the application, and is given the same name with a ".dwp" extension. This makes storing the package files somewhere else or requesting them from a "debug server" inconvenient.

Although a similar mechanism mechanism could be used to make primary DWARF files (as produced during a edit/compile/debug cycle) separate and relocatable from their object files, we aren't proposing such a mechanism for other DWARF files. There are various (not-standardized) mechanisms to do that, like GNU/Linux build-ids, .gnu_debuglink, Solaris Ancillary Objects or Apple's DWARF with dSYM File. But these relationships are only one-to-one, unlike .sup and .dwp files which can be referenced from different (primary) DWARF files.

This proposal is just for making DWARF Package files as easy to locate as DWARF Supplementary Object files.

It also includes some naming clarifications fir the existing .debug_section to make sure field names are not using the terms checksum (when ID is meant) and filename (when a full path name is meant).

Overview

We propose to add an identifier, a .debug_dwp section, that contains a filename and ID to match up application or shared library object files with skeleton units to a dwp file created for all the dwo sections. This is similar to how supplemental files can be identified.

At the same time we propose some clarifications to the .debug_sup section. Specifically to not use the term checksum, but call it an ID or identifier. And to replace the term filename with file path to indicate the field contains a full (relative or abstract) path including the file name.

Proposed Changes

In 7.3.5 DWARF Package Files add the following to the end of the second paragraph (informational):

The package file also contains a .debug_dwp section with a unique DWP ID.

Add a new section "7.3.5.4 Format of the .debug_dwp Section" (based on a similar description of the .debug_sup section in "7.3.6 DWARF Supplementary Object Files" (with the changes proposed below)

Both the DWARF package file and the original application object file containing the skeleton units contain a .debug_dwp section that establishes the relationship between the object file containing the skeleton units and the DWARF package file containing the dwo units.

The .debug_dwp section contains:

1. version (uhalf)

   A 2-byte unsigned integer representing the version of the DWARF information for the DWARF package file.

   The value in this field is 6.

2. is_package (ubyte)

   A 1-byte unsigned integer, which contains the value 1 if it is in the DWARF package file that other executable or shared object files refer to, or 0 if it is an executable or shared object with skeleton units referring to a DWARF package file.

3. dwp_filepath (null terminated file path string)

   If is_package is 0, this contains either an absolute file path for the DWARF package file, or a file path relative to the object file containing the .debug_dwp section. If is_package is 1, then dwp_filepath is not needed and must be an empty string (a single null byte).

4. dwp_id_len (unsigned LEB128)

   Length of the following dwp_id field; this value can be 0 if no id is provided.

5. dwp_id (array of ubyte)

   An implementation-defined integer constant value that provides unique identification of the package file.

In 7.3.6 DWARF Supplementary Object Files make the following changes:

Replace (filename with filepath and checksum with id) in:

1. sup_filename (null terminated filename string)

   If is_supplementary is 0, this contains either an absolute filename for the supplementary object file, or a filename relative to the object file containing the .debug_sup section. If is_supplementary is 1, then sup_filename is not needed and must be an empty string (a single null byte).

2. sup_checksum_len (unsigned LEB128)

   Length of the following sup_checksum field; this value can be 0 if no checksum is provided.

3. sup_checksum (array of ubyte)

   An implementation-defined integer constant value that provides unique identification of the supplementary file.

To

1. sup_filepath (null terminated file path string)

   If is_supplementary is 0, this contains either an absolute file path for the supplementary object file, or a file path relative to the object file containing the .debug_sup section. If is_supplementary is 1, then sup_filepath is not needed and must be an empty string (a single null byte).

2. sup_id_len (unsigned LEB128)

   Length of the following sup_id field; this value can be 0 if no id is provided.

3. sup_id (array of ubyte)

   An implementation-defined integer constant value that provides unique identification of the supplementary file.

In Appendix F.3 DWARF Package File Example, change "plus two" to "plus three" in the second paragraph:

The package file contains the same set of sections as a split DWARF object file, plus two additional sections described below.

to

The package file contains the same set of sections as a split DWARF object file, plus three additional sections described below.

Add a line to Figure F.9: Sections and contributions in example package file demo.dwp:

Section	Source of section contributions
.debug_dwp	DWP ID generated by package utility

At the end of the text of Appendix F.3 add the following paragraph:

Figure F.12 shows an example .debug_dwp section for a object with skeleton units referring to a DWARF package file.

Add a new Figure F.12 "Example DWP ID section"

version: 6
is_package: 0
dwp_filepath: "dwp_files/object.dwp\0"
dwp_id_len: 40
dwp_id: 5b4d5616762a56d44589e2c6a242d5ec7ca4a7f1

---

2026-03-12: Revised to provide additional rationale; changed "checksum" to "id" (here and for supplementary object files).

2026-03-30: Accepted.