dpkg-maintscript-helper

dpkg-maintscript-helper [--root=dir] command arguments...

--root=dir
    Specify an alternate root directory. For internal use by dpkg only, e.g., when building images.

rm_conffile old-conffile [package-version] [arch]
    Removes an old conffile (configuration file). This command handles scenarios where a conffile might have been removed or renamed in a new package version. It safely removes the file if it's no longer managed by the package or if it's no longer needed after a specified version. The package-version and arch arguments are optional and used for conditional removal.

mv_conffile old-conffile new-conffile [package-version] [arch]
    Moves an old conffile to a new path. This is crucial when a configuration file changes its location between package versions. It ensures that user modifications are preserved by moving the existing conffile, rather than overwriting it. The package-version and arch arguments are optional and used for conditional moves.

rm_links link-or-dir ... [package-version] [arch]
    Removes symbolic links that were previously managed by the package but are no longer needed. It can also remove directories that were managed via symlinks. The package-version and arch arguments are optional and used for conditional removal.

rm_diversion diversion-file [package-version] [arch]
    Removes a dpkg diversion. This is used when a package no longer needs to divert a specific file. It ensures the diversion is correctly removed from dpkg's state. The package-version and arch arguments are optional and used for conditional removal.

rm_symlink_to_dir symlink-to-dir [package-version] [arch]
    Removes a symbolic link that points to a directory. This is a specialized version of rm_links for directory symlinks, often used when a directory previously represented by a symlink becomes a real directory. The package-version and arch arguments are optional and used for conditional removal.

install_alternatives alternative-name [package-version] [arch]
    Installs or updates a symlink managed by the 'alternatives' system. This helps ensure that the package's alternative symlink is correctly set up, especially during upgrades. The package-version and arch arguments are optional and used for conditional operations.

run_command command ... [package-version] [arch]
    Executes an arbitrary command. This command acts as a wrapper, primarily useful for allowing maintainer scripts to run commands conditionally based on package version or architecture. The package-version and arch arguments are optional and used for conditional execution.

dpkg-maintscript-helper is a utility designed to simplify and standardize common operations within Debian package maintainer scripts (e.g., postinst, prerm, postrm). Its primary goal is to help maintainers manage tasks like moving or removing configuration files, symbolic links, or diversions safely and robustly during package upgrades or removals.

Before its introduction, maintainers often had to write complex and error-prone shell logic to handle various upgrade scenarios, leading to potential package breakage or orphaned files. This helper provides idempotent commands that check the current state before performing actions, ensuring that operations are carried out only when necessary and can be safely re-run multiple times (e.g., during re-installation or interrupted upgrades).

By standardizing these common routines, dpkg-maintscript-helper significantly reduces the complexity and error rate of maintainer scripts, making Debian packages more reliable and easier to upgrade for users. It is an essential tool for robust package maintenance in the Debian ecosystem.

Idempotency is Key: All commands provided by dpkg-maintscript-helper are designed to be idempotent. This means they can be safely called multiple times without adverse effects, even if the desired state has already been achieved. Maintainer scripts should leverage this property and not add complex checks to avoid re-running commands.

Context of Use: This utility is strictly intended for use within Debian package maintainer scripts (e.g., postinst, prerm, postrm). It relies on the environment and state managed by dpkg during package operations.

Version Argument Usage: When specifying package-version and arch, these arguments are used to make operations conditional. The action will only be performed if the installed version of the package (or the old version during removal) is less than or equal to the package-version provided. This is crucial for handling staggered upgrades across different package versions.

Error Handling: The command exits with a non-zero status if an error occurs. Maintainer scripts should check the exit status and handle errors appropriately.

Integration with dpkg: Be cautious when mixing dpkg-maintscript-helper calls with direct dpkg-divert or update-alternatives calls, as the helper aims to provide a safer, version-aware wrapper for some of those functionalities.

Most sub-commands accept optional package-version and arch arguments. When provided, the command will only execute if the currently installed package version (or the original package version during a removal) is less than or equal to the specified package-version. This allows maintainer scripts to apply changes incrementally across different package versions, ensuring that an operation for an older version is not accidentally applied to a system that has already passed that version, or vice-versa. The arch argument provides an additional layer of conditionality based on architecture, useful for multi-arch packages.

dpkg-maintscript-helper is primarily invoked from within the postinst, prerm, and postrm scripts of a Debian package. For instance, rm_conffile is typically called in postinst during an upgrade to clean up old conffiles, or in postrm during removal to ensure a clean uninstall. The helper handles the complexities of dpkg's internal state and ensures that operations are performed correctly based on the upgrade scenario (e.g., install, upgrade, remove, purge).

dpkg-maintscript-helper was introduced to address common challenges and pitfalls faced by Debian package maintainers when writing maintainer scripts. Historically, operations like migrating configuration files or removing old symlinks required maintainers to write complex, error-prone shell logic to handle various upgrade paths, including interrupted upgrades or downgrades. This often led to orphaned files, broken packages, or inconsistent system states.

By providing a set of standardized, idempotent, and version-aware sub-commands, dpkg-maintscript-helper significantly simplified script development and improved the robustness of package upgrades across the Debian distribution. Its development was driven by the need to reduce common bugs and ensure smoother transitions between package versions, making the Debian packaging ecosystem more reliable.

dpkg(1), dpkg-divert(1), update-alternatives(1), deb-postinst(5), deb-prerm(5), deb-postrm(5)