dwz

dwz(1)                      General Commands Manual                     dwz(1)

NAME
       dwz - DWARF optimization and duplicate removal tool

SYNOPSIS
       dwz [OPTION...] [FILES]

DESCRIPTION
       dwz  is a program that attempts to optimize DWARF debugging information
       contained in ELF shared libraries and ELF executables for size, by  re-
       placing DWARF information representation with equivalent smaller repre-
       sentation where possible and by reducing the amount of duplication  us-
       ing  techniques  from  DWARF standard appendix E - creating DW_TAG_par-
       tial_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  com-
       pliant 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 exist-
       ing 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 at-
       tempts to optimize DWARF debugging information  in  each  given  object
       (executable  or shared library) individually, with the -m option it af-
       terwards attempts to optimize even more by moving DWARF  debugging  in-
       formation  entries (DIEs), strings and macro descriptions duplicated in
       more than one object into a newly created ELF ET_REL object whose file-
       name  is  given  as -m option argument.  The debug sections in the exe-
       cutables and shared libraries specified on the command  line  are  then
       modified again, referring to the entities in the newly created object.

OPTIONS
       -m FILE --multifile FILE
              Multifile  mode.   After  processing  all  named executables and
              shared libraries, attempt to create ELF object FILE and put  de-
              bugging  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  de-
              fault 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.

       -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 at-
              tempt 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  con-
              taining  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_de-
              bugaltlink and corresponding forms.

       --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 at-
              tempt  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 ob-
              serve 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.

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

EXAMPLES
              $ 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/foo-
       bar-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 de-
       bugging information if successful into foo.dwz file it creates.
              $ dwz *.debug foo/*.debug
       will attempt to optimize debugging information in *.debug and foo/*.de-
       bug files, optimizing each file individually in place.
              $ dwz
       is equivalent to dwz a.out command.

SEE ALSO
       http://dwarfstd.org/doc/DWARF4.pdf , http://dwarfstd.org/doc/DWARF5.pdf
       , gdb(1).

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

BUGS
       Use  the  Bugzilla  link  of  the project web page or our mailing list.
       https://sourceware.org/dwz/, <dwz@sourceware.org>.

                                  15 Feb 2021                           dwz(1)