.\" (C) Copyright 2011-2024 Software Freedom Conservancy, Inc.
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3 of the License, or
.\" (at your option) any later version.
.TH "DH\-EXEC" "1" "2024-02-27" "" "dh-exec"
.ad l
.nh
.SH "NAME"
dh\-exec \- Debhelper executable file helpers
.SH "SYNOPSIS"
\fB#! /usr/bin/dh\-exec\fR
.br
src/libfoo-*.so.* debian/foo-plugins/usr/lib/foo/${DEB_HOST_MULTIARCH}/
.br
etc/example.conf => debian/foo/etc/foo/foo.conf
.br
[linux-any kfreebsd-any] some-arch-specific-file /usr/lib/foo/

.SH "DESCRIPTION"
dh\-exec is a simple program, meant to be used as the interpreter for
executable debhelper config files.

It is a wrapper around the various other sub\-commands (see below),
and will pipe the input file through all of them in turn, using an
ordering that makes most sense in the vast majority of cases.

The order as of now is \fIdh\-exec\-subst\fR gets run first, followed
by \fIdh\-exec\-install\fR, so that variable expansion happens before
files need to be copied.

.SH "FILTERING"

In all dh\-exec handled files, lines can be pre\- or post\-fixed with
a list of architectures for which the rest of the line should apply
to. All architectures and wildcards known by
\fIdpkg\-architecture\fR(1) are recognised, even negated ones.

.SH "ARCHITECTURE"

dh\-exec is built up from three layers: there is the \fBdh-exec\fR
utility, its single entry point, the only thing one will need to call.

Below that, there are the various \fIsub\-commands\fR, such as
\fIdh\-exec\-subst\fR, \fIdh\-exec\-filter\fR, \fIdh\-exec\-install\fR
and \fIdh\-exec\-illiterate\fR, which are thin wrappers around the
various dh\-exec scripts, that make sure they only run those that need
to be run.

And the lowest layer are the various scripts that do the actual work.

One can control which sub\-commands to run, or if even more
granularity is desired, one can limit which scripts shall be run,
too. See below for the options!

.SH "OPTIONS"

.IP "\fB\-\-with\fR=\fIcommand\fR[\fB,\fR\fIcommand\fR ...]" 4
Replace the list of sub\-commands to run the input through with a
custom list (where entries are separated by whitespace or
commas) that includes \fIdh\-exec\-filter\fR and \fIdh\-exec\-strip\fR
at the start and end of the queue respectively.
This option will always replace the existing list with
whatever is specified.

This can be used to explicitly set which sub\-commands to use.

The list \fBmust not\fR include the \fIdh\-exec\-\fR prefix.

Defaults to \fIsubst,install\fR.

.IP "\fB\-\-without\fR=\fIcommand\fR[\fB,\fR\fIcommand\fR ...]" 4
Inversely to the option above, this lists all the sub\-commands which
should not be used. The \fIdh-exec-filter\fR and \fIdh-exec-strip\fR
subcommands cannot be removed using this option. Use the
\fB\-\-no-defaults\fR instead.

The list \fBmust not\fR include the \fIdh\-exec\-\fR prefix.

.IP "\fB\-\-with\-scripts=\fIscript\fR[\fB,\fR\fIscript\fR ...]" 4
Replace the list of scripts to run the input through with a custom
list (where entries are separated by whitespace or commas). This
option will always replace the existing list with whatever is
specified.

This can be used to explicitly specify which scripts to use, limiting
even beyond what the \fB\-\-with\fR option is capable of.

The list \fBmust not\fR include the \fIdh\-exec\-\fR prefix.

By default it is empty, meaning there is no filtering done, and
whatever scripts the sub\-commands find, will be run.

.IP "\fB\-\-no\-defaults" 4
Most packages require the sub\-command list to start with
\fIdh\-exec\-filter\fR and end with \fIdh\-exec\-strip\fR
subcommands. If you really want to, use this option to remove
both these sub\-commands.

The \fI\-\-without\fR option does not remove these two
sub\-commands.

.IP "\fB\-\-no\-act" 4
Do not really do anything, but print the pipeline that would have been
run instead.

.IP "\fB\-\-list" 4
List the available sub\-commands and scripts, grouped by sub\-command.

.IP "\fB\-\-help\fR, \fB\-\-version\fR" 4
Display a short help or the package version, respectively.

.SH "SUB\-COMMANDS"

.TP
.B dh\-exec\-subst
Substitutes various variables (either from the environment, or from
\fIdpkg\-architecture\fR(1)).

.TP
.B dh\-exec\-filter
Filters the input in various ways (architecture restrictions, build
profiles, and so on).

.TP
.B dh\-exec\-install
An extension to \fIdh_install\fR(1), that supports renaming files
during the copy process, using a special syntax.

.TP
.B dh\-exec\-strip
Removes unrequired lines such as comments or blank lines.

.SH "ENVIRONMENT"

.PP
\fIDH_EXEC_LIBDIR\fR
.RS 4
The directory in which the wrapped sub\-commands reside. Defaults to
\fI/usr/lib/dh\-exec/\fR.
.RE

.PP
\fIDH_EXEC_SCRIPTDIR\fR
.RS 4
The directory in which the scripts that do the heavy work
live. Defaults to \fI/usr/share/dh\-exec/\fR.
.RE

.SH "FILES"

.PP
\fI$DH_EXEC_LIBDIR/dh\-exec\-*\fR
.RS 4
The various sub\-commands.
.RE

.PP
\fI$DH_EXEC_SCRIPTDIR/dh\-exec\-*\fR
.RS 4
The various scripts ran by the sub\-commands.
.RE

.SH SEE ALSO
.BR dh\-exec\-subst (1),
.BR dh\-exec\-filter (1),
.BR dh\-exec\-install (1),
.BR debhelper (7)