News about the debhelper toolchain
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512
We would like to share the following news about the debhelper toolchain
with you! :)
Overview of this rather long email:
* Making Debian packaging more DRY and declarative
* Highlights of current changes in compat 13
* Use of compat 11 is actively discouraged
* Removals and deprecations of features and compat levels
* Overview of which features are available in a given suite/backports
# Making Debian packaging more DRY and declarative
Over the past few Debian releases, we have implemented small steps
towards supporting more declarative and DRY packaging paradigms. Some
notably steps include (in no particular order):
* The "debhelper-compat (= 12)" build-dependency to replace
"Build-Depends: debhelper (>= 12~)" and "echo 12 > debian/compat".
* The "dh-sequence-<foo> build-dependency" to replace the
"--with <foo>" parameter to dh in the debian/rules.
- Note that third-party add-ons may not have added the relevant
Provides to support this change.
* Support for making "dh-sequence-<foo>" conditional by moving it to
Build-Depends-Indep, or by adding an architecture restriction or
by adding a build-profile requirement. This makes it easier for
you to support porters and cross-builders in reducing the
build-dependency requirements of your package. (#836699)
- A small number of add-ons are not compatible with this feature.
In general, dh(1) will detect this and abort when an error when
it is detected.
* Support for new execute_before_X and execute_after_X targets. These
are similar to regular override targets but are injected before and
after the command X without affecting how X itself is called. This
avoids having to repeat X in an override target when all you wanted
was to run another command before or after X.
- This feature is only enabled for compat 10 or later due to the
complexity involved in supporting this for compat 9 and earlier.
* In compat 13, the dh command sequencer will skip any hook or override
target for dh_auto_test, dh_dwz, and dh_strip if nocheck and nostrip
are present in DEB_BUILD_OPTIONS. This avoids a papercut where
overriding the commands often breaks the nocheck / nostrip
functionality (unless you remember to inject the correct makefile
runes).
Note that most of these changes requires recent versions of debhelper.
Please see the final section of this mail for guidance on whether you
can use them if you want to support older releases of Debian with the
same packaging.
# Highlights of current changes in compat 13
Here is a brief list of a *subset* of the current changes planned for
the future compat 13.
* dh_missing now defaults to --fail-missing.
* debhelper generate a temporary writable directory for $HOME
and $XDG_RUNTIME_DIR plus clear all remaining XDG_* variables.
This simplifies packaging of tools that insist on writing to
$HOME.
* dh_install (and other helpers) will in compat 13 support basic
substitution variables enabling you to reference paths
containing spaces or dynamic values such as DEB_HOST_MULTIARCH.
- Note this is *not* intended as a complete replacement of
dh-exec(1).
* The dh command sequencer will in compat 13 skip any hook or override
target for dh_auto_test, dh_dwz, and dh_strip if nocheck and nostrip
are present in DEB_BUILD_OPTIONS. This avoids a papercut where
overriding the commands often breaks the nocheck / nostrip
functionality (unless you remember to inject the correct make runes).
* The dh_* commands no longer accepts arbitrary abbreviations of their
command line arguments. This enables dh(1) to optimize the sequence
better as it can now reliably detect which commands react to the
given command line arguments.
Compat 13 is still open for changes and suggestion. If you have any
requests or suggestions, feel free to submit them via a bug in the
BTS or a MR request on salsa. You are also very welcome to test
compat 13 and file bugs if you discover anything not working as
advertised. Though please be aware of future changes to debhelper
if you upload any packages to unstable that relies on compat 13.
# Use of compat 11 is actively discouraged
While it is possible to use compat 11 without triggering this
issue, we have discouraged it as compat 11 has an unsafe and
buggy default handling in service handling.
While this is the first time a compat have been discouraged
(before being deprecated), please remember that a working
package with this bug is better than a broken package!
We have identified an unfortunate issue in compat 11 related to how
debhelper handles init.d and systemd services. A known problem is
that "apt install X && apt remove X && apt install X" will cause
services to not be started automatically on the second install,
requiring the admin to start it manually.
This issue only manifests in compat 11 and only for packages with
init.d / systemd services. Unfortunately, retroactively fixing
compat 11 will be non-trivial and error-prone as it involves
interaction between multiple helpers and how/whether options for a
given helper affect init.d or/and systemd based services.
The general recommendation solution for packages is:
* Move forward to compat 12 unless you need to support Debian
stretch. (Remember to check upgrade check list in "man debhelper"
*and test* the compat bump)
If you need to support Debian stretch or cannot upgrade to compat 12
for other reasons, please consider the following options:
* If the package do not ship *any* init.d or systemd services,
then you /can/ choose to stay with compat 11 without being
affected.
- This is the rule of thumb for whether your package is
affected. There may be exceptions that cannot fit in this
mail (if in doubt, test the "install, remove, install"
cycle and see if the service is in the correct state).
* Roll back to compat 10 globally in your package. (This is the
"simple" choice but assumes you are not requiring a compat 11
feature)
* Override dh_installsystemd to remove it from the sequence and
override dh_installinit to run dh_systemd_enable, dh_installinit
and dh_systemd_start (in that order!). All three helpers must
be run with DH_COMPAT=10 as an environment variable (e.g.
"DH_COMPAT=10 dh_installinit") to make them use compat 10
instead of the default. (This is the "advanced" option; use
only if you think it is worth the work).
* There may also be cases where staying with compat 11 and
accepting the bug is the lesser evil.
As mentioned; please remember to test your migration away from
compat 11 or your work around. This issue caused by compat 11
is nothing compared to the disruption caused by a frenzy of
inadequately tested uploads to unstable.
# Removals and deprecations of features and compat levels
To keep the codebase manageable while continuing to improve debhelper,
we periodically deprecate and remove obsolete features and workflow.
This brings us to the following deprecations and removals.
* Removal of manual sequence control arguments for dh
(--before/--after/--until/--remaining). This has already been
implemented in debhelper/12.4 and facilitated the refactoring
needed to implement the following improvements:
- Conditional debhelper add-ons.
- The new hook targets (execute_before_X and execute_after_X)
- Support for skipping override/hook targets under nostrip/nocheck
* dh_gconf will be removed soon as it is no longer useful and (almost)
everything has stopped using it. Please see #908845 for more
details.
* The now unused --ignore option has been removed. It had a very
narrow use-case in preset day and all packages have migrated away
from using it now.
* Compatibility level 9 is hereby officially deprecated and will
trigger deprecation warnings soon. We recommend people migrate
their packages to compat 12 or 10 depending on whether oldstable
support is needed. Please note that compat 11 is actively
discouraged in some cases. (see the section above).
# Overview of which features are available in a given suite/backports
The debhelper toolchain is continuously seeing improvements. Among
other to better defaults, less micromanagement, and better
performance. Where reasonably possible, we attempt to make these
changes available transparently. However, there are many cases where
people cannot immediately rely on these improvements because they are
targeting releases/distributions where debhelper does not yet have
these features.
The following is an incomplete list of features now available by
Debian release/suite, which we hope you will find useful in order to
make your packaging simpler.
## If you target to stretch
If your target is vanilla oldstable (stretch), you can now assume
features available in debhelper/10.2.5:
* compat 10
* dh_installchangelogs finds more changelog files by default.
* automatic dbgsym packages are universally available.
* dh_clean supports removal of directories listed in d/clean (when
explicitly marked as a directory)
* debhelper now uses debian/.debhelper for (new) internal state,
which makes it easier to manage .gitignore files.
* Improved cross-building support for cmake-based packages.
## If you target buster or/and stretch-backports
If your target is vanilla stable (buster) or oldstable-backports
(stretch-backports), you can now assume features available in
debhelper/12.1.1:
* compat 12
- dh_makeshlibs -V is default meaning less micro-management for
udeb library packages.
- dh_installinitramfs + dh_installsystemduser run by default
- More reliable detection of ELF files (dh_strip + dh_shlibdeps)
* meson (+ninja) and cmake+ninja build system
* The ability to use debhelper-compat (= X) and dh-sequence-X in
Build-Depends to declare debhelper compat level and used dh addons.
- Note: dh-sequence-X cannot be used conditionally in buster nor
stretch-backports. This requires buster-backports or bullseye.
* Derivatives or custom build processes can use DH_EXTRA_ADDONS
environment variables to inject global specific addons in all
packages relying on dh.
* dh_installsystemduser is available.
* dh_installchangelogs automatically detects and uses upstream
installed changelog (avoids duplicated changelog warning from
lintian in single binary source packages)
* Cross-building for QT5 working out of the box in many cases
- This item is buster-only as there are some changes on the QT5
side for this to work.
## If you target bullseye or/and buster-backports
If you have no particular backwards compat support targets or are
targeting stable-backports (buster-backports), you can assume the
latest features available in debhelper (12.9):
* dh_installdeb can substitute more variables into your maintscripts
for you - both built-in values and custom ones (the latter via -D).
Please see dh_installdeb(1), section "SUBSTITUTION IN MAINTAINER
SCRIPTS" and the description of -D/--define parameter, for more
information.
- This requires debhelper (>= 12.2~).
* dh_makeshlibs can often automatically detect udebs and generate
shlibs without needing an explicit --add-udeb.
- Please test before blindly dropping an --add-udeb to avoid
unnecessary breakage for the d-i team!
- Please add a Build-Dependency on debhelper (>= 12.6~) to avoid
some bugs in the early implementations.
* dh now support conditional addons via build-dependencies to
simplify bootstrapping and cross-building.
- This requires debhelper (>= 12.7.2~) to work.
* dh now supports execute_before_X and execute_after_X targets
in addition to override_X targets.
- This feature requires debhelper (>= 12.8~) to work AND compat 10
or later.
* The debhelper tool suite now have basic support for cross-building
Perl XS modules (provided the Build-Depends on perl-xs-dev)
- Assume this is bullseye-only as there has (and is) ongoing work
on the Perl side.
-----BEGIN PGP SIGNATURE-----
iQIzBAEBCgAdFiEE8f9dDX4ALfD+VfsMplt42+Z8eqwFAl41jRUACgkQplt42+Z8
eqxVKg//cMDxmKi0tBX660uHFy27aPgSbDDcW9TwmUaY96DQsc4qIC4baDBiXR0q
qP1//v8VhaF5eZ+ODSRLBil2eSCKYeljWIDt0CTYrG4duPN6+niV0KBEzTwSxPPH
SXSfb6JApRlwKdUZ0KGsLqG2ue+uwpND58VSrof59d1VOfYtxnCx6hx/GNc2Tg24
1wTqX28MWGm2sBF+DKrBDN0KscjgTv4XJ5/yVqehftn7IQ9mmNP+0WEZrLNsuRiU
JMrxFRTQSLQ4Okj6Q4dkPGeMF5LqdZaS2N+QmrIQL1OAeCVye8GOAFa7GDFrMkD3
X2+Jf9shNBWwp2tok+D1pTyN/fGE7O2T3BwcCB7SV1UzO2rKP4ZaoGDplkJ5qYiZ
78h90u9Msrq2nMAz8sTMFGNwfeI2z7J841xTZ/uXtAXpQ5IXFz+NC4UWXCrYKcLL
qkzT9MDR7RPHbSvHY5wK8cWei3L+qdRdMAW1/+gG16oDGMSdByPNFeQ9mAga4IeI
VCfj1YLbp6y7gfWdFfSc/7wTpTNxBrLgHn2C8PwTacA1cZ78wJgWmZZqfuDwn00l
GxVR11eGYfPEpxp3j6jhjf/fLadHTun6Z/e5LErD6IaGSY1TGvKINsSCM2psRHim
gh9YOA9BB62TJfGyQayrZmqzbCn8JuIimiWKpZrdjsxGIdokB54=
=L/Za
-----END PGP SIGNATURE-----
Reply to: