1dwz(1) General Commands Manual dwz(1)
2
6 dwz - DWARF optimization and duplicate removal tool
7
9 dwz [OPTION...] [FILES]
10
12 dwz is a program that attempts to optimize DWARF debugging information
13 contained in ELF shared libraries and ELF executables for size, by re‐
14 placing DWARF information representation with equivalent smaller repre‐
15 sentation where possible and by reducing the amount of duplication us‐
16 ing techniques from DWARF standard appendix E - creating DW_TAG_par‐
17 tial_unit compilation units (CUs) for duplicated information and using
18 DW_TAG_imported_unit to import it into each CU that needs it.
19 The tool handles DWARF 32-bit format debugging sections of versions 2,
21 3, 4, most of version 5 and GNU extensions on top of those. It is
22 strongly recommended to use at least DWARF 3, but using DWARF 4 or
23 higher will work much better.
24 While most of DWARF 5 is supported dwz doesn't yet generate spec com‐
26 pliant DWARF Supplementary Object Files (DWARF 5, section 7.3.6) unless
27 the --dwarf-5 option is used. Instead of a .debug_sup section it will
28 generate by default a .gnu_debugaltlink section. And it will use the
29 DW_FORM_GNU_strp_alt and DW_FORM_GNU_reg_alt, instead of
30 DW_FORM_strp_sup and DW_FORM_ref_sup to keep compatibility with exist‐
31 ing DWARF consumers.
32 DWARF 4 .debug_types are supported, but DWARF 5 DW_UT_type units are
34 not. Likewise .gdb_index is supported, but the DWARF 5 .debug_names is
35 not. Also some forms and sections that are only emitted by GCC when
36 generating Split DWARF, DW_FORM_strx and .debug_str_offsets,
37 DW_FORM_addrx and .debug_addr, DW_FORM_rnglistx and DW_FORM_loclistsx,
38 are not supported yet.
39 The tool has two main modes of operation, without the -m option it at‐
41 tempts to optimize DWARF debugging information in each given object
42 (executable or shared library) individually, with the -m option it af‐
43 terwards attempts to optimize even more by moving DWARF debugging in‐
44 formation entries (DIEs), strings and macro descriptions duplicated in
45 more than one object into a newly created ELF ET_REL object whose file‐
46 name is given as -m option argument. The debug sections in the exe‐
47 cutables and shared libraries specified on the command line are then
48 modified again, referring to the entities in the newly created object.
49
51 -m FILE --multifile FILE
52 Multifile mode. After processing all named executables and
53 shared libraries, attempt to create ELF object FILE and put de‐
54 bugging information duplicated in more than one object there,
55 afterwards optimize each named executable or shared library even
56 further if possible.
57 -h --hardlink
59 Look for executables or shared libraries hardlinked together,
60 instead of rewriting them individually rewrite just one of them
61 and hardlink the rest to the first one again.
62 -M NAME --multifile-name NAME
64 Specify the name of the common file that should be put into the
65 .gnu_debugaltlink section alongside with its build ID. By de‐
66 fault dwz puts there the argument of the -m option.
67 -r --relative
69 Specify that the name of the common file to be put into the
70 .gnu_debugaltlink section is supposed to be relative path from
71 the directory containing the executable or shared library to the
72 file named in the argument of the -m option. Either -M or -r
73 option can be specified, but not both.
74 -p N --multifile-pointer-size <N|auto|native>
76 Specify the pointer size of the multifile, in bytes. If auto,
77 use the pointer size of the files, provided they match. If na‐
78 tive, use native pointer size, as specified in the help message.
79 -p <l|b|auto> --multifile-endian <l|b|auto|native>
81 Specify the endianity of the multifile. If auto, use the endi‐
82 anity of the files, provided they match. If native, use native
83 endianity, as specified in the help message.
84 -q --quiet
86 Silence up some of the most common messages.
87 -o FILE --output FILE
89 This option instructs dwz not to overwrite the specified file,
90 but instead store the new content into FILE. Nothing is written
91 if dwz exits with non-zero exit code. Can be used only with a
92 single executable or shared library (if there are no arguments
93 at all, a.out is assumed).
94 -l <COUNT|none> --low-mem-die-limit <COUNT|none>
96 Handle executables or shared libraries containing more than
97 COUNT debugging information entries in their .debug_info section
98 using a slower and more memory usage friendly mode and don't at‐
99 tempt to optimize that object in multifile mode. The default is
100 10 million DIEs. There is a risk that for very large amounts of
101 debugging information in a single shared library or executable
102 there might not be enough memory (especially when dwz tool is
103 32-bit binary, it might run out of available virtual address
104 space even sooner). Specifying none as argument disables the
105 limit.
106 -L <COUNT|none> --max-die-limit <COUNT|none>
108 Don't attempt to optimize executables or shared libraries con‐
109 taining more than COUNT DIEs at all. The default is 50 million
110 DIEs. Specifying none as argument disables the limit.
111 -5 --dwarf-5
113 Emit standard DWARF 5 Supplementary Object Files with .debug_sup
114 and corresponding forms, instead of the GNU extension .gnu_de‐
115 bugaltlink and corresponding forms.
116 -j <N> --jobs <N>
118 Process N files in parallel. The default is processors / 2.
119 Disabled when multifile is used.
120 --odr / --no-odr
122 Experimental. Enable/disable One-Definition-Rule optimization
123 for C++ compilation units. This optimization causes
124 struct/union/class DIEs with the same name to be considered
125 equal. This has the effect that DIEs referring to distinct DIEs
126 representing the same type (like f.i. pointer type DIEs) are
127 considered equal, and may be deduplicated. The status of this
128 optimization is experimental. It's disabled in low-mem mode.
129 Disabled by default.
130 --odr-mode=<basic|link>
132 Set the One-Definition-Rule optimization aggressiveness: basic
133 or link. When using the link setting, the optimization will at‐
134 tempt to replace declarations of a struct/union/class with a
135 corresponding definition. When using the basic setting, that
136 part of the optimization is disabled. In normal operation, the
137 link setting should be used. The basic setting is provided only
138 as fallback in case of problems with the link setting. Set to
139 link by default.
140 --import-optimize / --no-import-optimize
142 Enable/disable optimization that reduces the number of
143 DW_TAG_imported_unit DIEs generated to import the partial units
144 created by dwz. Disabling the optimization can be used to work
145 around problems in the optimization, or to make it easier to ob‐
146 serve which CU imports which PU. Enabled by default.
147 -? --help
149 Print short help and exit.
150 -v --version
152 Print version number and short licensing notice and exit.
153
155 Command-line arguments should be the executables, shared libraries or
156 their stripped to file separate debug information objects.
157
159 $ dwz -m .dwz/foobar-1.2.debug -rh \
160 bin/foo.debug bin/foo2.debug foo/lib/libbar.so.debug
161 will attempt to optimize debugging information in bin/foo.debug,
162 bin/foo2.debug and lib/libbar.so.debug (by modifying the files in
163 place) and when beneficial also will create .dwz/foobar-1.2.debug file.
164 .gnu_debugaltlink section in the first two files will refer to
165 ../.dwz/foobar-1.2.debug and in the last file to ../../.dwz/foo‐
166 bar-1.2.debug. If e.g. bin/foo.debug and bin/foo2.debug were
167 hardlinked together initially, they will be hardlinked again and for
168 multifile optimizations considered just as a single file rather than
169 two.
170 $ dwz -o foo.dwz foo
171 will not modify foo but instead store the ELF object with optimized de‐
172 bugging information if successful into foo.dwz file it creates.
173 $ dwz *.debug foo/*.debug
174 will attempt to optimize debugging information in *.debug and foo/*.de‐
175 bug files, optimizing each file individually in place.
176 $ dwz
177 is equivalent to dwz a.out command.
178
180 http://dwarfstd.org/doc/DWARF4.pdf , http://dwarfstd.org/doc/DWARF5.pdf
181 , gdb(1).
182
184 Jakub Jelinek <jakub@redhat.com>, Tom de Vries <tdevries@suse.de>, Mark
185 Wielaard <mark@klomp.org>
186
188 Use the Bugzilla link of the project web page or our mailing list.
189 https://sourceware.org/dwz/, <dwz@sourceware.org>.
190 15 Feb 2021 dwz(1)