[Dwarf-discuss] DWARF Package File (.dwp) .debug_dwp ID proposal

[Cary Coutant]

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

https://dwarfstd.org/issues/260116.1.html

-cary


On Fri, Jan 16, 2026 at 11:20 AM Mark Wielaard via Dwarf-discuss <
dwarf-discuss@lists.dwarfstd.org> wrote:

> # DWARF Package file (.dwp) .debug_dwp ID
>
> ## Background
>
> Unlike DWARF Supplementary Object Files DWARF Package files don't have
> an ID or checksum 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.
>
> ## Overview
>
> We propose to add an identifier, a .debug_dwp section, that contains a
> filename and checksum 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.
>
> ## 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"
>
> ```
> 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_filename (null terminated filename string)
> If is_package is 0, this contains either an absolute filename for the
> DWARF package file, or a filename relative to the object file
> containing the .debug_dwp section. If is_package is 1, then
> dwp_filename is not needed and must be an empty string (a single null
> byte).
>
> 4. dwp_checksum_len (unsigned LEB128)
> Length of the following dwp_checksum field;
> this value can be 0 if no checksum is provided.
>
> 5. dwp_checksum (array of ubyte)
> An implementation-defined integer constant value that
> provides unique identification of the package 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:
>
> ".debug_dwp" | "DWP ID generated by package utility"
>
> At the end of the text of Appendix F.3 add the following paragraph:
>
> Add a new Figure F.12 "Example DWP ID section"
>
> ... figure to be provided based on new 7.3.5.4 Format of the .debug_dwp
> Section ...
> --
> Dwarf-discuss mailing list
> Dwarf-discuss@lists.dwarfstd.org
> https://lists.dwarfstd.org/mailman/listinfo/dwarf-discuss
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.dwarfstd.org/pipermail/dwarf-discuss/attachments/20260130/4a3493bc/attachment.htm>