packaging: maintainer script templating and control metadata

debian/README.md

@@ -58,9 +58,9 @@ pkg-linux-qcom/
 │   ├── changelog               ← Generated by 'prepare' (gitignored)
 │   ├── rules                   ← Build logic + 'prepare' target
 │   ├── clean                   ← Lists generated files for dh_clean
-│   ├── linux-image.preinst     ← Pre-install maintainer script
-│   ├── linux-image.postinst.in ← Post-install maintainer script template (depmod, initramfs, GRUB)
-│   ├── linux-image.postrm      ← Post-remove maintainer script (GRUB update)
+│   ├── linux-image.preinst.in  ← Pre-install maintainer script template (no-op)
+│   ├── linux-image.postinst.in ← Post-install maintainer script template (depmod, kernel hooks)
+│   ├── linux-image.postrm.in   ← Post-remove maintainer script template (kernel hooks)
 │   ├── config/                 ← Always-applied config fragments (committed)
 │   │   └── squashfs.config     ← SQUASHFS options for Ubuntu compatibility
 │   ├── config-available/       ← Packaging fragments, all applied to every build
@@ -89,9 +89,9 @@ pkg-linux-qcom/
 | `debian/control.in` | ✅ Committed | Template with `@KVER@` placeholder |
 | `debian/changelog.in` | ✅ Committed | Template with `@KVER@` placeholder |
 | `debian/rules` | ✅ Committed | Build rules + `prepare` target |
-| `debian/linux-image.preinst` | ✅ Committed | Pre-install maintainer script |
+| `debian/linux-image.preinst.in` | ✅ Committed | Pre-install script template (`@KVER@` substituted at build time) |
 | `debian/linux-image.postinst.in` | ✅ Committed | Post-install script template (`@KVER@` substituted at build time) |
-| `debian/linux-image.postrm` | ✅ Committed | Post-remove maintainer script |
+| `debian/linux-image.postrm.in` | ✅ Committed | Post-remove script template (`@KVER@` substituted at build time) |
 | `debian/config/*.config` | ✅ Committed | Always-applied config fragments |
 | `debian/config-available/*.config` | ✅ Committed | Packaging fragments, all applied to every build |
 | `debian/dkms-modules` | 🔄 Generated | Produced by `make -f debian/rules prepare DKMS_MODULES=...` |
@@ -175,8 +175,8 @@ Debian's official `linux` source package and Ubuntu OEM kernels.
 
 ```
 KVER = <base-version> + LOCALVERSION
-     = 7.0.0-rc2        + -qcom-next-20260826
-     = 7.2.0-qcom-next-20260826
+     = 7.2.0-rc7        + -qcom-next-20260826
+     = 7.2.0-rc7-qcom-next-20260826
 ```
 
 `build-kernel.sh` passes `LOCALVERSION` to `prepare`, which determines KVER by:
@@ -336,9 +336,46 @@ Virtual packages provided: `linux-image`, `linux-image-arm64`
 Maintainer scripts:
 - `preinst` — no-op; coexistence of multiple kernel versions is handled by
   dpkg automatically (each version has a unique package name)
-- `postinst` — runs `depmod`, then `/etc/kernel/postinst.d/` hooks
-  (triggers `update-initramfs` and `update-grub`)
-- `postrm` — runs `/etc/kernel/postrm.d/` hooks (triggers `update-grub`)
+- `postinst` — runs `depmod`, then the kernel `postinst.d` hooks
+  (triggers `update-initramfs`, `update-grub` and, where systemd-boot is
+  installed, the loader entry and `loader.conf` generation)
+- `postrm` — runs the kernel `postrm.d` hooks (drops the removed kernel's
+  bootloader entries)
+
+Both hook directories are run: `/etc/kernel/{postinst,postrm}.d/` for hooks
+the administrator installs, and `/usr/share/kernel/{postinst,postrm}.d/` for
+hooks a package ships. The second directory is where systemd-boot installs
+`zz-systemd-boot` from forky onwards, so a package that runs only the first
+one produces an unbootable install there. Both scripts dispatch through
+`linux-run-hooks(1)`, which runs the two directories in the documented order
+and sets `DEB_MAINT_PARAMS`.
+
+The image package `Pre-Depends: linux-base (>= 4.12~)`, the release that ships
+that command, as Debian's own `linux-image` packages do — it runs from our
+postinst, so it has to be configured before we are. It is a plain field in
+`control.in`, not generated per suite: every suite in the build matrix carries
+4.12 or later (trixie has 4.12.1, forky and sid are ahead of it, resolute has
+4.15ubuntu5), so there is no suite to make an exception for. A suite whose
+`linux-base` predates 4.12 — noble, say, which the matrix does not build —
+refuses the package outright rather than installing it and silently skipping
+the hooks.
+
+There is no `run-parts` fallback, deliberately. One that ran `/etc/kernel/*.d/`
+alone would reintroduce the silent unbootable install on any system that got
+past the pre-dependency, which is the failure this arrangement exists to
+prevent; the postinst therefore calls the command unguarded, as Debian's does.
+The postrm is the exception and tests for it first: `Pre-Depends` holds while
+the package is installed, not while it is being removed, since dpkg may remove
+`linux-base` in the same run. It warns and carries on there, again as Debian's
+does — the cost of a skipped hook at removal is a stale bootloader entry, not
+an unbootable system, and a kernel must always be removable.
+
+Each script is generated at build time from its `debian/linux-image.<script>.in`
+template, with `@KVER@` substituted for the kernel release, so every script
+names its own kernel version rather than deriving it from the package name at
+run time. `override_dh_installdeb` in `debian/rules` substitutes each template
+that exists into `debian/linux-image-<KVER>.<script>`; adding a `prerm` is a
+matter of adding `debian/linux-image.prerm.in`.
 
 ### `linux-headers-<KVER>` — Kernel headers
 
@@ -368,11 +405,22 @@ script (`scripts/package/builddeb`). Debug symbols are installed under
 both can be installed simultaneously.
 
 Installed paths:
-- `/usr/lib/debug/lib/modules/<KVER>/` — per-module debug symbols extracted via `objcopy --only-keep-debug`
+- `/usr/lib/debug/lib/modules/<KVER>/kernel/…` — per-module debug symbols extracted via `objcopy --only-keep-debug`, mirroring where each in-tree module installs
+- `/usr/lib/debug/lib/modules/<KVER>/extra/…` — the same for bundled DKMS modules
+- `/usr/lib/debug/.build-id/<xx>/<rest>.debug` → symlink to the module's debug file, one per module
 - `/usr/lib/debug/lib/modules/<KVER>/vmlinux` — unstripped vmlinux (for `perf`, `crash`)
 - `/usr/lib/debug/boot/vmlinux-<KVER>` → symlink to vmlinux (for `systemtap`)
 - `/usr/lib/debug/vmlinux-<KVER>` → symlink to vmlinux (for `kdump-tools`)
 
+A module's debug file is reachable two ways, as in `builddeb`: by the path that
+mirrors the module's own install path, and by build ID. The build-id path is
+what `gdb` and `debuginfod` consult first, and it is the only one that holds
+however the module was addressed — a tool that opens it as
+`/usr/lib/modules/…` rather than `/lib/modules/…` looks under
+`/usr/lib/debug/usr/lib/modules/…`, which the mirrored path does not answer.
+A module built without a build ID is still shipped at the mirrored path; the
+build sends a warning to the log and no symlink is made.
+
 Depends on `linux-image-<KVER>` (same version).
 
 Virtual packages provided: `linux-image-dbg`

debian/control.in

@@ -2,19 +2,22 @@ Source: @SRCPKG@
 Section: kernel
 Priority: optional
 Maintainer: Bjordis Collaku <bcollaku@qti.qualcomm.com>
-Standards-Version: 4.6.2
+Standards-Version: 4.7.4
 Build-Depends: debhelper-compat (= 13),
                bc, bison, flex, libssl-dev, libelf-dev, dwarves,
                python3, kmod, cpio, rsync, pkg-config, gcc, make@DKMS_BUILD_DEPENDS@
 Homepage: https://kernel.org
+Vcs-Git: https://github.com/qualcomm-linux/pkg-linux-qcom.git
+Vcs-Browser: https://github.com/qualcomm-linux/pkg-linux-qcom
 Rules-Requires-Root: binary-targets
 
 Package: linux-image-@KVER@
 Architecture: arm64
-Depends: ${misc:Depends}, ${shlibs:Depends}
-Recommends: initramfs-tools | dracut | linux-initramfs-tool
+Pre-Depends: linux-base (>= 4.12~)
+Depends: ${misc:Depends}, ${shlibs:Depends},
+         initramfs-tools | dracut | linux-initramfs-tool
 Suggests: linux-headers-@KVER@
-Provides: linux-image, linux-image-arm64
+Provides: linux-image, linux-image-arm64@DKMS_PROVIDES@
 Description: Qualcomm ARM64 Linux kernel image @KVER@
  Kernel image, modules, and DTBs for kernel release @KVER@ on ARM64
  Qualcomm platforms.
@@ -28,7 +31,7 @@ Description: Qualcomm ARM64 Linux kernel image @KVER@
 
 Package: @BINPKG@
 Architecture: arm64
-Depends: linux-image-@KVER@, ${misc:Depends}
+Depends: linux-image-@KVER@ (= ${binary:Version}), ${misc:Depends}
 Description: Qualcomm ARM64 Linux kernel image (meta-package)
  This meta-package always depends on the latest @BINPKG@ kernel image
  for ARM64 Qualcomm platforms. Installing this package ensures that
@@ -47,7 +50,7 @@ Description: Qualcomm ARM64 Linux kernel headers @KVER@
 
 Package: @HDRPKG@
 Architecture: arm64
-Depends: linux-headers-@KVER@, ${misc:Depends}
+Depends: linux-headers-@KVER@ (= ${binary:Version}), ${misc:Depends}
 Description: Qualcomm ARM64 Linux kernel headers (meta-package)
  This meta-package always depends on the latest @HDRPKG@ kernel headers
  for ARM64 Qualcomm platforms.

debian/linux-image.postinst.in

@@ -1,18 +1,37 @@
 #!/bin/sh
+# postinst for linux-image-@KVER@
+#
+# Generated from debian/linux-image.postinst.in by debian/rules at build time;
+# @KVER@ is substituted with the kernel release (uname -r).
 set -e
 
 KVER="@KVER@"
 
-# Auto-generated code from dh_installmodules (depmod calls) will be inserted here
+# Auto-generated debhelper code (dh_installmodules' depmod call) is inserted
+# here.
 #DEBHELPER#
 
-# Run kernel postinst.d hooks (triggers initramfs generation and bootloader updates)
-if [ "$1" = "configure" ] && [ -d /etc/kernel/postinst.d ]; then
-    echo "linux-image: running /etc/kernel/postinst.d hooks for $KVER..."
+# Run the kernel postinst.d hooks: initramfs generation, bootloader entries.
+#
+# Hooks live in two directories: /etc/kernel/postinst.d for the ones the
+# administrator installs, and /usr/share/kernel/postinst.d for the ones a
+# package ships. systemd-boot's zz-systemd-boot moved to the latter in forky,
+# so running only the /etc directory there leaves the loader entry and
+# loader.conf unwritten and the kernel unbootable.
+#
+# linux-run-hooks(1) runs both directories in the right order and sets
+# DEB_MAINT_PARAMS. It ships in linux-base 4.12, which the package
+# pre-depends on, so it is here whenever this script runs: dpkg configures a
+# pre-dependency before it unpacks us. It is called unguarded for that reason,
+# as Debian's own linux-image postinst calls it. A fallback that ran the /etc
+# directory alone would be worse than none, since it would reintroduce exactly
+# the silent unbootable install described above.
+if [ "$1" = "configure" ]; then
+    echo "linux-image: running kernel postinst.d hooks for $KVER..."
     image_path="/boot/vmlinuz-$KVER"
-    DEB_MAINT_PARAMS="$*" run-parts --verbose --exit-on-error \
-          --arg="$KVER" --arg="$image_path" /etc/kernel/postinst.d
+    linux-run-hooks image postinst "$KVER" "$image_path" -- "$@"
 fi
 
 echo "linux-image: installed kernel $KVER (reboot to use it)."
+
 exit 0

debian/linux-image.postrm.in

@@ -0,0 +1,43 @@
+#!/bin/sh
+# postrm for linux-image-@KVER@
+#
+# Generated from debian/linux-image.postrm.in by debian/rules at build time;
+# @KVER@ is substituted with the kernel release (uname -r).
+set -e
+
+KVER="@KVER@"
+
+# Auto-generated debhelper code (dh_installmodules' depmod call) is inserted
+# here.
+#DEBHELPER#
+
+# Run the kernel postrm.d hooks: zz-update-grub, and on forky zz-systemd-boot,
+# which drops the removed kernel's loader entry. This is the standard Debian
+# way to tidy the bootloader after a kernel is removed.
+#
+# The hooks live in the same two directories as the postinst.d ones and are
+# dispatched the same way, through linux-run-hooks(1). See the postinst for
+# the full reasoning.
+#
+# Unlike the postinst, this one tests for the command first. Pre-Depends
+# guarantees linux-base while the package is installed, not while it is being
+# removed: dpkg is free to remove linux-base in the same run, and on purge it
+# may already be gone. Debian's own linux-image postrm guards it for the same
+# reason and warns rather than failing, so that a kernel can always be
+# removed; the cost of a missing hook run here is a stale bootloader entry,
+# not an unbootable system.
+#
+# A failing hook must not fail the removal either -- dpkg would leave the
+# package half-removed -- so the dispatch is allowed to fail.
+if [ "$1" = "remove" ]; then
+    image_path="/boot/vmlinuz-$KVER"
+    if command -v linux-run-hooks >/dev/null 2>&1; then
+        echo "linux-image: running kernel postrm.d hooks for $KVER..."
+        linux-run-hooks image postrm "$KVER" "$image_path" -- "$@" || true
+    else
+        echo "linux-image: linux-base is gone; skipping the postrm.d hooks for $KVER." >&2
+        echo "linux-image: a bootloader entry for $KVER may be left behind." >&2
+    fi
+fi
+
+exit 0

debian/linux-image.preinst.in

@@ -0,0 +1,20 @@
+#!/bin/sh
+# preinst for linux-image-@KVER@
+#
+# Generated from debian/linux-image.preinst.in by debian/rules at build time;
+# @KVER@ is substituted with the kernel release (uname -r).
+set -e
+
+# Auto-generated debhelper code is inserted here.
+#DEBHELPER#
+
+# Nothing to do before unpacking. Each kernel version is a uniquely named
+# package (the version is part of the package name), so dpkg handles the
+# coexistence of multiple installed kernels on its own; there is no need to
+# remove other kernel versions here.
+#
+# Kernels are removed explicitly by the administrator:
+#   sudo dpkg -r linux-image-@KVER@
+# or by apt autoremove once the package is no longer needed.
+
+exit 0