QUD-1773: smart Linux installer guide with preflight analyzer and known-good matrix

[hangzqcom]

Summary

Implements QUD-1773 — a self-analyzing Linux installer guide for qcom-usb-drivers-dkms.

Adds a preflight environment analyzer, a machine-readable known-good compatibility matrix, a Python classifier that maps the two together, and a user-facing install guide that ties everything into a concrete troubleshooting workflow. build-deb.sh now runs the preflight automatically before building.

Motivation

QUD-1773 calls out five persistent Linux install pain points:

1. Too many distro variants — fragmented coverage, ad-hoc support.
2. Kernel update breakage — manual make install breaks on kernel upgrade.
3. Secure Boot hurdles — unsigned DKMS modules silently fail to load.
4. Missing components — users hit cryptic failures when linux-headers, dkms, dh-dkms, or gcc are missing.
5. Immutable systems — Silverblue/Kinoite/MicroOS can't write to /usr.

The goal was an installer experience that auto-detects, validates, diagnoses, and learns from new configurations.

What's new

scripts/check-install-env.sh — preflight analyzer

Detects distro, kernel, arch, Secure Boot state + MOK enrollment, kernel headers, DKMS, gcc, make, Debian build deps, immutable rootfs, and conflicting in-tree modules (qcserial, qmi_wwan, cdc_wdm, option, usb_wwan). Cross-references the detected tuple with the known-good matrix and prints a human- or JSON-formatted report.

Every finding carries a stable CODE (e.g. MISSING_HEADERS, SECURE_BOOT_MOK, IMMUTABLE_ROOTFS, MATCH_FAIL) that the companion guide documents in a troubleshooting matrix.

sudo bash scripts/check-install-env.sh                          # text
sudo bash scripts/check-install-env.sh --json                    # machine-readable
sudo bash scripts/check-install-env.sh --report-file report.json # for issue reports
sudo bash scripts/check-install-env.sh --strict                  # CI-friendly

Exit codes: 0=pass · 1=partial · 2=fail · 3=unknown · 4=error.

scripts/known-good-configs.json — living compatibility matrix

JSON Schema is defined inline. Seeded with 12 entries covering Ubuntu 22.04/24.04, Debian 11/12, Linux Mint, Pop!_OS, Fedora 40/41 + Silverblue, RHEL 9, CentOS Stream 9 and Arch. Each entry captures distro_id, version (glob), kernel_range (min..max), architectures, status ∈ {pass, partial, fail, untested}, secure_boot, immutable_rootfs, required_packages, validated_by/on, and free-form notes.

This file is designed to grow via PRs — every user who validates an unlisted combination can append one entry, turning the file into a continuously-learning compatibility database.

scripts/match_known_good.py — classifier

Pure-stdlib Python. Maps (distro_id, distro_version, kernel_major_minor, arch) to the most specific matching entry (prefers exact version over glob), treats x86_64↔amd64 and aarch64↔arm64 as synonyms, and emits a single tab-separated line (status\tnotes\trequired_packages) that the bash driver parses.

docs/linux/install-guide.md — companion user guide

Human-readable walkthrough (~200 lines):

• Quick-start
• Preflight-first workflow
• Supported-environment table
• Step-by-step install for every distro family
• Troubleshooting matrix indexed by finding code — one-to-one mapping with what the preflight emits
• Secure Boot MOK enrollment procedure
• Immutable / OSTree workarounds (rpm-ostree install, usroverlay, toolbox)
• A "report back" section that shows contributors exactly how to submit a PR extending the known-good matrix

Integrations

• build-deb.sh runs the preflight automatically; hard failures (exit 2) abort the build. Bypass with SKIP_PREFLIGHT=1.
• README.md repository structure + Debian install section now point at the preflight and the new guide.
• docs/linux/getting-started/README.md links to the install guide.

Test plan & live results

Live-tested on this machine (Ubuntu 24.04.2 LTS, kernel 6.8.0-106-generic, x86_64):

#	Scenario	Result
1	Default (text) mode on real host	✅ PASS, exit 0
2	--json mode	✅ valid JSON, full system + findings payload
3	--report-file writes valid JSON	✅ 837 bytes, parses clean
4	--strict mode	✅ exit 0 on pass
5	Matcher spot-checks: Ubuntu 24.04, Debian 11, Fedora 40, nixos (unknown), Debian 12 arm64	✅ pass, partial, untested, unknown, pass respectively
6	--help output	✅
7	CentOS 9 (known QUD-1629 caveat) + Ubuntu 24.04 / kernel 4.19 (range edge)	✅ partial with note, pass respectively
8	Missing --configs-file	✅ emits NO_CONFIGS_FILE warn, graceful PARTIAL, exit 1
9	SKIP_PREFLIGHT=1 bypass in build-deb.sh	✅ skip path exercises correctly
10	Live build-deb.sh integration	✅ preflight runs, reports PASS, build continues ("Building qcom-usb-drivers-dkms version 1.0.6.1")

Sample run on this host

Qualcomm USB Kernel Drivers - Install Environment Report
========================================================

  Distribution     : Ubuntu 24.04.2 LTS (ubuntu 24.04)
  Kernel           : 6.8.0-106-generic (6.8)
  Architecture     : x86_64
  Package manager  : apt
  Immutable rootfs : no
  Secure Boot      : disabled
  Kernel headers   : found (/lib/modules/6.8.0-106-generic/build)
  dkms             : dkms-3.0.11
  gcc              : 13
  make             : 4.3
  Conflicting mods : none

  Known-good match : pass
                     LTS. Validated on 6.8 and 6.11 HWE kernels.

Findings
--------
  [INFO] MATCH_PASS: System matches a known-good configuration.

Overall status   : PASS

Static checks

• python3 -m json.tool scripts/known-good-configs.json → valid
• bash -n scripts/check-install-env.sh and build-deb.sh → clean
• python3 -c "import ast; ast.parse(...)" on match_known_good.py → clean

Files changed

 README.md                              |   8 +-
 build-deb.sh                           |  17 +
 docs/linux/getting-started/README.md   |  10 +-
 docs/linux/install-guide.md            | new (~200 lines)
 scripts/check-install-env.sh           | new (~320 lines)
 scripts/known-good-configs.json        | new (~180 lines incl. schema)
 scripts/match_known_good.py            | new (~130 lines)

Total: 7 files changed, +1135 / −4 lines.

Notes for reviewers

• The JSON schema for known-good-configs.json is embedded in the file itself under $defs, so a PR that edits entries also ships schema documentation. No extra file to maintain.
• match_known_good.py uses only stdlib (json, fnmatch) so there are no new runtime dependencies beyond python3 (already required by DKMS on every supported distro).
• The preflight does not alter system state. It only reads /etc/os-release, uname, mokutil, /sys/firmware/efi, lsmod, and checks for common binaries via command -v. Safe to run as non-root too — Secure Boot detection may be less precise without mokutil.
• Followup opportunity: wire scripts/check-install-env.sh --json into a GitHub Actions matrix that runs the preflight (and eventually the build) on every distro/kernel combo, feeding results back into known-good-configs.json via automated PRs.