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, dh_configpackage would create a diversion from /bin/true to
       /bin/true.debathena.orig, and create a symbolic link from /bin/true to /bin/true.debathena.  The package
       should then install its modified version at /bin/true.debathena, using e.g. dh_install.  (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 target file without the displace extension. dh_configpackage will check to make
           sure that the source file is owned by a Debian package and has not been modified locally, in order to
           ensure that unwanted changes do not show up in the result of the transformation. (If the file is
           already displaced or transformed by a config-package-dev package, it will check the original version
           of the file and use that as the transformation source, allowing a config-package-dev package to be
           built correctly on a running system where a previous version of the same package was already
           installed.)

           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'

           The full path should generally be an absolute path; however, in rare cases, it is useful to use a
           file in the current package's build directory as the transformation source.  In this case, the
           package's build directory is assumed to be clean, and no dpkg ownership check is performed.

           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).

SEE ALSO

       debhelper(7), The config-package-dev homepage <http://debathena.mit.edu/config-package-dev>

       This program is a part of config-package-dev.

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>.