kernel: add opt-in linux-image-dbg package with debug info by iav · Pull Request #10244 · armbian/build

iav · Jul 20, 2026

Description

Kernels built with CONFIG_DEBUG_INFO produce a vmlinux with full debug info, but only the stripped Image is packaged — vmlinux is discarded with the build tree, leaving nothing to analyze kdump vmcores with. Debian ships it as linux-image-*-dbg, Ubuntu as -dbgsym ddebs, Fedora as kernel-debuginfo.

This adds KERNEL_DBG_PACKAGE=yes (default no) producing a linux-image-<BRANCH>-<LINUXFAMILY>-dbg package (Debian-style -dbg suffix) with vmlinux at /usr/lib/debug/lib/modules/<version>/vmlinux — the standard search path of crash, drgn and gdb. Split DWARF (CONFIG_DEBUG_INFO_SPLIT) is rejected with a rebuild hint: a vmlinux-only package would be an empty shell there.

Exact build pairing: linux-image declares a versioned virtual Provides: linux-image-<BRANCH>-<LINUXFAMILY>-build (= artifact_version), and the dbg package carries a versioned Depends on it. Deployment reversioning rewrites only the Version: field, so the pairing survives it and dpkg refuses to install debug symbols for a kernel built from any other inputs. With KERNEL_DBG_PACKAGE=yes the artifact hash additionally covers KERNEL_COMPILER (prefix), the probed compiler version, KERNEL_EXTRA_CFLAGS, and the sources of the make-time hooks (kernel_make_config, custom_kernel_make_params); the kernel-version-toolchain extension is force-enabled for a visible toolchain part in the version string. config_dump emits KERNEL_DBG_PACKAGE and the compiler inputs so the artifact reducer never coalesces dbg and non-dbg targets.

Scope: an opt-in for local builds; the feature is not wired into the apt repository publishing pipeline.

Why a build variable and not an extension: there is currently no hook point to add a package to the kernel artifact — artifact_map_packages is built after the last extension hook runs, and without an entry in that map the deb would not be part of the deb-tar artifact and thus invisible to the ORAS cache. The dbg package's siblings (dtb, headers, libc-dev) are all gated by core variables; this follows the same pattern.

Cache correctness: the variable is hashed into the artifact version only when enabled — regular builds keep their existing cache entries.

Cost: vmlinux with DWARF5 is ~0.5–1 GB unpacked (measured deb: ~520 MB for meson64-edge) — hence opt-in.

How Has This Been Tested?

./compile.sh kernel BOARD=odroidn2 BRANCH=edge KERNEL_DBG_PACKAGE=yes — deb produced; vmlinux is with debug_info, not stripped (BuildID present); gdb resolves info line start_kernel → init/main.c:1018 from the packaged vmlinux
Boot-environment install matrix: the pair installs; dbg without/against a foreign image is refused by dpkg in both directions; replacing installed kernels is clean; a bare dpkg -i of the image with a stale dbg present is caught by apt-get check and healed by --fix-broken
Reversioned control verified: Version: 26.08.0-trunk with the versioned -build pairing intact
5 bot-review rounds in the staging PR (kernel: add opt-in linux-image-dbg package with debug info iav/armbian#192), all findings fixed or scoped

Checklist:

My code follows the style guidelines of this project
I have performed a self-review of my own code
My changes generate no new warnings

Summary by CodeRabbit

New Features
- Added opt-in kernel debug package generation for builds configured with KERNEL_DBG_PACKAGE=yes.
- Generated debug packages now include kernel symbols and are emitted as an additional -dbg variant.
- Debug packages are paired with the exact matching kernel build via strict version pinning.
Bug Fixes
- Prevented debug and non-debug kernel artifacts from sharing cached outputs by separating hash/version inputs.
- Improved validation of debug-symbol configuration, with clear failure/warnings for unsupported setups (e.g., missing required debug inputs).

coderabbitai · Jul 20, 2026

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

@coderabbitai resume to resume automatic reviews.
@coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

▶️ Resume reviews
🔍 Trigger review

📝 Walkthrough

Walkthrough

Optional kernel debug packaging now selects the toolchain extension, includes debug inputs in artifact versioning, and creates a version-linked Debian package containing vmlinux.

Changes

Kernel debug-symbol packaging

Layer / File(s)	Summary
Debug configuration and artifact identity `lib/functions/configuration/main-config.sh`, `lib/functions/artifacts/artifact-kernel.sh`	`KERNEL_DBG_PACKAGE=yes` enables `kernel-version-toolchain`; compiler, flags, resolved compiler version, and make hooks contribute to kernel artifact identity.
Debug Debian package generation `lib/functions/artifacts/artifact-kernel.sh`, `lib/functions/compilation/kernel-debs.sh`	Debug builds add a `linux-dbg` artifact, pin the image package to its matching build package, and package `vmlinux` with validation and dependency metadata.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant BuildConfig
  participant ArtifactVersioning
  participant DebianPackaging
  participant DebugPackage
  BuildConfig->>ArtifactVersioning: enable debug inputs and toolchain
  ArtifactVersioning->>DebianPackaging: produce distinct linux-dbg artifact mapping
  DebianPackaging->>DebugPackage: invoke debug package callback
  DebugPackage->>DebugPackage: validate and install vmlinux
  DebugPackage-->>DebianPackaging: write pinned Depends and Provides metadata

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: an opt-in kernel debug package with debug information.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@lib/functions/compilation/kernel-debs.sh`:
- Line 654: Remove armbian-$BRANCH from the Provides list for the debug symbols
package, leaving only the debug-package providers so apt cannot treat it as a
kernel image provider.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ca5819ef-8743-4bd4-8619-feb4b2e17d9b

📥 Commits

Reviewing files that changed from the base of the PR and between 78fd7da and d0025a4.

📒 Files selected for processing (3)

lib/functions/artifacts/artifact-kernel.sh
lib/functions/compilation/kernel-debs.sh
lib/functions/configuration/main-config.sh

rpardini · Jul 20, 2026

Interesting. How does one use such debug info, in practice?

iav · Jul 20, 2026

Four practical uses, all of which need exactly the vmlinux the running kernel was built from.

1. Crash analysis: kdump + crash. With kdump enabled, the capture kernel writes a vmcore on panic. crash can't open it without an uncompressed vmlinux carrying DWARF — the compressed Image/vmlinuz from linux-image won't do. With the package it's just:

crash /usr/lib/debug/lib/modules/$(uname -r)/vmlinux /var/crash/*/vmcore

then bt, ps, log, struct, dis over the dump.

2. Live introspection: drgn. drgn reads /proc/kcore and takes its types from the debug vmlinux, so you can walk kernel structures on a running system — no rebuild, no separate debug kernel. Handy when the bug only shows up on the actual board and not in the lab.

3. gdb on kcore or on a dump. gdb vmlinux /proc/kcore (with CONFIG_PROC_KCORE) gives you info line, symbol resolution and address→source mapping. The same vmlinux turns a bare address from an oops/BUG into file.c:line.

4. perf probe and tracing. Probing by source line or by local variable name requires DWARF; without it you only get function names from kallsyms.

The point of doing it this way: debug info is only useful if it belongs to that exact binary. So the dbg package has a strict Depends on a versioned virtual package provided by linux-image — the pair can't drift apart, not across re-versioning and not across compilers: the artifact hash version carries a toolchain part (gcc13.3 / clang18.1), so gcc and clang builds of the same kernel version get distinct artifact versions and can never be mixed.

It's opt-in (KERNEL_DBG_PACKAGE=yes) because the package is large (hundreds of MB of uncompressed vmlinux) and useless to ordinary users.

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/data-sync-maintainers.yml:
- Around line 14-19: Remove the unsupported metadata permission entry from the
workflow’s top-level permissions block, leaving the valid contents,
pull-requests, and issues permissions unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 3da1d094-1eb1-4e1b-8f6d-126bbd1e9b62

📥 Commits

Reviewing files that changed from the base of the PR and between c1e0d19 and ec96553.

📒 Files selected for processing (4)

.github/workflows/data-sync-maintainers.yml
lib/functions/artifacts/artifact-kernel.sh
lib/functions/compilation/kernel-debs.sh
lib/functions/configuration/main-config.sh

🚧 Files skipped from review as they are similar to previous changes (3)

lib/functions/configuration/main-config.sh
lib/functions/compilation/kernel-debs.sh
lib/functions/artifacts/artifact-kernel.sh

Kernels built with CONFIG_DEBUG_INFO produce a vmlinux with full debug info, but only the stripped Image is packaged; vmlinux is discarded with the build tree, leaving nothing to analyze kdump vmcores with. Debian ships it as linux-image-*-dbg, Ubuntu as -dbgsym ddebs, Fedora as kernel-debuginfo. Add KERNEL_DBG_PACKAGE=yes (default no) producing a linux-image-BRANCH-FAMILY-dbg deb (Debian-style -dbg suffix) with vmlinux at /usr/lib/debug/lib/modules/<version>/vmlinux — the standard search path of crash, drgn and gdb. The debug package is pinned to its exact kernel build via a versioned virtual package: linux-image provides linux-image-BRANCH-FAMILY-build (= artifact_version), and the dbg package depends on it. artifact_version encodes every build input (source SHA1, patches, .config, hooks, toolchain), and reversioning rewrites only the Version: field, so the pairing survives deployment reversioning and dpkg refuses to install debug symbols for a kernel built from any other inputs. The variable is hashed into the artifact version only when enabled, so dbg-enabled builds get a cache entry distinct from regular builds (a cached tarball without the dbg deb would otherwise poison them). Compiler identity and version are made part of the artifact version by force-enabling the kernel-version-toolchain extension for dbg builds, and KERNEL_EXTRA_CFLAGS is hashed in as well — compiler-distinct builds must not share a version, or debug symbols from one could pair with an image from another. Disabled by default: vmlinux with DWARF5 is ~0.5-1 GB unpacked (~150-300 MB deb). Assisted-by: Claude:claude-fable-5

github-actions Bot added size/medium PR with more then 50 and less then 250 lines 08 Milestone: Third quarter release Needs review Seeking for review Framework Framework components labels Jul 20, 2026

coderabbitai Bot reviewed Jul 20, 2026

View reviewed changes

Comment thread lib/functions/compilation/kernel-debs.sh Outdated

iav force-pushed the kernel-dbg-package branch from d0025a4 to c1e0d19 Compare July 20, 2026 04:25

iav force-pushed the kernel-dbg-package branch from c1e0d19 to ec96553 Compare July 24, 2026 16:31

github-actions Bot added GitHub Actions GitHub Actions code GitHub GitHub-related changes like labels, templates, ... labels Jul 24, 2026

coderabbitai Bot reviewed Jul 24, 2026

View reviewed changes

Comment thread .github/workflows/data-sync-maintainers.yml Outdated

iav force-pushed the kernel-dbg-package branch 3 times, most recently from f3541b9 to 0340785 Compare July 24, 2026 18:13

iav force-pushed the kernel-dbg-package branch from 0340785 to 3bb38b8 Compare July 25, 2026 19:24

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

kernel: add opt-in linux-image-dbg package with debug info - #10244

kernel: add opt-in linux-image-dbg package with debug info#10244
iav wants to merge 1 commit into
armbian:mainarmbian/build:mainfrom
iav:kernel-dbg-packageiav/armbian:kernel-dbg-packageCopy head branch name to clipboard

iav commented Jul 20, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 20, 2026 •

edited

Loading

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

rpardini commented Jul 20, 2026

Uh oh!

iav commented Jul 20, 2026

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Search code, repositories, users, issues, pull requests...

Uh oh!

Uh oh!

Conversation

iav commented Jul 20, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

How Has This Been Tested?

Checklist:

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviews paused

Walkthrough

Changes

Sequence Diagram(s)

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rpardini commented Jul 20, 2026

Uh oh!

iav commented Jul 20, 2026

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

iav commented Jul 20, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 20, 2026 •

edited

Loading