.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DH_DWZ 1"
.TH DH_DWZ 1 2024-03-27 13.15.3 Debhelper
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
dh_dwz \- optimize DWARF debug information in ELF binaries via dwz
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBdh_dwz\fR [\fIdebhelper\ options\fR] [\fB\-X\fR\fIitem\fR] [\fB\-\-\fR\ \fIparams\fR]
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBdh_dwz\fR is a debhelper program that will optimize the (uncompressed)
size of the DWARF debug information in ELF binaries.  It does so by
running \fBdwz\fR\|(1) on all the ELF binaries in the package.
.SH OPTIONS
.IX Header "OPTIONS"
.IP "\fB\-\-dwz\-multifile\fR, \fB\-\-no\-dwz\-multifile\fR" 4
.IX Item "--dwz-multifile, --no-dwz-multifile"
Whether \fBdwz\fR\|(1) should generate a \fImultifile\fR from the ELF binaries
in the same package.  When enabled, if a package ships at least 2 ELF
binaries, \fBdh_dwz\fR will instruct \fBdwz\fR\|(1) to generate a multifile
for the package.
.Sp
By default, \fBdh_dwz\fR will attempt to create a multifile but will
continue without if \fBdwz\fR\|(1) does not create one (but succeeds anyway).
This commonly happens when the debug files do not contain debug
symbols (e.g. a missing \-g to the compiler) or when the debug
symbols are compressed (see Debian bug #931891).  If \fB\-\-dwz\-multifile\fR
is passed, then \fBdh_dwz\fR will abort with an error if \fBdwz\fR\|(1) does
not create a multifile.
.Sp
Note this options may not work if a package contains more ELF binaries
than can fit on a single command line.  If this becomes a problem,
please pass \fB\-\-no\-dwz\-multifile\fR to work around the issue.
.Sp
The generated multifile will be compressed with \fBobjcopy
\&\-\-compress\-debug\-sections\fR.
.Sp
Note for \fBudeb\fR packages: \fBdh_dwz\fR will never generate multifiles
for \fBudeb\fR packages.  It will still use \fBdwz\fR to reduce the
file size of debug files if it finds any.
.IP "\fB\-X\fR\fIitem\fR, \fB\-\-exclude=\fR\fIitem\fR" 4
.IX Item "-Xitem, --exclude=item"
Exclude files that contain \fIitem\fR anywhere in their filename from being
stripped. You may use this option multiple times to build up a list of
things to exclude.
.IP "\fB\-\-\fR \fIparams\fR" 4
.IX Item "-- params"
Pass \fIparams\fR to \fBdwz\fR\|(1) when it processes ELF binaries.  This is
mostly useful for setting memory related parameters (e.g. \-l and \-L).
.SH NOTES
.IX Header "NOTES"
If the \fBDEB_BUILD_OPTIONS\fR environment variable contains \fBnostrip\fR,
nothing will be stripped, in accordance with Debian policy (section
10.1 "Binaries").
.PP
While this tool technically does not remove debug information from
binaries, it is still skipped when the \fBDEB_BUILD_OPTIONS\fR
environment variable contains \fBnostrip\fR.  This is because \fBnostrip\fR
is often used to optimize build times (e.g. for "build and
test"\-cycles) rather than optimizing for size.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBdebhelper\fR\|(7)
.PP
This program is a part of debhelper.
.SH AUTHOR
.IX Header "AUTHOR"
Niels Thykier <niels@thykier.net>