Ubuntu Manpage: dh_configpackage - add maintainer script rules to displace, hide, or transform files

Provided by: config-package-dev_5.1.2_all

NAME

       dh_configpackage - add maintainer script rules to displace, hide, or transform files

SYNOPSIS

       dh_configpackage [--displace path] [--hide path] [--undisplace path] [--unhide file]
       [--transform transformation] [debhelper options] [-n]

DESCRIPTION

dh_configpackage is a debhelper program to create "configuration packages". These
packages provide an ideal way to distribute configurations to target systems while still
affording local system administrators a degree of control over their workstations. The
motivation and philosophy behind this style of packaging is described in detail on the
config-package-dev website. Configuration packages make use of dpkg diversions and
maintainer script snippets to provide three primary operations: displacing, hiding, and
transforming files.

The displace operation consists of replacing a file on the target system. The original
file is renamed out of the way and diverted in the dpkg database. The replacement file is
then installed by the package, and the config-package-dev maintainer script snippets
create a symlink from the original name. A common use of this is to install a wrapper
script for an executable.

The transform operation is a special case of the displace operation. At build time, a
"transform script" is applied to the original source, and the result is used as the
replacement in the displace operation. A common use of this is to change one value in a
config file without needing to re-type the entire config file (and risk bit-rot).

The hide operation is yet another special case of the displace operation, namely that
there is no replacement or symlink. Instead, the file is diverted to a unique path on the
target system, thus preserving its contents. A common use of this is to suppress a
snippet file in a configuration directory (e.g. /etc/foo.d), thus disabling a specific
operation or configuration.

The displace extension is a suffix appended to the diverted versions of files, and this
suffix plus the string "-orig" is appended to the original versions of the files. The
default value is the first word of the package name. For example, the extension for
debathena-bin-example would be ".debathena". So if debathena-bin-example displaced
/bin/true, the original /bin/true would be found at /bin/true.debathena-orig and the new
version (installed by e.g. dh_install) found at /bin/true.debathena. /bin/true itself
would become a symbolic link. (For the remainder of this documentation, ".debathena" will
be used as the displace extension.)

FILES

debian/package.displace
List the files to displace, one per line, including the full path and displace
extension. For example, to displace /usr/bin/true to /usr/bin/true.debathena, you
would list "/usr/bin/true.debathena" in the file. (As with other Debhelper commands,
you can omit the initial leading slash in pathnames in the package, but these examples
retain it.)

debian/package.hide
List the files to hide, one per line, including the full path and displace extension.
As noted above, these files won't actually be removed, but merely diverted and renamed
to a unique path below /usr/share/package.

debian/package.undisplace
List the files to undisplace, one per line, including the full path and displace
extension. NOTE: This is only needed when a new version of the package no longer
needs to displace a file (for example, if an upstream bug was fixed). Packages
automatically undo all operations upon removal or deconfiguration.

debian/package.unhide
List the files to unhide, one per line, including the full path and displace
extension. NOTE: As with undisplace, this is only needed when a new version of the
package no longer needs to hide a file.

debian/package.transform
Each line in the file specifies a transformation. A transformation consists of two
space-separated fields: the full path of the target file including the displace
extension and the transformation command itself. The transformation can either be a
single shell command, or an executable file in the debian directory. The
transformation takes the original source of the file on stdin and prints its
transformation on stdout. Transformations are typically performed by perl, sed, or
awk, but there is no limitation on what can be used as a transformation.

For example, to transform /etc/school.conf by replacing all occurrences of the word
'Harvard' with the word 'MIT', you might specify the following line:

/etc/school.conf.debathena sed -e 's/Harvard/MIT/g'

Or, storing the command in a separate script:

/etc/school.conf.debathena debian/transform_school.conf.pl

If the transformation script fails, the package build fails. You can use this with
e.g. Perl's "or die" syntax to make sure that the source file of the transformation
has not changed from what you expected.

Transformation sources: Under normal operation, the source (passed on stdin) for the
transformation is the name of the diversion without the divert extension. In some
cases, you may wish to use a different source (e.g. a sample configuration file in
/usr/share/doc). You can specify this source as an optional field between the
diversion filename and the transformation. This field must begin with a '<'
immediately followed by the full path to the source. Taking the example above, we
might alter it as follows:

/etc/school.conf.debathena </usr/share/doc/school/conf.example sed -e 's/Harvard/MIT/g'

NOTE: There is no "untransform" operation. Because a transform operation is a special
case of a displace operation, the "undisplace" operation is the correct way of
removing a no-longer-needed transformation in future versions of the package.

debian/package.displace-extension
This file is used to specify the displace extension for any files diverted by this
package, if you do not want to accept the default of the first word in the package
name. It will not normally be present. (See "CAVEATS".)

OPTIONS

       -n, --noscripts
           Do not modify maintainer scripts.  This is a standard debhelper option, though you are
           strongly discouraged from using it except for debugging, as these operations rely
           heavily on the maintainer scripts.

       --displace path
       --hide path
       --undisplace path
       --unhide path
       --transform transformation
           These options allow for specifying an operation on the command line.  The argument to
           the option is the same as a single line of the corresponding file, as described above.
           You may specify multiple occurrences of --displace, or you may invoke dh_configpackage
           repeatedly with different invocations.  The most common use of this format is in a
           rules file when performing conditional operations, in an "override_dh_configpackage"
           target in the "rules" file.  See the debathena-conffile-example-1.1 package in
           /usr/share/doc/config-package-dev/EXAMPLES for one such use.

CAVEATS

       Because the displace extension is automatically generated from the package name, renaming
       the package can have unintended consequences.  If you must rename a package such that the
       first component of the name changes, specify the old extension using the
       "displace-extension" file (see above).

AUTHOR

       config-package-dev was written by Anders Kaseorg <andersk@mit.edu> and Tim Abbott
       <tabbott@mit.edu>. The debhelper port is by Geoffrey Thomas <geofft@mit.edu>.
       Documentation by Jonathan Reed <jdreed@mit.edu>.