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