.TH dwz 1 "15 June 2012"
dwz \- DWARF optimization and duplicate removal tool
.RB [OPTION...]\ [FILES]
\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
compilation units (CUs) for duplicated information and using
to import it into each CU that needs it.
The tool handles DWARF 32-bit format debugging sections of versions
2, 3 and 4 and GNU extensions on top of those, though using DWARF 4
or worst case DWARF 3 is strongly recommended.
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
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.
.B \-m\ FILE \-\-multifile FILE
After processing all named executables and shared libraries, attempt to
create ELF object
and put debugging information duplicated in more than one object there,
afterwards optimize each named executable or shared library even further
.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.
.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.
.B \-r \-\-relative
Specify that the name of the common file to be put into the
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.
.B \-q \-\-quiet
Silence up some of the most common messages.
.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,
.B \-l COUNT \-\-low\-mem\-die\-limit COUNT
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).
.B \-L COUNT \-\-max\-die\-limit COUNT
Don't attempt to optimize executables or shared libraries
containing more than
\fICOUNT\fR DIEs at all. The default is 50 million DIEs.
.B \-? \-\-help
Print short help and exit.
.B \-v \-\-version
Print version number and short licensing notice and exit.
Command-line arguments should be the executables, shared libraries
or their stripped to file separate debug information objects.
$ dwz -m .dwz/foobar-1.2.debug -rh \\
bin/foo.debug bin/foo2.debug foo/lib/libbar.so.debug
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.
$ dwz -o foo.dwz foo
will not modify \fIfoo\fR
but instead store the ELF object with optimized debugging information
if successful into \fIfoo.dwz\fR
file it creates.
$ dwz *.debug foo/*.debug
will attempt to optimize debugging information in *.debug and foo/*.debug
files, optimizing each file individually in place.
is equivalent to \fIdwz a.out\fR command.
.SH SEE ALSO
.BR gdb (1).
Jakub Jelinek <firstname.lastname@example.org>.