path: root/dwz.1

.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 <N|auto|native>
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 <l|b|auto> \-\-multifile-endian <l|b|auto|native>
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 <COUNT|none> \-\-low\-mem\-die\-limit <COUNT|none>
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 <COUNT|none> \-\-max\-die\-limit <COUNT|none>
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 <N> \-\-jobs <N>
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=<basic|link>
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 <jakub@redhat.com>,
Tom de Vries <tdevries@suse.de>,
Mark Wielaard <mark@klomp.org>
.SH BUGS
Use the Bugzilla link of the project web page or our mailing list.
.nh
.BR https://sourceware.org/dwz/ ", " <dwz@sourceware.org> .