.TH dwz 1 "15 Feb 2021" .SH NAME dwz \- DWARF optimization and duplicate removal tool .SH SYNOPSIS dwz .RB [OPTION...]\ [FILES] .SH DESCRIPTION \fBdwz\fR is a program that attempts to optimize DWARF debugging information contained in ELF shared libraries and ELF executables for size, by replacing DWARF information representation with equivalent smaller representation where possible and by reducing the amount of duplication using techniques from DWARF standard appendix E - creating \fIDW_TAG_partial_unit\fR compilation units (CUs) for duplicated information and using \fIDW_TAG_imported_unit\fR to import it into each CU that needs it. The tool handles DWARF 32-bit format debugging sections of versions 2, 3, 4, most of version 5 and GNU extensions on top of those. It is strongly recommended to use at least DWARF 3, but using DWARF 4 or higher will work much better. While most of DWARF 5 is supported dwz doesn't yet generate spec compliant DWARF Supplementary Object Files (DWARF 5, section 7.3.6) unless the \fI--dwarf-5\fR option is used. Instead of a \fI.debug_sup\fR section it will generate by default a \fI.gnu_debugaltlink\fR section. And it will use the \fIDW_FORM_GNU_strp_alt\fR and \fIDW_FORM_GNU_reg_alt\fR, instead of \fIDW_FORM_strp_sup\fR and \fIDW_FORM_ref_sup\fR to keep compatibility with existing DWARF consumers. DWARF 4 \fI.debug_types\fR are supported, but DWARF 5 \fIDW_UT_type\fR units are not. Likewise \fI.gdb_index\fR is supported, but the DWARF 5 \fI.debug_names\fR is not. Also some forms and sections that are only emitted by GCC when generating Split DWARF, \fIDW_FORM_strx\fR and \fI.debug_str_offsets\fR, \fIDW_FORM_addrx\fR and \fI.debug_addr\fR, \fIDW_FORM_rnglistx\fR and \fIDW_FORM_loclistsx\fR, are not supported yet. The tool has two main modes of operation, without the \fI-m\fR option it attempts to optimize DWARF debugging information in each given object (executable or shared library) individually, with the \fI-m\fR option it afterwards attempts to optimize even more by moving DWARF debugging information entries (DIEs), strings and macro descriptions duplicated in more than one object into a newly created ELF ET_REL object whose filename is given as \fI-m\fR option argument. The debug sections in the executables and shared libraries specified on the command line are then modified again, referring to the entities in the newly created object. .SH OPTIONS .TP .B \-m\ FILE \-\-multifile FILE Multifile mode. After processing all named executables and shared libraries, attempt to create ELF object \fIFILE\fR and put debugging information duplicated in more than one object there, afterwards optimize each named executable or shared library even further if possible. .TP .B \-h\ \-\-hardlink Look for executables or shared libraries hardlinked together, instead of rewriting them individually rewrite just one of them and hardlink the rest to the first one again. .TP .B \-M NAME \-\-multifile-name NAME Specify the name of the common file that should be put into the \fI.gnu_debugaltlink\fR section alongside with its build ID. By default \fBdwz\fR puts there the argument of the \fB-m\fR option. .TP .B \-r \-\-relative Specify that the name of the common file to be put into the \fI.gnu_debugaltlink\fR section is supposed to be relative path from the directory containing the executable or shared library to the file named in the argument of the \fB-m\fR option. Either \fB-M\fR or \fB-r\fR option can be specified, but not both. .TP .B \-p N \-\-multifile-pointer-size Specify the pointer size of the multifile, in bytes. If auto, use the pointer size of the files, provided they match. If native, use native pointer size, as specified in the help message. .TP .B \-p \-\-multifile-endian Specify the endianity of the multifile. If auto, use the endianity of the files, provided they match. If native, use native endianity, as specified in the help message. .TP .B \-q \-\-quiet Silence up some of the most common messages. .TP .B \-o FILE \-\-output FILE This option instructs \fBdwz\fR not to overwrite the specified file, but instead store the new content into \fBFILE\fR. Nothing is written if \fBdwz\fR exits with non-zero exit code. Can be used only with a single executable or shared library (if there are no arguments at all, \fIa.out\fR is assumed). .TP .B \-l \-\-low\-mem\-die\-limit Handle executables or shared libraries containing more than \fICOUNT\fR debugging information entries in their \fI.debug_info\fR section using a slower and more memory usage friendly mode and don't attempt to optimize that object in multifile mode. The default is 10 million DIEs. There is a risk that for very large amounts of debugging information in a single shared library or executable there might not be enough memory (especially when \fBdwz\fR tool is 32-bit binary, it might run out of available virtual address space even sooner). Specifying none as argument disables the limit. .TP .B \-L \-\-max\-die\-limit Don't attempt to optimize executables or shared libraries containing more than \fICOUNT\fR DIEs at all. The default is 50 million DIEs. Specifying none as argument disables the limit. .TP .B \-5 \-\-dwarf\-5 Emit standard DWARF 5 Supplementary Object Files with \fI.debug_sup\fR and corresponding forms, instead of the GNU extension \fI.gnu_debugaltlink\fR and corresponding forms. .TP .B \-j \-\-jobs Process \fIN\fR files in parallel. The default is processors / 2. Disabled when multifile is used. .TP .B \-\-odr / \-\-no-odr .B Experimental. Enable/disable One-Definition-Rule optimization for C++ compilation units. This optimization causes struct/union/class DIEs with the same name to be considered equal. This has the effect that DIEs referring to distinct DIEs representing the same type (like f.i. pointer type DIEs) are considered equal, and may be deduplicated. The status of this optimization is experimental. It's disabled in low-mem mode. Disabled by default. .TP .B \-\-odr-mode= Set the One-Definition-Rule optimization aggressiveness: basic or link. When using the link setting, the optimization will attempt to replace declarations of a struct/union/class with a corresponding definition. When using the basic setting, that part of the optimization is disabled. In normal operation, the link setting should be used. The basic setting is provided only as fallback in case of problems with the link setting. Set to link by default. .TP .B \-\-import-optimize / \-\-no-import-optimize Enable/disable optimization that reduces the number of \fIDW_TAG_imported_unit\fR DIEs generated to import the partial units created by \fBdwz\fR. Disabling the optimization can be used to work around problems in the optimization, or to make it easier to observe which CU imports which PU. Enabled by default. .TP .B \-? \-\-help Print short help and exit. .TP .B \-v \-\-version Print version number and short licensing notice and exit. .SH ARGUMENTS Command-line arguments should be the executables, shared libraries or their stripped to file separate debug information objects. .SH EXAMPLES .RS $ dwz -m .dwz/foobar-1.2.debug -rh \\ bin/foo.debug bin/foo2.debug foo/lib/libbar.so.debug .RE will attempt to optimize debugging information in \fIbin/foo.debug\fR, \fIbin/foo2.debug\fR and \fIlib/libbar.so.debug\fR (by modifying the files in place) and when beneficial also will create \fI.dwz/foobar-1.2.debug\fR file. \fI.gnu_debugaltlink\fR section in the first two files will refer to \fI../.dwz/foobar-1.2.debug\fR and in the last file to \fI../../.dwz/foobar-1.2.debug\fR. If e.g. \fIbin/foo.debug\fR and \fIbin/foo2.debug\fR were hardlinked together initially, they will be hardlinked again and for multifile optimizations considered just as a single file rather than two. .RS $ dwz -o foo.dwz foo .RE will not modify \fIfoo\fR but instead store the ELF object with optimized debugging information if successful into \fIfoo.dwz\fR file it creates. .RS $ dwz *.debug foo/*.debug .RE will attempt to optimize debugging information in *.debug and foo/*.debug files, optimizing each file individually in place. .RS $ dwz .RE is equivalent to \fIdwz a.out\fR command. .SH SEE ALSO .BR http://dwarfstd.org/doc/DWARF4.pdf , .BR http://dwarfstd.org/doc/DWARF5.pdf , .BR gdb (1). .SH AUTHORS Jakub Jelinek , Tom de Vries , Mark Wielaard .SH BUGS Use the Bugzilla link of the project web page or our mailing list. .nh .BR https://sourceware.org/dwz/ ", " .