.\" (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\-INSTALL" "1" "2024-02-27" "" "dh-exec"
.ad l
.nh
.SH "NAME"
dh\-exec\-install \- Install (and possibly rename) files.
.SH "SYNOPSIS"
\fB#! /usr/bin/dh\-exec\fR
.br
debian/default.conf => /etc/my\-package/start.conf
.br
=> /usr/bin/runme
.br
usr/bin/*
.br
[linux-any kfreebsd-any] some-arch-specific-file /usr/lib/foo/

.SH "DESCRIPTION"
Being a sub\-command of
.BR dh\-exec (1),
this program must not be ran directly, but through \fBdh\-exec\fR,
which automatically runs all available sub\-commands if run bare;
or explicitly with \fBdh\-exec \-\-with=install\fR.

It is meant to be used for the
.BR dh_install (1)
family of files, and those alone. If it finds that its input is not such a file,
it will do nothing, but echo back the contents. For a full list of
recognised files, see the \fBFILE TYPES\fR section of this manual.

The purpose of the program is to extend
.BR dh_install (1)'s
functionality, by allowing to specify a destination filename, and a way to
move (instead of copy) a file to a single package.

The first can be accomplished by a special syntax: the \fI" => "\fR mark between
a source and a destination means that the source file should be installed with
the specified destination name.

For obvious reasons, the source \fBmust not\fR be a wildcard, and the
destination in this case \fBmust\fR be a file, and not a directory.

The second extension follows a simpler syntax: any filename prefixed with
\fI"=>"\fR will be moved instead of copied to the package. This allows one to
move a file out of a directory to a package, and install the rest of the files
in the same dir into another package.

See the \fBFILTERING\fR section of
.BR dh\-exec (1)
for more information about how lines are filtered. Any non\-comment lines
without a filter will be left alone.

.SH "RESTRICTIONS"
Due to the way executable scripts are called from
.BR dh (1),
there is no way to know what options were used for the original
.BR dh_install (1).
This means, that the \fB\-\-sourcedir\fR option of \fBdh_install\fR(1) will
not work correctly when \fBdh\-exec\-install\fR is in use.

.SH FILE TYPES

The program supports
.BR dh_install (1)
and
.BR dh_installmanpages (1)
files only.

.SH "IMPLEMENTATION"
Internally, the renaming happens by creating a temporary directory
under \fIdebian/tmp/\fR, and copying (or moving, if the source was
under \fIdebian/tmp/\fR to begin with) the file there, with the new
name.

This is done this way to allow \fIdh_install\fR(1) to do the real
copying, and allow its options to continue working, even when renaming
is involved.

The temporary directory is put under \fIdebian/tmp\fR so that it will
be cleaned by
.BR dh_prep (1)
when the \fBclean\fR target gets to run. Thus, no extra code is needed
anywhere to clean up the renamed files.

.SH "ENVIRONMENT"
.PP
\fIDH_EXEC_SCRIPTDIR\fR
.RS 4
Indicates which directory the command\-specific scripts should be
sought for. If not specified, scripts will be searched for in
\fI/usr/share/dh\-exec/\fR.
.RE

.SH "FILES"
.PP
\fI$DH_EXEC_SCRIPTDIR/dh\-exec\-install\-*\fR
.RS 4
The various scripts for the higher\-level program.
.RE

.SH "VERSIONS"

The sub\-command was introduced in dh\-exec version \fI0.1\fR. Support
for
.BR dh_installmanpages (1)
files were added in version \fI0.13\fR.

.SH SEE ALSO
.BR dh (1),
.BR dh\-exec (1),
.BR dh_install (1),
.BR dh_installmanpages (1),
.BR dh_prep (1),
.BR debhelper (7)