1dwz(1)                      General Commands Manual                     dwz(1)
2
3
4

NAME

6       dwz - DWARF optimization and duplicate removal tool
7

SYNOPSIS

9       dwz [OPTION...] [FILES]
10

DESCRIPTION

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
20       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
25       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
33       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
40       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

OPTIONS

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
58       -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
63       -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
68       -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
75       -q --quiet
76              Silence up some of the most common messages.
77
78       -o FILE --output FILE
79              This  option  instructs dwz not to overwrite the specified file,
80              but instead store the new content into FILE.  Nothing is written
81              if  dwz  exits with non-zero exit code.  Can be used only with a
82              single executable or shared library (if there are  no  arguments
83              at all, a.out is assumed).
84
85       -l <COUNT|none> --low-mem-die-limit <COUNT|none>
86              Handle  executables  or  shared  libraries  containing more than
87              COUNT debugging information entries in their .debug_info section
88              using a slower and more memory usage friendly mode and don't at‐
89              tempt to optimize that object in multifile mode.  The default is
90              10 million DIEs.  There is a risk that for very large amounts of
91              debugging information in a single shared library  or  executable
92              there  might  not  be enough memory (especially when dwz tool is
93              32-bit binary, it might run out  of  available  virtual  address
94              space  even  sooner).   Specifying none as argument disables the
95              limit.
96
97       -L <COUNT|none> --max-die-limit <COUNT|none>
98              Don't attempt to optimize executables or shared  libraries  con‐
99              taining  more than COUNT DIEs at all.  The default is 50 million
100              DIEs.  Specifying none as argument disables the limit.
101
102       -5 --dwarf-5
103              Emit standard DWARF 5 Supplementary Object Files with .debug_sup
104              and  corresponding  forms, instead of the GNU extension .gnu_de‐
105              bugaltlink and corresponding forms.
106
107       --odr / --no-odr
108              Experimental.  Enable/disable  One-Definition-Rule  optimization
109              for   C++   compilation   units.    This   optimization   causes
110              struct/union/class DIEs with the  same  name  to  be  considered
111              equal.  This has the effect that DIEs referring to distinct DIEs
112              representing the same type (like f.i.  pointer  type  DIEs)  are
113              considered  equal,  and may be deduplicated.  The status of this
114              optimization is experimental.  It's disabled  in  low-mem  mode.
115              Disabled by default.
116
117       --odr-mode=<basic|link>
118              Set  the  One-Definition-Rule optimization aggressiveness: basic
119              or link.  When using the link setting, the optimization will at‐
120              tempt  to  replace  declarations  of a struct/union/class with a
121              corresponding definition.  When using the  basic  setting,  that
122              part  of the optimization is disabled.  In normal operation, the
123              link setting should be used.  The basic setting is provided only
124              as  fallback  in case of problems with the link setting.  Set to
125              link by default.
126
127       --import-optimize / --no-import-optimize
128              Enable/disable  optimization  that   reduces   the   number   of
129              DW_TAG_imported_unit  DIEs generated to import the partial units
130              created by dwz.  Disabling the optimization can be used to  work
131              around problems in the optimization, or to make it easier to ob‐
132              serve which CU imports which PU.  Enabled by default.
133
134       -? --help
135              Print short help and exit.
136
137       -v --version
138              Print version number and short licensing notice and exit.
139

ARGUMENTS

141       Command-line arguments should be the executables, shared  libraries  or
142       their stripped to file separate debug information objects.
143

EXAMPLES

145              $ dwz -m .dwz/foobar-1.2.debug -rh \
146                bin/foo.debug bin/foo2.debug foo/lib/libbar.so.debug
147       will  attempt  to  optimize  debugging  information  in  bin/foo.debug,
148       bin/foo2.debug and  lib/libbar.so.debug  (by  modifying  the  files  in
149       place) and when beneficial also will create .dwz/foobar-1.2.debug file.
150       .gnu_debugaltlink  section  in  the  first  two  files  will  refer  to
151       ../.dwz/foobar-1.2.debug  and  in  the  last  file  to  ../../.dwz/foo‐
152       bar-1.2.debug.   If  e.g.   bin/foo.debug   and   bin/foo2.debug   were
153       hardlinked  together  initially,  they will be hardlinked again and for
154       multifile optimizations considered just as a single  file  rather  than
155       two.
156              $ dwz -o foo.dwz foo
157       will not modify foo but instead store the ELF object with optimized de‐
158       bugging information if successful into foo.dwz file it creates.
159              $ dwz *.debug foo/*.debug
160       will attempt to optimize debugging information in *.debug and foo/*.de‐
161       bug files, optimizing each file individually in place.
162              $ dwz
163       is equivalent to dwz a.out command.
164

SEE ALSO

166       http://dwarfstd.org/doc/DWARF4.pdf , http://dwarfstd.org/doc/DWARF5.pdf
167       , gdb(1).
168

AUTHORS

170       Jakub Jelinek <jakub@redhat.com>, Tom de Vries <tdevries@suse.de>, Mark
171       Wielaard <mark@klomp.org>
172

BUGS

174       Use  the  Bugzilla  link  of  the project web page or our mailing list.
175       https://sourceware.org/dwz/, <dwz@sourceware.org>.
176
177
178
179                                  15 Feb 2021                           dwz(1)
Impressum