diff options
Diffstat (limited to '')
| -rw-r--r-- | dwz.1 | 207 |
1 files changed, 207 insertions, 0 deletions
@@ -0,0 +1,207 @@ +.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> . |