dwz - DWARF optimization and duplicate removal tool
dwz 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
DW_TAG_partial_unit compilation units (CUs) for duplicated
information and using DW_TAG_imported_unit 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 --dwarf-5 option is used. Instead of a .debug_sup section
it will generate by default a .gnu_debugaltlink section. And it will
use the DW_FORM_GNU_strp_alt and DW_FORM_GNU_reg_alt, instead
of DW_FORM_strp_sup and DW_FORM_ref_sup to keep compatibility
with existing DWARF consumers.
DWARF 4 .debug_types are supported, but DWARF 5
DW_UT_type units are not. Likewise .gdb_index is supported,
but the DWARF 5 .debug_names is not. Also some forms and sections
that are only emitted by GCC when generating Split DWARF,
DW_FORM_strx and .debug_str_offsets, DW_FORM_addrx and
.debug_addr, DW_FORM_rnglistx and DW_FORM_loclistsx,
are not supported yet.
The tool has two main modes of operation, without the -m
option it attempts to optimize DWARF debugging information in each given
object (executable or shared library) individually, with the -m
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 -m 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.
- -m FILE --multifile
FILE
- Multifile mode. After processing all named executables and shared
libraries, attempt to create ELF object FILE and put debugging
information duplicated in more than one object there, afterwards optimize
each named executable or shared library even further if possible.
- -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.
- -M NAME --multifile-name
NAME
- Specify the name of the common file that should be put into the
.gnu_debugaltlink section alongside with its build ID. By default
dwz puts there the argument of the -m option.
- -r --relative
- Specify that the name of the common file to be put into the
.gnu_debugaltlink 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 -m option. Either -M or -r option
can be specified, but not both.
- -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.
- -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.
- -q --quiet
- Silence up some of the most common messages.
- -o FILE --output
FILE
- This option instructs dwz not to overwrite the specified file, but
instead store the new content into FILE. Nothing is written if
dwz exits with non-zero exit code. Can be used only with a single
executable or shared library (if there are no arguments at all,
a.out is assumed).
- -l <COUNT|none>
--low-mem-die-limit <COUNT|none>
- Handle executables or shared libraries containing more than COUNT
debugging information entries in their .debug_info 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 dwz tool is 32-bit binary, it might run out of available
virtual address space even sooner). Specifying none as argument disables
the limit.
- -L <COUNT|none>
--max-die-limit <COUNT|none>
- Don't attempt to optimize executables or shared libraries containing more
than COUNT DIEs at all. The default is 50 million DIEs. Specifying
none as argument disables the limit.
- -5 --dwarf-5
- Emit standard DWARF 5 Supplementary Object Files with .debug_sup
and corresponding forms, instead of the GNU extension
.gnu_debugaltlink and corresponding forms.
- -j <N> --jobs
<N>
- Process N files in parallel. The default is processors / 2.
Disabled when multifile is used.
- --odr / --no-odr
- 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.
- --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.
- --import-optimize
/ --no-import-optimize
- Enable/disable optimization that reduces the number of
DW_TAG_imported_unit DIEs generated to import the partial units
created by dwz. 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.
- -? --help
- Print short help and exit.
- -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
bin/foo.debug, bin/foo2.debug and lib/libbar.so.debug
(by modifying the files in place) and when beneficial also will create
.dwz/foobar-1.2.debug file. .gnu_debugaltlink section in the
first two files will refer to ../.dwz/foobar-1.2.debug and in the
last file to ../../.dwz/foobar-1.2.debug. If e.g.
bin/foo.debug and bin/foo2.debug 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 foo but instead store the ELF object with optimized
debugging information if successful into foo.dwz 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.
$ dwz
is equivalent to dwz a.out command.
http://dwarfstd.org/doc/DWARF4.pdf ,
http://dwarfstd.org/doc/DWARF5.pdf , gdb(1).
Jakub Jelinek <jakub@redhat.com>, Tom de Vries
<tdevries@suse.de>, Mark Wielaard <mark@klomp.org>
Use the Bugzilla link of the project web page or our mailing list.
https://sourceware.org/dwz/, <dwz@sourceware.org>.