forked from openkylin/dwz
208 lines
8.5 KiB
Groff
208 lines
8.5 KiB
Groff
.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> .
|