source/skeptical-updater
1
0 Fork 0
Code Issues Pull Requests Releases Activity

first commit

Browse Source
This commit is contained in:
bryanpedini committed 2026-10-10 10:37:53 +02:00
commit 1354db6c39
90 files changed
+13123
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

discovery/apt.md
+607
View File
@@ -0,0 +1,607 @@
# APT family (Debian / Ubuntu) - discovery for skeptical-updater
Everything below was verified empirically in throwaway containers (`docker run --rm -i <image> bash ...`) on
2026-10-09, always with `LC_ALL=C DEBIAN_FRONTEND=noninteractive`. Exit codes are quoted as `[exit=N]`.
Sample outputs are real; real-world package versions drift daily, the `su-dummy-*` fixture ones do not.
Companion files in `discovery/apt/` (all runnable, all proven on the five images):
| file | purpose |
|---|---|
| `fixture.sh` | builds the local flat repo + dummy packages (item 10) |
| `smoke.sh` | asserts every recipe in this document on top of the fixture (32 checks, passes on all five images) |
| `parse-inst.awk` | `Inst` line -> `name<TAB>old<TAB>new<TAB>repo` (item 2) |
| `closure-dpkg.awk` | exact installed dependency closure from the dpkg database (item 5) |
## 0. TL;DR - chosen commands
| need | command (all with `LC_ALL=C DEBIAN_FRONTEND=noninteractive`) |
|---|---|
| refresh | `apt-get update -qq -o APT::Update::Error-Mode=any` (without the `-o`, unreachable mirrors still give exit 0!) |
| list what the upgrade will do | `apt-get -s --with-new-pkgs upgrade \| awk -f parse-inst.awk` (same verb + flags as the real upgrade) |
| list kept-back/held | same output, block `The following packages have been kept back:` (do NOT use `-qq`, it drops it); `apt-mark showhold` for real holds |
| cross-check / "everything newer" | `apt list --upgradable 2>/dev/null` (stderr carries a warning, stdout has a `Listing...` header) |
| one-liner description | `apt-cache show --no-all-versions P \| sed -n 's/^Description: //p'` |
| full description (candidate) | `apt-cache show --no-all-versions P \| awk '<see item 3>'` |
| installed reverse deps | `apt-cache rdepends --installed --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances P \| awk '/^Reverse Depends:/{p=1;next} p{sub(/^[ \|]+/,"");print}' \| sort -u` |
| installed dep closure | exact: `dpkg-query -W -f '${db:Status-Abbrev}\t${Package}\t${Pre-Depends}\t${Depends}\t${Provides}\n' \| awk -F'\t' -v roots="P" -f closure-dpkg.awk` (== apt's own parser, verified). The single-call `apt-cache depends --recurse ... P` is **inexact in both modes** (with `--installed` it loses virtual-provided deps, without it over-approximates 2-8x): see item 5 |
| per-run exclusion | `apt-mark hold P` for packages not already held, restore from a persisted snapshot with `comm` (item 6) |
| upgrade | `apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold -o DPkg::Lock::Timeout=60 --with-new-pkgs upgrade` |
| purge | `apt-get -y purge P`, then `apt-get -y autoremove --purge` |
| bats | `apt-get install -y --no-install-recommends bats` (1.2.1 .. 1.13.0 depending on image) |
Top gotchas (details in the sections):
1. `apt-get update` exits **0** when every mirror is unreachable (only `W:` lines). Use `-o APT::Update::Error-Mode=any` (or `--error-on=any`) to get exit 100. Hard errors (unsigned repo, no root) are exit 100 regardless.
2. `apt list` / `apt show` are the "unstable CLI": a warning is printed on **stderr** whenever stdout is not a tty. Use `apt-get` / `apt-cache` / `dpkg-query` / `apt-mark` for parsing.
3. All five images run as **root with no sudo, no python3**; `apt-get update` must be run first (lists are empty).
4. `-y` upgrade with a *locally modified conffile* that the new package also changes => dpkg prompts, hits EOF on stdin, fails, **exit 100**, package left in `iU` state. Always pass `--force-confdef --force-confold`.
5. `apt-cache depends --recurse` cannot produce an exact installed closure: with `--installed` it silently loses everything reachable only through a **virtual package** (e.g. `base-files` -> `awk` -> `mawk`: closure of 1 instead of 5 on debian:12) and may still print non-installed provider names; without `--installed` it walks through non-installed alternatives/providers and uses *candidate* metadata (debian:12 `bash`: 19 names vs the exact 8). Use the dpkg-database awk (`closure-dpkg.awk`).
6. `apt-cache rdepends` does not follow `Provides` (nobody is listed as reverse dependency of `mawk` although `base-files` needs `awk`), lists duplicates (one per version), and `--installed` filters on the *package* being installed, not the *version* that has the dependency.
7. `apt-get` takes the dpkg lock: a concurrent apt gives exit 100 `Could not get lock /var/lib/dpkg/lock-frontend` (also `apt-mark hold`, with a misleading "Are you root?"). `-o DPkg::Lock::Timeout=N` waits instead.
8. Holding a package also keeps back everything that needs a newer version of it (hold `b` => `a` kept back). `apt-mark hold` with a mix of valid/invalid names holds the valid ones **and** exits 100.
9. stderr noise is not failure: minimal images print `debconf: delaying package configuration, since apt-utils is not installed` on every dpkg run. Trust exit codes.
10. Plain `apt-get install bats` pulls `parallel` + perl (39 pkgs / 85 MB on debian:12, 60 / 159 MB on ubuntu:24.04) and may upgrade unrelated packages; use `--no-install-recommends`.
11. `ubuntu:latest` is now **26.04 (apt 3.2.0, new solver3)**: prints `Solving dependencies...`, and `dist-upgrade` refuses to remove manually installed packages (keeps them back instead).
## 1. Test matrix and base-image facts
| image | resolves to | image id | apt | dpkg | bash | awk | bats (apt) |
|---|---|---|---|---|---|---|---|
| debian:12 | Debian 12 bookworm | 94926f0fd968 | 2.6.1 | 1.21.23 | 5.2.15 | mawk 1.3.4 20200120 | 1.8.2-1 |
| debian:13 | Debian 13 trixie | 99339bdd341a | 3.0.3 | 1.22.22 | 5.2.37 | mawk 1.3.4 20250131 | 1.11.1-1 |
| ubuntu:22.04 | Ubuntu 22.04.5 jammy | e8df6c74f650 | 2.4.14 | 1.21.1 | 5.1.16 | mawk 1.3.4 20200120 | 1.2.1-3build1 |
| ubuntu:24.04 | Ubuntu 24.04.5 noble | 69f919497cad | 2.8.3 | 1.22.6 | 5.2.21 | mawk 1.3.4 20240123 | 1.10.0-1 |
| ubuntu:latest | **Ubuntu 26.04.1 resolute** | 6e92c4fd8dfd | 3.2.0 | 1.23.7 | 5.3.9 | mawk 1.3.4 20260129 | 1.13.0-1 |
Identical on all five (item 9):
```
$ id -u; whoami -> 0, root (docker default user; no USER directive)
$ command -v sudo -> (nothing) sudo is NOT installed
$ command -v python3 -> (nothing) python3 is NOT installed
$ command -v bash -> /usr/bin/bash bash present (5.1 .. 5.3); /bin/sh is dash
perl, flock, sed (GNU), grep, awk (mawk), dpkg-deb: present. curl, wget, gpg, dpkg-scanpackages, apt-ftparchive: absent.
```
- Do not rely on gawk features: `awk` is **mawk** everywhere and `sed` is GNU sed 4.8/4.9. Verified on mawk: `gensub()` -> `function gensub never defined`; 3-argument `match(s,r,arr)` -> syntax error; regex brace repetition `a{2}` is matched **literally** on mawk 1.3.4 20200120 (debian:12, ubuntu:22.04) and works on 20240123+ (debian:13, ubuntu:24.04, ubuntu:latest) - so avoid `{n}` in awk regexes.
- `/var/lib/apt/lists` is empty at start: nothing works (`apt-cache policy` has no candidates) until `apt-get update`.
- Docker-specific apt config shipped in the images: `docker-clean` (`Dir::Cache::pkgcache ""` => **no binary cache**, every `apt-get/apt-cache/apt-mark` call re-parses all lists), `docker-no-languages` (`Acquire::Languages "none"` => descriptions come from the `Packages` file, no Translation files), `docker-gzip-indexes`, `docker-autoremove-suggests` (`SuggestsImportant "false"`), `docker-disable-periodic-update` (ubuntu), `/usr/sbin/policy-rc.d` (`exit 101`, services are not started by maintainer scripts).
- Sources point to the **live** mirrors (`deb.debian.org`, `archive.ubuntu.com`, `security.ubuntu.com`) although the debian images carry a commented snapshot date. Therefore real-world upgradable packages exist in the images and change over time. Seen on 2026-10-09:
| image | real-world upgradable right now |
|---|---|
| debian:12 | `perl-base` 5.36.0-7+deb12u3 -> u4 (`oldstable-security`) |
| debian:13 | `liblzma5` 5.8.1-1+deb13u1 -> u2 (`stable-security`) |
| ubuntu:22.04 | `libssl3` 3.0.2-0ubuntu1.29 -> .30 |
| ubuntu:24.04 | `libaudit-common`, `libaudit1`, `libssl3t64` |
| ubuntu:latest | `libssl3t64`, `openssl-provider-legacy` 3.5.5-1ubuntu3.5 -> .7 |
- bats (item 9): `apt-get install -y --no-install-recommends bats` works on all five (exit 0, 0.7-1.7 s, 1 package, <200 kB; `bats --version` as in the table; `bats --tap` works). Helper libs `bats-support bats-assert bats-file` exist on every image **except ubuntu:22.04**. Oldest is **1.2.1** (jammy) which lacks `run --separate-stderr`, `bats_require_minimum_version`, `setup_suite`: restrict tests to the 1.2.1 feature set or vendor bats-core. `Recommends: parallel` (that is what bloats a plain install).
## 2. Item 1 - refreshing metadata: `apt-get update`
```
$ apt-get update (debian:12, root, network ok) [exit=0]
Get:1 http://deb.debian.org/debian bookworm InRelease [151 kB]
Get:2 http://deb.debian.org/debian bookworm-updates InRelease [55.4 kB]
Get:3 http://deb.debian.org/debian-security bookworm-security InRelease [34.8 kB]
Get:4 http://deb.debian.org/debian bookworm/main amd64 Packages [8790 kB]
Get:5 http://deb.debian.org/debian bookworm-updates/main amd64 Packages [6924 B]
...
Fetched 9388 kB in 2s (5412 kB/s)
Reading package lists...
```
Second run: `Hit:1 ... InRelease` lines, exit 0. `-qq` prints nothing on success (still exit 0); warnings/errors still go to **stderr** under `-qq`.
| situation | exit | where |
|---|---|---|
| success / nothing new (`Hit:`) | 0 | |
| not root | **100** | `E: Could not open lock file /var/lib/apt/lists/lock - open (13: Permission denied)` + `E: Unable to lock directory /var/lib/apt/lists/` |
| all mirrors unreachable (`--network none`) | **0** (!) | stdout `Err:1 ...` + `Temporary failure resolving 'deb.debian.org'`; stderr `W: Failed to fetch ...` and `W: Some index files failed to download. They have been ignored, or old ones used instead.` |
| one of several sources unreachable | **0** (!) | same `W:` lines |
| same two cases with `-o APT::Update::Error-Mode=any` (or `--error-on=any`) | **100** | the `W:` become `E:` (same text) |
| unsigned repo (no `[trusted=yes]`) | **100** | `E: The repository 'file:/srv/su-repo ./ Release' is not signed.` |
The "unreachable => exit 0" row and the `Error-Mode=any` fix are identical on all five images. After a failed update the old lists are kept (verified with a dead `Acquire::http::Proxy`: exit 0, `W: Failed to fetch ...`, the 3 `Packages` files and the candidate versions are unchanged = stale data) - so a tool must either use `Error-Mode=any` or parse stderr for `^W: Failed to fetch`.
Other notes: `apt-get update --print-uris` lists the index URLs without fetching. A second `update` of a `file:` repo regenerated within the same second can be seen as unchanged (mtime resolution): `fixture.sh` removes the repo's list files first.
## 3. Item 2 - listing upgradable packages
### 3.1 The candidates compared (real data, ubuntu:24.04)
`apt list --upgradable` (stdout and stderr captured separately) [exit=0]:
```
stdout:
Listing...
libaudit-common/noble-updates 1:3.1.2-2.1ubuntu0.1 all [upgradable from: 1:3.1.2-2.1build1.1]
libaudit1/noble-updates 1:3.1.2-2.1ubuntu0.1 amd64 [upgradable from: 1:3.1.2-2.1build1.1]
libssl3t64/noble-updates,noble-security 3.0.13-0ubuntu3.16 amd64 [upgradable from: 3.0.13-0ubuntu3.15]
stderr:
(empty line)
WARNING: apt does not have a stable CLI interface. Use with caution in scripts.
```
- stderr warning on all five images whenever stdout is not a tty; `Listing...` header on stdout; origin column is only the suite(s) comma-separated (no Label/Version); the name has **no arch qualifier** (with multiarch the same name appears twice: `su-dummy-m/su-repo 2.0 amd64 ...` and `su-dummy-m/su-repo 2.0 i386 ...`); it lists **every** package whose candidate is newer, including held and kept-back ones (it is not "what the upgrade will do").
`apt-get -s --with-new-pkgs upgrade` (ubuntu:24.04) [exit=0]:
```
Reading package lists...
Building dependency tree...
Reading state information...
Calculating upgrade...
The following packages will be upgraded:
libaudit-common libaudit1 libssl3t64
3 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.
Inst libaudit-common [1:3.1.2-2.1build1.1] (1:3.1.2-2.1ubuntu0.1 Ubuntu:24.04/noble-updates [all])
Conf libaudit-common (1:3.1.2-2.1ubuntu0.1 Ubuntu:24.04/noble-updates [all])
Inst libaudit1 [1:3.1.2-2.1build1.1] (1:3.1.2-2.1ubuntu0.1 Ubuntu:24.04/noble-updates [amd64])
Inst libssl3t64 [3.0.13-0ubuntu3.15] (3.0.13-0ubuntu3.16 Ubuntu:24.04/noble-updates, Ubuntu:24.04/noble-security [amd64])
```
debian:12: `Inst perl-base [5.36.0-7+deb12u3] (5.36.0-7+deb12u4 Debian-Security:12/oldstable-security [amd64])`.
`apt-get -s dist-upgrade` prints the identical `Inst` lines when no removals/new packages are involved (all three verbs gave the same count on the real data).
### 3.2 Decision
Use **`LC_ALL=C apt-get -s --with-new-pkgs upgrade`** and parse the `Inst` lines:
- it lists exactly what the real `apt-get --with-new-pkgs upgrade` will do (same resolver, same holds/pins), including *new* dependency packages and the correct order;
- no stderr warning, works **as non-root** (prints a `NOTE: This is only a simulation!` block on stdout, harmless), needs no lock;
- carries old version, new version, full origin and arch;
- `Inst`/`Conf`/`Remv`/`Purg` line prefixes are not translated, but the `kept back` header is, hence `LC_ALL=C`.
Keep `apt list --upgradable 2>/dev/null` only as a cross-check (it is the superset: includes held/kept-back).
### 3.3 Exact parse -> `name<TAB>old<TAB>new<TAB>repo` (`discovery/apt/parse-inst.awk`, POSIX awk, tested with mawk)
```awk
/^Inst / {
name = $2
rest = $0
sub(/^Inst [^ ]+ /, "", rest)
old = "-"
if (substr(rest, 1, 1) == "[") { # "[old] (new origins [arch])"
old = rest
sub(/^\[/, "", old)
sub(/\].*$/, "", old)
sub(/^\[[^]]*\] /, "", rest)
}
sub(/^\(/, "", rest) # "new origins [arch]) ..."
new = rest
sub(/ .*$/, "", new)
sub(/^[^ ]+ ?/, "", rest) # "origins [arch]) ..."
i = index(rest, "])")
repo = substr(rest, 1, i - 1) # "origins [arch"
sub(/ ?\[[^[]*$/, "", repo) # drop " [arch"
printf "%s\t%s\t%s\t%s\n", name, old, new, repo
}
```
Usage: `LC_ALL=C apt-get -s --with-new-pkgs upgrade 2>/dev/null | awk -f parse-inst.awk`. Real output:
```
perl-base 5.36.0-7+deb12u3 5.36.0-7+deb12u4 Debian-Security:12/oldstable-security
libssl3t64 3.0.13-0ubuntu3.15 3.0.13-0ubuntu3.16 Ubuntu:24.04/noble-updates, Ubuntu:24.04/noble-security
libaudit-common 1:3.1.2-2.1build1.1 1:3.1.2-2.1ubuntu0.1 Ubuntu:24.04/noble-updates
su-dummy-newdep - 1.0 su-fixture:su-repo
```
Edge cases, proven with a unit test on literal lines (real lines plus two hand-written ones modelled on them, the `libc6:i386` line and the `Inst su-dummy-slow` line with an empty origin) - input on the left, TSV output on the right:
```
Inst su-dummy-newdep (1.0 su-fixture:su-repo [all]) -> su-dummy-newdep - 1.0 su-fixture:su-repo
Inst su-dummy-slow [0.9] (1.0 [all]) -> su-dummy-slow 0.9 1.0 (empty repo)
Inst su-dummy-m [1.0] (2.0 su-fixture:su-repo [amd64]) [su-dummy-m:amd64 on su-dummy-m:i386] [su-dummy-m:i386 ]
-> su-dummy-m 1.0 2.0 su-fixture:su-repo
Inst libc6:i386 [2.36-9] (2.36-9+deb12u10 Debian-Security:12/oldstable-security, Debian:12.12/oldstable [i386]) []
-> libc6:i386 2.36-9 2.36-9+deb12u10 Debian-Security:12/oldstable-security, Debian:12.12/oldstable
Conf ... / Remv su-dummy-f [1.0] -> (ignored)
```
(`smoke.sh` asserts the plain fixture line and the new-package `-` case on every image; the real-data lines above come from the images themselves.)
- **new package** (pulled in as dependency): `Inst su-dummy-newdep (1.0 su-fixture:su-repo [all])` has no `[old]` => old column is `-` (not empty: `IFS=$'\t' read` collapses empty tab fields because tab is IFS-whitespace).
- **multiple origins**: `Ubuntu:24.04/noble-updates, Ubuntu:24.04/noble-security` (comma+space, kept verbatim in the repo column).
- **empty origin** (package from a local .deb): `(1.0 [all])` -> repo is empty.
- **foreign arch**: name carries the qualifier, `libc6:i386`; native arch has none.
- **trailing junk after the closing paren** (multiarch pairs): `Inst su-dummy-m [1.0] (2.0 su-fixture:su-repo [amd64]) [su-dummy-m:amd64 on su-dummy-m:i386] [su-dummy-m:i386 ]` - hence the parser cuts at the first `])`, never anchors on `$`. A bare ` []` may also trail.
- `Inst` order is **dependency order** (b before a), not alphabetical: `sort` if a stable order is needed.
- Repo string format is `Label:Version/Suite` (from the Release file; `Debian-Security:12/oldstable-security`, `Ubuntu:24.04/noble-updates`); fixture repo (no Version) gives `su-fixture:su-repo`; with neither Label nor Suite apt prints the host (`localhost`).
Secondary parse of `apt list --upgradable` (if ever needed), same 4 columns (repo = suite list):
```sh
apt list --upgradable 2>/dev/null | sed -nE 's#^([^/]+)/([^ ]+) ([^ ]+) ([^ ]+) \[upgradable from: ([^]]+)\]$#\1\t\5\t\3\t\2#p'
```
(`Listing...` is skipped by the anchored pattern; no arch disambiguation.)
### 3.4 Held and kept-back packages
Held packages never appear as `Inst`. They show up in the `kept back` block together with packages kept back for dependency reasons, and in the "N not upgraded" count; `apt list --upgradable` still lists them. Real output (fixture, `su-dummy-c` held, `-d` needs a new package, `-e` needs a removal):
```
$ apt-mark hold su-dummy-c ; apt-get -s upgrade
The following packages have been kept back:
su-dummy-c su-dummy-d su-dummy-e
The following packages will be upgraded:
su-dummy-a su-dummy-b su-dummy-w
3 upgraded, 0 newly installed, 0 to remove and 3 not upgraded.
```
Parse of the block (names are space separated, indented by two spaces, wrapped at 80 columns):
```sh
awk '/^The following packages have been kept back:/{k=1;next} k&&/^ /{for(i=1;i<=NF;i++)print $i;next} {k=0}'
```
Distinguish "held" from "kept back for other reasons" with `apt-mark showhold`. **Do not use `-qq`** with `-s` when you need this block: `apt-get -qq -s ...` prints only the `Inst`/`Conf` lines (verified).
Behaviour of the three upgrade verbs on the same state (fixture `SU_FIXTURE_EXTRA=1`: d needs a NEW dependency, e conflicts with installed f; debian:12/13, ubuntu:22.04/24.04 identical):
| verb | upgraded | newly installed | removed | kept back |
|---|---|---|---|---|
| `apt-get upgrade` | a b c w | - | - | d e |
| `apt-get --with-new-pkgs upgrade` | a b c d w | su-dummy-newdep | - | e |
| `apt-get dist-upgrade` | a b c d e w | su-dummy-newdep | su-dummy-f | - |
(`ubuntu:latest`/apt 3.2 solver3: `dist-upgrade` does **not** remove the manually installed `su-dummy-f`, so `e` stays kept back there: 5 upgraded, 1 new, 0 removed.) `--with-new-pkgs upgrade` is the safe choice: it never removes anything.
## 4. Item 3 - description of a package
Candidate vs installed matters. Real data (debian:12, `perl-base` installed u3, candidate u4):
```
$ apt-cache policy perl-base
perl-base:
Installed: 5.36.0-7+deb12u3
Candidate: 5.36.0-7+deb12u4
Version table:
5.36.0-7+deb12u4 500
500 http://deb.debian.org/debian-security bookworm-security/main amd64 Packages
*** 5.36.0-7+deb12u3 500
500 http://deb.debian.org/debian bookworm/main amd64 Packages
100 /var/lib/dpkg/status
```
| command | content | notes |
|---|---|---|
| `apt-cache policy P` | Installed / Candidate / version table with pins and origins | no description at all; exit 0 and **empty output** for an unknown package |
| `apt-cache show P` | full control record(s) **of all versions** (default `--all-versions`: 2 stanzas for perl-base) | `--no-all-versions` => only the candidate (1 stanza); `P=1.0` selects one version; unknown package: `E: No packages found` **exit 100**; purely virtual: no output, exit 0 |
| `dpkg -s P` / `dpkg-query -W -f '${Description}' P` | record of the **installed** version only | non-installed (known or unknown) package: `dpkg-query: package 'x' is not installed and no information is available`, **exit 1** (`dpkg-query -W -f '${binary:Summary}'` prints `(no description available)` with exit 0) |
| `apt show P` | like `apt-cache show` plus formatting | stderr warning, not for scripts |
Short description (one line):
```sh
apt-cache show --no-all-versions "$pkg" | sed -n 's/^Description: //p' # candidate -> minimal Perl system
dpkg-query -W -f='${binary:Summary}\n' "$pkg" # installed version
apt-cache search --names-only "^$pkg\$" # "perl-base - minimal Perl system"
```
Full Description paragraph of the **candidate** (first line, continuation lines with the single leading space stripped, ` .` turned into an empty line, stops at the next field):
```sh
apt-cache show --no-all-versions "$pkg" | awk '
/^Description(-[a-z][a-z](_[A-Z][A-Z])?)?:/ { p=1; sub(/^[^:]*: ?/,""); print; next }
p && /^ / { l=substr($0,2); print (l=="." ? "" : l); next }
p { exit }'
```
Verified output for the fixture package (identical on debian:12 and ubuntu:24.04; `Description-md5:` is correctly not matched):
```
dummy package su-dummy-a for skeptical-updater tests
This package only exists to exercise the package manager.
It ships one data file and one conffile (version 2.0).
```
Raw record order differs per distro (`Description` is followed by `Description-md5`, `Homepage`, ... on Debian; Ubuntu 24.04+/Debian 13 print an empty `Description-md5:` for installed-only stanzas) - that is why the awk stops at the first non-continuation line instead of counting lines. `dpkg -s` shows the same text for the installed version (`... (version 1.0)` in the fixture, `2.0` for the candidate).
## 5. Item 4 - installed reverse dependencies
Flags: `apt-cache rdepends --installed --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances P`.
Without the `--no-conflicts/--no-breaks/...` flags Conflicts/Breaks/Replaces are included (fixture: `su-dummy-e` shows up as "reverse dependency" of `su-dummy-f` only because of `Conflicts`; on debian:12 `libc6`: 76 entries default vs 75 filtered). Pre-Depends are always included (good).
Output format (fixture, debian:12) [exit=0]:
```
su-dummy-b
Reverse Depends:
su-dummy-a
su-dummy-a
```
real data (`gpgv`, debian:12, an alternative `gpgv | gpgv2 | gpgv1` in apt's Depends):
```
gpgv
Reverse Depends:
|apt
```
- line 1 = the package, line 2 = `Reverse Depends:`, then one dependent per line, 2 spaces indent; a leading ` |` marks "I depend on this **or an alternative**" (the `|` replaces the first space).
- **duplicates**: one entry per package *version* that has the dependency (installed 1.0 and candidate 2.0 both => twice; ubuntu repeats per pocket) => `sort -u`.
- unknown package: `E: No packages found` **[exit=100]**. Purely virtual name (`awk`, `su-virtual`): prints only `<awk>` [exit=0], never the dependents.
- Not-installed package with `--installed`: still answers (lists installed dependents).
Parse to plain names (one package per call):
```sh
apt-cache rdepends --installed --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances "$pkg" \
| awk '/^Reverse Depends:/{p=1;next} p{sub(/^[ |]+/,""); print}' | sort -u
```
Real: `libgcrypt20` -> `gpgv libapt-pkg6.0 libsystemd0` (debian:12), `gpgv libapt-pkg6.0t64 libsystemd0` (ubuntu:24.04); without `--installed` the same query returns 155 / 171 names.
For several packages in one call the output is a repeated block (`pkg` / `Reverse Depends:` / entries); track the block header (first non-indented line) if needed.
Known inexactness (all verified):
1. **`Provides` is not followed**: `apt-cache rdepends --installed ... mawk` => empty, although `base-files` (Pre-)Depends on the virtual `awk` that `mawk` provides. Fixture: `su-dummy-w` depends on `su-virtual | su-dummy-alt`, `su-dummy-v` provides `su-virtual` => `rdepends su-dummy-v` is empty. To be complete, also query every name in the target's `Provides:` (`apt-cache show --no-all-versions P | sed -n 's/^Provides: //p'`) - but `rdepends <virtual>` itself prints only `<virtual>`, so you must instead scan for the virtual in `apt-cache showpkg <virtual>` ("Reverse Depends:" section lists `su-dummy-w,su-virtual`) or use the dpkg database.
2. `--installed` filters on the dependent **package** being installed, not on the installed **version** having the dependency: `rdepends --installed su-dummy-newdep` lists `su-dummy-d` although only the not-yet-installed d 2.0 depends on it.
3. Exact alternative for "what would break if I removed P": `apt-get -s purge P | awk '/^Purg /{print $2}'` (transitive, uses the installed versions, the output includes P itself): fixture `apt-get -s purge su-dummy-b` => `Purg su-dummy-a [1.0]`, `Purg su-dummy-b [1.0]` [exit=0]. For Essential chains it errors (`E: Error, pkgProblemResolver::Resolve generated breaks`, `apt-get -s remove libgcrypt20`).
## 6. Item 5 - recursive dependency closure restricted to installed packages
Requested form: `apt-cache depends --recurse --installed --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances P`.
### 6.1 Output format (debian:12, `apt`)
```
apt <- column 0: a package header (one stanza per reachable package; --recurse output is FLAT, not a tree)
Depends: adduser <- 2 spaces: dependency ("PreDepends:" for Pre-Depends)
|Depends: gpgv <- leading " |": member of an alternative group "gpgv | gpgv2 | gpgv1"; the last member has no '|'
Depends: libapt-pkg6.0
Depends: libsystemd0
libelogind0 <- 4 spaces: packages that PROVIDE the dependency name above (not filtered by --installed!)
adduser
Depends: passwd
gpgv
Depends: libbz2-1.0
...
```
Without `--installed` the group is `|Depends: gpgv`, `|Depends: gpgv2`, ` Depends: gpgv1`. A purely virtual dependency is printed in angle brackets with its providers below it, and later as its own (empty) stanza:
```
ca-certificates (NOT installed; plain depends) [exit=0]
Depends: openssl
|Depends: debconf
Depends: <debconf-2.0>
cdebconf
debconf
```
- Package **not installed**: exit 0, the header and its dependencies are printed anyway; with `--installed` only the installed dependencies (` |Depends: debconf`; `openssl` and `<debconf-2.0>` disappear), and `--recurse --installed` yields `ca-certificates` (the root, although not installed) + `debconf`.
- Unknown package: `E: No packages found` [exit=100]. Purely virtual root: prints `<name>` [exit=0].
- `depends P` uses the **candidate** version's dependencies (fixture: installed `su-dummy-d 1.0` has none, candidate 2.0 needs `su-dummy-newdep` => `apt-cache depends su-dummy-d` shows it; `apt-cache depends su-dummy-d=1.0` shows nothing). Pin a version with `P=VERSION` to get the installed version's dependencies.
### 6.2 What the single-call forms really return (real lists, all five images)
Reference ("exact") = the installed versions' Pre-Depends/Depends, expanded only through installed packages, every installed alternative followed, virtuals resolved through installed providers. It was computed two independent ways that agree 100% (`comm` diff empty) for 5 roots x 5 images: (D) a BFS driving `apt-cache depends --no-... pkg=INSTALLED_VERSION` (apt's own parser), and (C) `closure-dpkg.awk` over the dpkg database (6.4).
**A. with `--installed`** (as requested) - under-approximates, and is not even purely "installed":
```
$ apt-cache depends --recurse --installed <flags> base-files (debian:12)
base-files <- the whole closure is ONE package (exact: 5)
```
Virtual packages are not "installed", so `--installed` prunes every dependency satisfied through `Provides` and the recursion stops there (`base-files` has `PreDepends: <awk>`, provider `mawk`). Sizes `--installed` vs exact: `base-files` 1 vs 5 (debian:12/13), 5 vs 6 (ubuntu 22.04/24.04), 6 vs 7 (ubuntu:latest); `bash` 7 vs 8, 7 vs 8, 8 vs 9, 8 vs 9, 9 vs 10 (always missing `mawk`); fixture `su-dummy-w` -> `<su-virtual>` -> `su-dummy-v` lost the same way (1 vs 2). Conversely the provider lines are not filtered and get recursed: non-installed names such as `libelogind0` (debian:12 `apt`: 46 vs 45) or `gpgv-from-sq` (ubuntu:latest `apt`: 27 vs 26) appear as column-0 headers. A non-installed root is still printed as the first stanza.
**B. without `--installed`, then intersect with dpkg-installed names** - over-approximates, because apt-cache walks into *non-installed* alternatives/providers (`debconf-2.0` -> `cdebconf`, `gpgv2`, ...) and uses the *candidate* version's dependencies:
| root | exact | B | | root | exact | B |
|---|---|---|---|---|---|---|
| debian:12 `apt` | 45 | 50 | | debian:13 `apt` | 27 | 46 |
| debian:12 `base-files` | 5 | 17 | | ubuntu:24.04 `apt` | 35 | 49 |
| debian:12 `bash` | 8 | 19 | | ubuntu:latest `apt` | 26 | 45 |
| debian:12 `tzdata` | 2 | 16 | | ubuntu:22.04 `bash` | 9 | 19 |
(the extras are installed packages such as `dpkg libacl1 tar libselinux1 libtinfo6 ...` that are reached only by recursing into **non-installed** providers/alternatives: `cdebconf` (+ `libnewt0.52 libslang2 ...`) for `tzdata`'s `debconf | debconf-2.0`, `gawk`/`original-awk` (+ `libmpfr6 libreadline8 ...`) for the virtual `awk` of `base-files`/`bash`; verified by listing the non-installed column-0 stanzas of the recursion). In addition `depends` uses the *candidate* version's dependencies (fixture `su-dummy-d`), which differ from the installed ones whenever an upgrade changes dependencies. B is a superset of the exact closure, A is neither a subset nor a superset. With the offline fixture (no real lists, apt only knows installed versions) A, B and exact differ only by the virtual case.
Other facts: cost of the recursion itself is nil (0.35 s with and without `--installed` on debian:12, dominated by re-parsing the lists); the foreign-arch names come as `name:arch`.
### 6.3 If a single apt-cache call is preferred anyway (superset semantics, e.g. "candidate/post-upgrade closure")
```sh
FLAGS="--no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances"
installed_names() { dpkg-query -W -f '${db:Status-Abbrev}\t${Package}\n' | awk -F'\t' 'substr($1,2,1) !~ /[nc]/ {print $2}' | sort -u; }
comm -12 \
<(apt-cache depends --recurse $FLAGS "$pkg" | awk '/^[^ <]/' | sort -u) \
<(installed_names)
```
- `awk '/^[^ <]/'` = column-0 lines = every package that was reached, minus `<virtual>` headers; the `|` markers (` |Depends: x`) and the 4-space provider lines are indented, hence ignored (`|alternatives` are therefore all followed, installed or not).
- `substr($1,2,1) !~ /[nc]/`: dpkg state is not `n`(ot-installed)/`c`(onfig-files only); `ii`, `iU`, `iF` count as installed, `rc` does not.
- Use `${Package}:${Architecture}` on both sides if foreign architectures matter (apt-cache prints `name:arch` for non-native only).
### 6.4 Recommended (exact, no apt call): `discovery/apt/closure-dpkg.awk`
```sh
dpkg-query -W -f '${db:Status-Abbrev}\t${Package}\t${Pre-Depends}\t${Depends}\t${Provides}\n' \
| awk -F'\t' -v roots="pkg1 pkg2" -f closure-dpkg.awk | sort -u
```
Follows Pre-Depends + Depends of the **installed** versions, every installed alternative of an `a | b` group, virtual names through the `Provides` of installed packages (versioned `Provides: x (= 1.2)` and `:any` qualifiers handled); prints plain names, roots included if installed (a non-installed root yields nothing). ~0 s (single dpkg-query). Output verified identical to the apt-cache BFS reference on `apt base-files bash libpam-runtime tzdata` on all five images (e.g. debian:12 `apt` 45 = 45, `bash` 8 = 8, `base-files` 5 = 5 incl. `mawk`; ubuntu:24.04 `tzdata` not installed => empty).
## 7. Item 6 - per-run exclusion with `apt-mark hold / unhold / showhold`
Real outputs (fixture, debian:12):
```
$ apt-mark hold su-dummy-c su-dummy-c set on hold. [exit=0]
$ apt-mark hold su-dummy-c su-dummy-c was already set on hold. [exit=0]
$ apt-mark showhold su-dummy-c [exit=0] (works as non-root too)
$ apt-mark unhold su-dummy-c Canceled hold on su-dummy-c. [exit=0]
$ apt-mark unhold su-dummy-a su-dummy-a was already not on hold. [exit=0]
$ apt-mark hold no-such-pkg-xyz E: Unable to locate package no-such-pkg-xyz / E: No packages found [exit=100]
$ apt-mark hold su-dummy-newdep no-such-pkg-xyz su-dummy-newdep set on hold. / E: Unable to locate package ... [exit=100] <- the valid one IS held
$ (non-root) apt-mark hold X dpkg: error: required read/write access to the dpkg database directory / E: Executing dpkg failed. Are you root? [exit=100]
$ dpkg-query -W -f '${Package} ${Status}\n' su-dummy-c su-dummy-c hold ok installed
$ dpkg --get-selections | grep hold su-dummy-c<TABs>hold
```
- A hold is a dpkg selection state (stored in `/var/lib/dpkg/status`): persistent, visible to `dpkg`, needs root **and the dpkg lock** (`apt-mark hold` while another apt runs: `dpkg: error: dpkg frontend lock was locked by another process`, exit 100).
- Holding a package that is **not installed** works (`set on hold`), shows in `showhold`, and blocks its installation as a new dependency (it made `su-dummy-d` kept back), but `dpkg --get-selections` does not list it.
- Foreign arch is shown as `name:i386`.
**`apt-get --with-new-pkgs upgrade` skips held packages** - proven (fixture, real run, `su-dummy-c` held):
```
$ apt-get -y --with-new-pkgs upgrade [exit=0]
The following NEW packages will be installed: su-dummy-newdep
The following packages have been kept back: su-dummy-c su-dummy-e
The following packages will be upgraded: su-dummy-a su-dummy-b su-dummy-d su-dummy-w
4 upgraded, 1 newly installed, 0 to remove and 2 not upgraded.
=> a=2.0 b=2.0 c=1.0 (held, untouched) d=2.0 e=1.0 (kept back)
```
- The hold cascades: holding `b` (while `a` 2.0 needs `b (>= 2.0)`) keeps **a** back too (`kept back: su-dummy-a su-dummy-b su-dummy-c ...`, exit 0). Always re-run the simulation after holding and show the user the real result.
- `dist-upgrade` honours holds the same way. `apt-get -y purge <held>` fails: `E: Held packages were changed and -y was used without --allow-change-held-packages.` [exit=100].
- No-state alternative (inclusion list instead of exclusion): `apt-get -y --only-upgrade install P1 P2 ...` upgrades only those (plus whatever they need: `a` drags `b` along; `d` drags `su-dummy-newdep`; a not-installed name is skipped with exit 0; if the needed dependency is held it fails `E: Unable to correct problems, you have held broken packages.` exit 100).
### Recipe: hold temporarily and restore the previous hold set EXACTLY (verified, incl. crash recovery)
Idea: never touch what the admin already holds; journal (write-ahead) every hold *we* add to a state file; restore = unhold exactly the journaled packages that are still held. The journal survives `kill -9`, so the next run can undo a leaked hold without disturbing holds the admin added/removed in the meantime (a snapshot-and-diff restore would revert such admin edits - tested, rejected).
```bash
SU_STATE_DIR=${SU_STATE_DIR:-/var/lib/skeptical-updater}
SU_HOLDS_ADDED=$SU_STATE_DIR/holds.added # write-ahead journal: the holds WE put (one name per line)
su_holds_begin() { # su_holds_begin PKG... (packages to exclude from this run)
mkdir -p "$SU_STATE_DIR" || return 1
local held p; held=$(apt-mark showhold) || return 1
: > "$SU_HOLDS_ADDED"
for p in "$@"; do
grep -qxF -- "$p" <<<"$held" && continue # already held by the admin: not ours, never touched
echo "$p" >> "$SU_HOLDS_ADDED" # journal first (write-ahead) ...
apt-mark hold "$p" >/dev/null || return 1 # ... then hold (on failure the caller runs su_holds_restore)
done
}
su_holds_restore() { # idempotent; also call it at the START of every run (crash recovery)
[ -f "$SU_HOLDS_ADDED" ] || return 0
apt-mark showhold | sort -u | comm -12 - <(sort -u "$SU_HOLDS_ADDED") | xargs -r apt-mark unhold >/dev/null
rm -f "$SU_HOLDS_ADDED"
}
trap su_holds_restore EXIT # plus INT/TERM; SIGKILL cannot be trapped -> journal + start-of-run call
```
Verified scenarios (debian:12; the same logic is asserted by `smoke.sh` on all five images):
```
admin before : [su-dummy-a su-dummy-alt ] <- a installed, alt NOT installed
su_holds_begin su-dummy-a su-dummy-c journal: [su-dummy-c ] (a is the admin's: not journaled)
during : [su-dummy-a su-dummy-alt su-dummy-c ]
upgrade exit=0 a=1.0 (held) c=1.0 (held), b/d/w upgraded
after restore: [su-dummy-a su-dummy-alt ] <- identical to "before"; a 2nd restore is a no-op (rc=0)
crash: su_holds_begin su-dummy-c su-dummy-b ; kill -9 ; admin: hold su-dummy-e, unhold su-dummy-alt
leaked : [su-dummy-a su-dummy-alt su-dummy-b su-dummy-c ]
admin edits : [su-dummy-a su-dummy-b su-dummy-c su-dummy-e ]
recovered : [su-dummy-a su-dummy-e ] <- only b,c released; the admin's new hold e kept, the admin's removal of alt respected
```
Notes: each `apt-mark` call costs 0.3-0.6 s on these images (no cache) - pass many names to one call where possible (a bad name in a multi-name call holds the valid ones and exits 100, so validate names first: `apt-cache show --no-all-versions N >/dev/null`); `apt-mark`/`xargs -r` needs root and the dpkg lock (use the same `DPkg::Lock::Timeout` discipline: `apt-mark hold` has no timeout option, retry on exit 100 when the message is `frontend lock was locked`).
## 8. Item 7 - upgrading non-interactively
```
$ apt-get -y --with-new-pkgs upgrade (fixture; held c) [exit=0]
...
Need to get 0 B/4188 B of archives.
Get:1 file:/srv/su-repo ./ su-dummy-b 2.0 [826 B]
(Reading database ... 6114 files and directories currently installed.)
Preparing to unpack ..././su-dummy-b_2.0_all.deb ...
Unpacking su-dummy-b (2.0) over (1.0) ...
Setting up su-dummy-b (2.0) ...
Installing new version of config file /etc/su-dummy/su-dummy-b.conf ...
```
Exit codes (identical on the five images unless noted):
| case | exit | evidence |
|---|---|---|
| success | 0 | |
| nothing to upgrade (all three verbs) | **0**, ends with `0 upgraded, 0 newly installed, 0 to remove and 0 not upgraded.` | `apt-get -qq -s` prints nothing |
| kept back / held packages remain | **0** | summary `... and 2 not upgraded.` |
| dpkg fails (postinst `exit 1`, fixture `SU_FIXTURE_BAD=1`) | **100** | stdout `Errors were encountered while processing:` + pkg; stderr `E: Sub-process /usr/bin/dpkg returned an error code (1)`; other packages in the same run are still configured; the bad package is left `iF` (half-configured) and every later `apt-get upgrade`/`install -f` fails again with 100 until fixed |
| conffile conflict, no `--force-conf*` | **100** | see below |
| lock held by another apt | **100** | `E: Could not get lock /var/lib/dpkg/lock-frontend. It is held by process 191 (apt-get)` + `E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), is another process using it?` |
| `-o DPkg::Lock::Timeout=30` | waits (7 s in the test) then proceeds, exit 0 | |
| not root (real run) | **100** | `E: Could not open lock file /var/lib/dpkg/lock-frontend - open (13: Permission denied)` + `E: Unable to acquire the dpkg frontend lock (/var/lib/dpkg/lock-frontend), are you root?` (`-s` works as non-root) |
| unknown package (`install`/`purge`) | **100** | `E: Unable to locate package no-such-pkg-xyz` |
| unsatisfiable (held dependency) | **100** | `E: Unable to correct problems, you have held broken packages.` |
**Conffile prompt** (fixture: `/etc/su-dummy/su-dummy-c.conf` edited locally, 2.0 ships a different one, stdin = /dev/null, `-y` only):
```
Configuration file '/etc/su-dummy/su-dummy-c.conf'
==> Modified (by you or by a script) since installation.
==> Package distributor has shipped an updated version.
What would you like to do about it ? Your options are: ...
*** su-dummy-c.conf (Y/I/N/O/D/Z) [default=N] ? dpkg: error processing package su-dummy-c (--configure):
end of file on stdin at conffile prompt [exit=100], state iU, su-dummy-c.conf.dpkg-new left behind
```
With a tty it would block waiting for input instead. Results of the fix options (same scenario, separate containers, all exit 0, state `ii`):
| `-o Dpkg::Options::=...` | conf after | leftover |
|---|---|---|
| `--force-confold` | `local-edit=1` (kept) | `su-dummy-c.conf.dpkg-dist` (new version) |
| `--force-confnew` | `version=2.0` (replaced) | `su-dummy-c.conf.dpkg-old` (your edit) |
| `--force-confdef --force-confold` | kept | `.dpkg-dist` |
Use `--force-confdef --force-confold` (never silently overwrite admin edits; unmodified conffiles are still updated: `Installing new version of config file ...`).
`upgrade` vs `dist-upgrade`: see the table in 3.4. `apt-get -y dist-upgrade` on the fixture removed `su-dummy-f` (`Removing su-dummy-f (1.0) ...` - note it stays `rc` in dpkg, `dpkg-query -W` still prints its version; always check `${db:Status-Abbrev}`) with no extra confirmation. Recommendation: `--with-new-pkgs upgrade`; use `dist-upgrade` only when explicitly asked, and then show the `Remv` lines first.
Output noise (non-tty): `(Reading database ... 5%(Reading database ...` progress is in stdout, `-qq` drops the apt summary but keeps dpkg's output; `-o Dpkg::Use-Pty=0` / `Dpkg::Progress-Fancy=0` change nothing in non-tty runs. stderr always has `debconf: delaying package configuration, since apt-utils is not installed` on the minimal images (harmless).
## 9. Item 8 - purge and autoremove
```
$ apt-get -s purge su-dummy-b (a depends on b) [exit=0]
The following packages will be REMOVED:
su-dummy-a* su-dummy-b* <- '*' = purge
0 upgraded, 0 newly installed, 2 to remove and 4 not upgraded.
Purg su-dummy-a [1.0]
Purg su-dummy-b [1.0]
$ apt-get -y purge su-dummy-b [exit=0]
Removing su-dummy-a (1.0) ... <- reverse dependencies are removed too, NO extra confirmation with -y
Removing su-dummy-b (1.0) ...
Purging configuration files for su-dummy-b (1.0) ...
Purging configuration files for su-dummy-a (1.0) ...
```
- `apt-get -y remove P` leaves conffiles and state `rc` (`rc su-dummy-c=1.0`, `/etc/su-dummy/su-dummy-c.conf` still there); a following `apt-get -y purge P` prints `Purging configuration files for P` and deletes them (state: no dpkg-query entry).
- Not installed / already purged / known-but-not-installed: `Package 'su-dummy-a' is not installed, so not removed` [exit=0]. Unknown name: `E: Unable to locate package no-such-pkg-xyz` [exit=100].
- Essential protection: `apt-get -y purge login` -> `WARNING: The following essential packages will be removed. This should NOT be done unless you know exactly what you are doing!` ... `E: Essential packages were removed and -y was used without --allow-remove-essential.` [exit=100], nothing is removed (debian:12/13, ubuntu:22.04/24.04; `coreutils` gives the same on debian:13, ubuntu:22.04 and ubuntu:latest). `login` is **not Essential on ubuntu 26.04** and was really purged there (exit 0) - use `coreutils` for a cross-image Essential test.
- Held package: `E: Held packages were changed and -y was used without --allow-change-held-packages.` [exit=100] (with the flag it works).
Autoremove (fixture: `su-dummy-d` 2.0 pulled `su-dummy-newdep` as automatically installed):
```
$ apt-get -y purge su-dummy-d [exit=0]
The following package was automatically installed and is no longer required:
su-dummy-newdep
Use 'apt autoremove' to remove it.
The following packages will be REMOVED:
su-dummy-d*
$ apt-get -s autoremove --purge -> Purg su-dummy-newdep [1.0]
$ apt-get -y autoremove --purge [exit=0]
Removing su-dummy-newdep (1.0) ...
Purging configuration files for su-dummy-newdep (1.0) ...
$ apt-get -y autoremove --purge (nothing left) ... 0 to remove ... [exit=0]
```
`apt-get autopurge` is an equivalent alias (verified: `Purg su-dummy-newdep [1.0]` / `Removing ...` / `Purging configuration files ...`, exit 0). Packages installed with `dpkg -i` are *manual*; `apt-mark auto P` / `apt-mark showauto` control the auto flag. The images set `APT::AutoRemove::SuggestsImportant "false"`.
Simulation lines to preview: `Purg name [ver]` for purge/autoremove --purge, `Remv name [ver]` for plain remove.
## 10. Item 10 - E2E fixture: `discovery/apt/fixture.sh`
Builds `/srv/su-repo` (flat repo: `*.deb`, `Packages`, `Release`), source line `deb [trusted=yes] file:/srv/su-repo ./` in `/etc/apt/sources.list.d/su-repo.list`, installs the 1.0 packages with `dpkg -i` (from `/srv/su-old`, deliberately not published), runs `apt-get update` and **asserts** that `su-dummy-a/b/c` are upgradable via both `apt list --upgradable` and `apt-get -s --with-new-pkgs upgrade` (exit 1 otherwise).
- `su-dummy-a` 1.0 `Depends: su-dummy-b`; 2.0 `Depends: su-dummy-b (>= 2.0)`; `su-dummy-b`; `su-dummy-c` standalone. Arch `all` (runs on any host arch). Each ships one data file and one conffile (`/etc/su-dummy/<name>.conf`, content `version=<ver>`), multi-line Description.
- `dpkg-deb --root-owner-group -Zgzip --build`. Index: default `SU_FIXTURE_INDEXER=shell` (dpkg-deb -f + md5sum/sha256sum + hand-written `Release` with Origin/Label `su-fixture`, Suite/Codename `su-repo` and a valid `Date`) => **no extra packages, no network needed**. `scanpackages` (installs `dpkg-dev`) and `ftparchive` (installs `apt-utils`) are also implemented and verified; both need the real mirrors, and installing the tool can upgrade packages as a side effect (on debian:12 installing dpkg-dev upgraded `perl-base`, i.e. the "real-world upgradable" package disappeared from the list) - prefer `shell`.
- Missing `Date:` in Release gives `W: Invalid 'Date' entry in Release file`; the generated Release has one. A Release without any file also works with `[trusted=yes]` but is noisy (`Method gave a blank filename` x6), hence the generated Release.
- Optional knobs: `SU_FIXTURE_OFFLINE=1` (moves the distro's real sources to `/srv/su-disabled-sources` => hermetic, 0.4 s, works with `--network none`), `SU_FIXTURE_EXTRA=1` (su-dummy-d/newdep/e/f/v/w/alt scenarios for kept-back, removal, virtual and alternatives), `SU_FIXTURE_BAD=1` (`su-dummy-bad` 2.0 with failing postinst). Wipe guard: repo/old dirs must match `/srv/su-*`, `/tmp/su-*`, `/var/tmp/su-*`. Re-running in a dirty container works (uses `--force-confnew`, `</dev/null`; a downgrade is reported on stderr).
- Real-world upgradable packages of the base image are **kept** (not touched) and printed as a `NOTE:` line, e.g. debian:12 `perl-base`, debian:13 `liblzma5`, ubuntu:22.04 `libssl3`, ubuntu:24.04 `libaudit-common libaudit1 libssl3t64`, ubuntu:latest `libssl3t64 openssl-provider-legacy`. They are time dependent: tests must not hard-code them; assert only on `su-dummy-*`.
Proof, exact required invocation (`docker run --rm -i -v <project>/discovery/apt:/d:ro IMAGE bash /d/fixture.sh`), all [exit=0], no stderr output:
```
== debian:12 [fixture] repo /srv/su-repo indexed with 'shell': 3 packages
[fixture] installed (old): su-dummy-a=1.0 su-dummy-b=1.0 su-dummy-c=1.0
[fixture] upgradable dummy packages: su-dummy-a su-dummy-b su-dummy-c
[fixture] NOTE: real-world upgradable packages present in this base image: perl-base
[fixture] OK in 3s (image: Debian GNU/Linux 12 (bookworm))
== ubuntu:24.04 ... upgradable dummy packages: su-dummy-a su-dummy-b su-dummy-c
NOTE: ... libaudit-common libaudit1 libssl3t64 ; OK in 5s (image: Ubuntu 24.04.5 LTS)
== debian:13, ubuntu:22.04, ubuntu:latest(26.04.1): same, OK in 3s / 7s / 6s
```
Also verified: `SU_FIXTURE_INDEXER=scanpackages|ftparchive` on debian:12, debian:13, ubuntu:24.04, ubuntu:latest; `SU_FIXTURE_OFFLINE=1 SU_FIXTURE_EXTRA=1 SU_FIXTURE_BAD=1 --network none` on all five; `smoke.sh` (32 checks: Inst parse, kept-back parse, description awk, rdepends, three closure methods, hold/restore, upgrade, purge, autoremove) `ALL PASSED` on all five images.
Fixture-state facts useful for tests: `apt list --upgradable` => `su-dummy-a/su-repo 2.0 all [upgradable from: 1.0]`; `Inst su-dummy-a [1.0] (2.0 su-fixture:su-repo [all])`; `apt-cache policy su-dummy-a` => Installed 1.0 / Candidate 2.0, table `2.0 500 / 500 file:/srv/su-repo ./ Packages` and ` *** 1.0 100 / 100 /var/lib/dpkg/status`.
## 11. Item 11 - timing (rough, this host, 3 runs each, network OK)
| image | `apt-get update` cold (lists empty) | lists size | `fixture.sh` default (incl. real update + 3 apt calls) | `fixture.sh` OFFLINE (`--network none`) | one `apt-get -s upgrade` / `apt list` / `apt-cache policy` |
|---|---|---|---|---|---|
| debian:12 | 1.1 s | 19 MB | 2.8-3.1 s (docker wall 3.2-3.4) | 0.4 s | 0.72 / 0.35 / 0.31 s |
| debian:13 | 1.0-1.1 s | 21 MB | 3.0-3.3 s | 0.4 s | 0.82 / 0.44 / 0.31 s |
| ubuntu:22.04 | 2.5-3.4 s | 78 MB | 5.7-5.8 s | 0.4 s | 1.62 / 0.92 / 0.71 s |
| ubuntu:24.04 | 2.2-3.3 s | 52 MB | 4.9 s | 0.3-0.4 s | 1.11 / 0.63 / 0.47 s |
| ubuntu:latest | 1.7-3.1 s | 42 MB | 4.1-4.4 s | 0.5 s | 1.00 / 0.56 / 0.40 s |
Container start overhead is ~0.2-0.3 s; `docker pull` of the five images took 3-8 s each. Network variance dominates `update`. `smoke.sh` (hermetic) takes a few seconds per image. Because the images have no apt binary cache, budget ~0.3-1.6 s **per apt invocation** in tests, and prefer one batched call over per-package loops. `apt-get install bats` (no recommends) +0.7-1.7 s; with recommends 5.7 s (debian:12) / 13 s (ubuntu:24.04).
## 12. Differences between the five images (summary)
| aspect | debian:12 | debian:13 | ubuntu:22.04 | ubuntu:24.04 | ubuntu:latest (26.04) |
|---|---|---|---|---|---|
| apt / solver | 2.6.1 classic | 3.0.3 classic (behaves like 12) | 2.4.14 classic | 2.8.3 classic | **3.2.0, solver3 default** |
| sources format | `debian.sources` (deb822) | deb822 | `sources.list` (one-line) | `ubuntu.sources` (deb822) | `ubuntu.sources` |
| repo string in `Inst` (real) | `Debian:12.15/oldstable`, `Debian-Security:12/oldstable-security` | `Debian:13.7/stable`, `Debian-Security:13/stable-security` | `Ubuntu:22.04/jammy-updates, Ubuntu:22.04/jammy-security` | `Ubuntu:24.04/noble-updates, Ubuntu:24.04/noble-security` | `Ubuntu:26.04/resolute-updates, Ubuntu:26.04/resolute-security` |
| `Solving dependencies...` line | no | no | no | no | **yes** (in simulations/removals, stdout) |
| `dist-upgrade` removes a manually-installed conflicting pkg | yes | yes | yes | yes | **no** (kept back) |
| `Description-md5:` in `apt-cache show` of installed-only | value | empty | value | empty | empty |
| Essential `login` (`apt-get -y purge login`) | protected | protected | protected | protected | **not Essential: purged without error** |
| bats | 1.8.2 | 1.11.1 | **1.2.1**, no helper libs | 1.10.0 | 1.13.0 |
Everything else compared with `diff` over a 385-line transcript of ~60 commands (update, list, simulate, hold, show/policy/dpkg -s, depends/rdepends, real upgrade, dist-upgrade, purge, autoremove, error paths): identical wording and exit codes across the five images apart from the rows above and checksums/sizes. Specifically identical: `apt list` stderr warning, `Inst`/`Conf`/`Remv`/`Purg` formats, `kept back` block, `apt-mark` messages, `apt-cache depends/rdepends` formats, `E:`/`W:` texts and exit codes (0 / 100), lock message, conffile failure, Essential protection message.
Pre-existing docker images were not touched (`images-before.tsv` compared: nothing missing or changed); only `debian:12`, `debian:13`, `ubuntu:22.04`, `ubuntu:24.04`, `ubuntu:latest` were pulled and only `docker run --rm` containers were used (one hung throwaway container of mine, caused by a test that re-ran the fixture over a locally modified conffile, was `docker kill`ed).
discovery/apt/closure-dpkg.awk
+41
View File
@@ -0,0 +1,41 @@
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# closure-dpkg.awk - dependency closure (Pre-Depends + Depends) of installed packages, computed
# from the dpkg database only (exactly the dependencies of the INSTALLED versions; virtual
# packages are resolved through the Provides of installed packages; every installed alternative
# of an "a | b" group is followed).
# usage: dpkg-query -W -f '${db:Status-Abbrev}\t${Package}\t${Pre-Depends}\t${Depends}\t${Provides}\n' \
# | awk -F'\t' -v roots="pkg1 pkg2" -f closure-dpkg.awk
# output: plain package names, one per line, roots included (only if installed), BFS order
function trim(s) { gsub(/^[ ]+|[ ]+$/, "", s); return s }
substr($1, 2, 1) ~ /[nc]/ { next } # not-installed / config-files-only
{
inst[$2] = 1
deps[$2] = $3 "," $4
n = split($5, pv, ",")
for (i = 1; i <= n; i++) {
p = trim(pv[i]); sub(/ .*/, "", p); sub(/:.*/, "", p)
if (p != "") prov[p] = prov[p] " " $2
}
}
END {
nr = split(roots, r, " ")
for (i = 1; i <= nr; i++) if (inst[r[i]] && !seen[r[i]]) { seen[r[i]] = 1; q[++t] = r[i] }
for (h = 1; h <= t; h++) {
p = q[h]; print p
m = split(deps[p], d, ",")
for (j = 1; j <= m; j++) {
na = split(d[j], alt, "|")
for (k = 1; k <= na; k++) {
a = alt[k]
gsub(/\([^)]*\)/, "", a); gsub(/\[[^]]*\]/, "", a); gsub(/<[^>]*>/, "", a)
a = trim(a); sub(/:(any|native)$/, "", a)
if (a == "") continue
if (inst[a] && !seen[a]) { seen[a] = 1; q[++t] = a }
np = split(prov[a], pp, " ")
for (x = 1; x <= np; x++) if (!seen[pp[x]]) { seen[pp[x]] = 1; q[++t] = pp[x] }
}
}
}
}
discovery/apt/fixture.sh
Executable
+217
View File
@@ -0,0 +1,217 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# fixture.sh - APT e2e fixture for skeptical-updater (Debian/Ubuntu containers).
#
# Builds a local *flat* APT repository at /srv/su-repo containing dummy packages
# and installs the old (1.0) versions, so that after `apt-get update` the package
# manager reports deterministic upgrades:
#
# su-dummy-a 1.0 -> 2.0 (Depends: su-dummy-b, ships a conffile)
# su-dummy-b 1.0 -> 2.0 (dependency of su-dummy-a)
# su-dummy-c 1.0 -> 2.0 (standalone)
#
# Optional extras (SU_FIXTURE_EXTRA=1) for "kept back" / removal / virtual-package
# scenarios:
# su-dummy-d 1.0 -> 2.0 2.0 adds a NEW dependency (su-dummy-newdep, not installed)
# => plain `upgrade` keeps it back, `--with-new-pkgs upgrade`
# and `dist-upgrade` install it
# su-dummy-e 1.0 -> 2.0 2.0 Conflicts: su-dummy-f (installed, no 2.0 exists)
# => only `dist-upgrade` can do it (removes su-dummy-f) - except with apt 3.x
# solver3 (ubuntu:latest = 26.04) which refuses to remove the manually
# installed su-dummy-f and keeps su-dummy-e back even for dist-upgrade
# su-dummy-f 1.0 installed, never upgradable
# su-dummy-w 1.0 -> 2.0 Depends: su-virtual | su-dummy-alt (virtual + alternative)
# su-dummy-v 1.0 Provides: su-virtual
# (+ su-dummy-newdep 1.0 and su-dummy-alt 1.0: only in the repo, never pre-installed)
#
# Environment knobs (all optional):
# SU_REPO_DIR=/srv/su-repo where the repo is created (wiped first; must match /srv/su-*, /tmp/su-*, /var/tmp/su-*)
# SU_OLD_DIR=/srv/su-old where the 1.0 .debs are kept (NOT in the repo)
# SU_FIXTURE_INDEXER=shell shell | scanpackages | ftparchive
# shell = no extra tools needed (dpkg-deb -f + sha256sum)
# scanpackages = dpkg-scanpackages (installs dpkg-dev if missing)
# ftparchive = apt-ftparchive (installs apt-utils if missing)
# SU_FIXTURE_OFFLINE=1 disable the distro's real sources (hermetic: no network at all)
# SU_FIXTURE_EXTRA=1 add the extra scenario packages listed above
# SU_FIXTURE_BAD=1 add su-dummy-bad: 1.0 installed, 2.0 has a postinst that fails
# (apt-get upgrade then exits 100) - for error-path tests
#
# Must run as root inside a throwaway container, e.g.:
# docker run --rm -i -v "$PWD/discovery/apt:/d:ro" debian:12 bash /d/fixture.sh
set -euo pipefail
export LC_ALL=C DEBIAN_FRONTEND=noninteractive
REPO_DIR=${SU_REPO_DIR:-/srv/su-repo}
OLD_DIR=${SU_OLD_DIR:-/srv/su-old}
INDEXER=${SU_FIXTURE_INDEXER:-shell}
OFFLINE=${SU_FIXTURE_OFFLINE:-0}
EXTRA=${SU_FIXTURE_EXTRA:-0}
BAD=${SU_FIXTURE_BAD:-0}
SOURCES_FILE=/etc/apt/sources.list.d/su-repo.list
T0=$(date +%s)
log() { printf '[fixture] %s\n' "$*"; }
die() { printf '[fixture] ERROR: %s\n' "$*" >&2; exit 1; }
[ "$(id -u)" -eq 0 ] || die "must run as root"
command -v apt-get >/dev/null || die "apt-get not found (not a Debian/Ubuntu image?)"
command -v dpkg-deb >/dev/null || die "dpkg-deb not found"
case $INDEXER in shell|scanpackages|ftparchive) ;; *) die "bad SU_FIXTURE_INDEXER=$INDEXER" ;; esac
# the directories are wiped with rm -rf: only accept obviously fixture-owned locations
for d in "$REPO_DIR" "$OLD_DIR"; do
case $d in /srv/su-*|/tmp/su-*|/var/tmp/su-*) ;; *) die "refusing to wipe '$d' (must match /srv/su-*, /tmp/su-* or /var/tmp/su-*)" ;; esac
done
# ---------------------------------------------------------------- build debs
# mkdeb NAME VERSION OUTDIR [extra control line]...
# If $MKDEB_POSTINST is set it becomes the body of the package's postinst script.
mkdeb() {
local name=$1 ver=$2 out=$3 root line
shift 3
root=$(mktemp -d)
mkdir -p "$root/DEBIAN" "$root/usr/share/su-dummy" "$root/etc/su-dummy"
{
printf 'Package: %s\nVersion: %s\nSection: misc\nPriority: optional\n' "$name" "$ver"
printf 'Architecture: all\nMaintainer: Skeptical Updater Fixture <su-fixture@example.invalid>\n'
for line in "$@"; do printf '%s\n' "$line"; done
printf 'Description: dummy package %s for skeptical-updater tests\n' "$name"
printf ' This package only exists to exercise the package manager.\n'
printf ' .\n'
printf ' It ships one data file and one conffile (version %s).\n' "$ver"
} > "$root/DEBIAN/control"
echo "$ver" > "$root/usr/share/su-dummy/$name"
echo "version=$ver" > "$root/etc/su-dummy/$name.conf"
echo "/etc/su-dummy/$name.conf" > "$root/DEBIAN/conffiles"
if [ -n "${MKDEB_POSTINST:-}" ]; then
printf '#!/bin/sh\n%s\n' "$MKDEB_POSTINST" > "$root/DEBIAN/postinst"
chmod 755 "$root/DEBIAN/postinst"
fi
mkdir -p "$out"
# -Zgzip: readable by every dpkg in the supported images; --root-owner-group: files owned by root
dpkg-deb --root-owner-group -Zgzip --build "$root" "$out/${name}_${ver}_all.deb" >/dev/null
rm -rf "$root"
}
rm -rf "$REPO_DIR" "$OLD_DIR"
mkdir -p "$REPO_DIR" "$OLD_DIR"
# old versions (installed straight away with dpkg, NOT published in the repo)
mkdeb su-dummy-a 1.0 "$OLD_DIR" 'Depends: su-dummy-b'
mkdeb su-dummy-b 1.0 "$OLD_DIR"
mkdeb su-dummy-c 1.0 "$OLD_DIR"
# new versions (published in the repo)
mkdeb su-dummy-a 2.0 "$REPO_DIR" 'Depends: su-dummy-b (>= 2.0)'
mkdeb su-dummy-b 2.0 "$REPO_DIR"
mkdeb su-dummy-c 2.0 "$REPO_DIR"
if [ "$EXTRA" = 1 ]; then
mkdeb su-dummy-d 1.0 "$OLD_DIR"
mkdeb su-dummy-d 2.0 "$REPO_DIR" 'Depends: su-dummy-newdep'
mkdeb su-dummy-newdep 1.0 "$REPO_DIR" # only in the repo, never pre-installed
mkdeb su-dummy-e 1.0 "$OLD_DIR"
mkdeb su-dummy-e 2.0 "$REPO_DIR" 'Conflicts: su-dummy-f'
mkdeb su-dummy-f 1.0 "$OLD_DIR"
mkdeb su-dummy-v 1.0 "$OLD_DIR" 'Provides: su-virtual'
mkdeb su-dummy-alt 1.0 "$REPO_DIR" # alternative target, not installed
mkdeb su-dummy-w 1.0 "$OLD_DIR" 'Depends: su-virtual | su-dummy-alt'
mkdeb su-dummy-w 2.0 "$REPO_DIR" 'Depends: su-virtual | su-dummy-alt'
fi
if [ "$BAD" = 1 ]; then
mkdeb su-dummy-bad 1.0 "$OLD_DIR"
MKDEB_POSTINST='[ "$1" = configure ] && { echo "su-dummy-bad: postinst failing on purpose" >&2; exit 1; }; exit 0' \
mkdeb su-dummy-bad 2.0 "$REPO_DIR"
fi
# ---------------------------------------------------------------- real sources
if [ "$OFFLINE" = 1 ]; then
mkdir -p /srv/su-disabled-sources
for f in /etc/apt/sources.list /etc/apt/sources.list.d/*.sources /etc/apt/sources.list.d/*.list; do
[ -e "$f" ] || continue
case $f in "$SOURCES_FILE") continue ;; esac
mv "$f" "/srv/su-disabled-sources/$(basename "$f")"
done
log "OFFLINE: real sources moved to /srv/su-disabled-sources"
fi
# ---------------------------------------------------------------- indexing
install_tool() { # install_tool PACKAGE : needs the real mirrors
[ "$OFFLINE" = 1 ] && die "SU_FIXTURE_INDEXER=$INDEXER needs network to install $1; use shell with OFFLINE"
log "installing $1 (needs network)"
apt-get update -qq >/dev/null
apt-get install -y -qq --no-install-recommends "$1" >/dev/null
}
index_shell() {
local f
: > Packages
for f in ./*.deb; do
f=${f#./}
dpkg-deb -f "$f" >> Packages
printf 'Filename: ./%s\nSize: %s\nMD5sum: %s\nSHA256: %s\n\n' \
"$f" "$(stat -c %s "$f")" "$(md5sum < "$f" | cut -d' ' -f1)" "$(sha256sum < "$f" | cut -d' ' -f1)" >> Packages
done
{
printf 'Origin: su-fixture\nLabel: su-fixture\nSuite: su-repo\nCodename: su-repo\n'
printf 'Date: %s\n' "$(date -u '+%a, %d %b %Y %H:%M:%S UTC')"
printf 'SHA256:\n %s %s Packages\n' "$(sha256sum < Packages | cut -d' ' -f1)" "$(stat -c %s Packages)"
} > Release
}
index_scanpackages() {
command -v dpkg-scanpackages >/dev/null || install_tool dpkg-dev
dpkg-scanpackages --multiversion . /dev/null > Packages 2>/dev/null
# dpkg-scanpackages does not write a Release file; make a minimal one
{
printf 'Origin: su-fixture\nLabel: su-fixture\nSuite: su-repo\nCodename: su-repo\n'
printf 'Date: %s\n' "$(date -u '+%a, %d %b %Y %H:%M:%S UTC')"
printf 'SHA256:\n %s %s Packages\n' "$(sha256sum < Packages | cut -d' ' -f1)" "$(stat -c %s Packages)"
} > Release
}
index_ftparchive() {
command -v apt-ftparchive >/dev/null || install_tool apt-utils
apt-ftparchive packages . > Packages
apt-ftparchive \
-o APT::FTPArchive::Release::Origin=su-fixture \
-o APT::FTPArchive::Release::Label=su-fixture \
-o APT::FTPArchive::Release::Suite=su-repo \
-o APT::FTPArchive::Release::Codename=su-repo \
release . > Release
}
( cd "$REPO_DIR" && "index_$INDEXER" )
log "repo $REPO_DIR indexed with '$INDEXER': $(grep -c '^Package:' "$REPO_DIR/Packages") packages"
echo "deb [trusted=yes] file:$REPO_DIR ./" > "$SOURCES_FILE"
# ---------------------------------------------------------------- install old versions
# --force-confnew + </dev/null: never block on a conffile prompt if the fixture is re-run in a dirty container
dpkg --force-confnew -i "$OLD_DIR"/*.deb >/dev/null </dev/null
log "installed (old): $(dpkg-query -W -f '${db:Status-Abbrev} ${Package}=${Version}\n' 'su-dummy-*' 2>/dev/null | awk '$1 == "ii" {printf "%s ", $2}')"
# ---------------------------------------------------------------- refresh + verify
# drop stale lists of our own repo first: apt compares mtimes of file: indexes with 1s resolution,
# so a repo regenerated within the same second would otherwise be seen as "unchanged"
rm -f /var/lib/apt/lists/"$(printf '%s' "$REPO_DIR" | tr / _)"_*
apt-get update -qq >/dev/null
fail=0
upg=$(apt list --upgradable 2>/dev/null | awk -F/ '/^su-dummy-/{print $1}' | sort | tr '\n' ' ')
for p in su-dummy-a su-dummy-b su-dummy-c; do
case " $upg" in *" $p "*) ;; *) log "MISSING from upgradable: $p"; fail=1 ;; esac
done
sim=$(apt-get -s --with-new-pkgs upgrade 2>/dev/null | awk '/^Inst su-dummy-(a|b|c) /{n++} END{print n+0}')
[ "$sim" -ge 3 ] || { log "simulated upgrade only covers $sim of 3 core packages"; fail=1; }
[ "$fail" -eq 0 ] || die "fixture verification failed"
log "upgradable dummy packages: $upg"
real=$(apt list --upgradable 2>/dev/null | awk -F/ 'NR>1 && $1 !~ /^su-dummy-/{print $1}' | tr '\n' ' ')
if [ -n "$real" ]; then
log "NOTE: real-world upgradable packages present in this base image: $real"
else
log "NOTE: no real-world upgradable packages in this base image right now"
fi
log "OK in $(( $(date +%s) - T0 ))s (image: $(. /etc/os-release; echo "$PRETTY_NAME"))"
discovery/apt/parse-inst.awk
+29
View File
@@ -0,0 +1,29 @@
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# parse-inst.awk - parse the "Inst" lines of `LC_ALL=C apt-get -s <verb>` into TSV.
# usage: LC_ALL=C apt-get -s --with-new-pkgs upgrade | awk -f parse-inst.awk
# output: name<TAB>oldversion<TAB>newversion<TAB>repo
# oldversion is "-" for packages that are newly installed (no previous version);
# repo is the raw origin list, e.g. "Ubuntu:24.04/noble-updates, Ubuntu:24.04/noble-security"
# (may be empty for packages coming from a local .deb). POSIX awk, tested with mawk 1.3.4.
/^Inst / {
name = $2
rest = $0
sub(/^Inst [^ ]+ /, "", rest)
old = "-"
if (substr(rest, 1, 1) == "[") { # "[old] (new origins [arch])"
old = rest
sub(/^\[/, "", old)
sub(/\].*$/, "", old)
sub(/^\[[^]]*\] /, "", rest)
}
sub(/^\(/, "", rest) # "new origins [arch]) ..."
new = rest
sub(/ .*$/, "", new)
sub(/^[^ ]+ ?/, "", rest) # "origins [arch]) ..."
i = index(rest, "])")
repo = substr(rest, 1, i - 1) # "origins [arch"
sub(/ ?\[[^[]*$/, "", repo) # drop " [arch"
printf "%s\t%s\t%s\t%s\n", name, old, new, repo
}
discovery/apt/smoke.sh
Executable
+110
View File
@@ -0,0 +1,110 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# smoke.sh - proves that the command recipes documented in discovery/apt.md work, on top of fixture.sh.
# docker run --rm -i --network none -v "$PWD/discovery/apt:/d:ro" debian:12 bash /d/smoke.sh
# Runs fixture.sh in hermetic mode (SU_FIXTURE_OFFLINE=1, SU_FIXTURE_EXTRA=1) and then asserts.
set -uo pipefail
export LC_ALL=C DEBIAN_FRONTEND=noninteractive
HERE=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
fails=0
ok() { printf 'PASS %s\n' "$1"; }
bad() { printf 'FAIL %s\n got: %s\n expected: %s\n' "$1" "$2" "$3"; fails=$((fails + 1)); }
check() { # check LABEL GOT EXPECTED
if [ "$2" = "$3" ]; then ok "$1"; else bad "$1" "$2" "$3"; fi
}
ver() { dpkg-query -W -f '${Version}' "$1" 2>/dev/null; }
SU_FIXTURE_OFFLINE=1 SU_FIXTURE_EXTRA=1 bash "$HERE/fixture.sh" >/dev/null || { echo "fixture failed"; exit 2; }
echo "image: $(. /etc/os-release; echo "$PRETTY_NAME") apt: $(apt-get --version | head -1)"
# ---- 1. refresh: exit code is 0 and the unreachable-source case is made fatal by Error-Mode=any
apt-get update -qq -o APT::Update::Error-Mode=any >/dev/null 2>&1; check "update exit code" "$?" "0"
# ---- 2. upgradable list (Inst parse) + kept-back parse + apt list cross-check
list=$(apt-get -s --with-new-pkgs upgrade 2>/dev/null | awk -f "$HERE/parse-inst.awk" | sort)
check "Inst parse su-dummy-a" "$(printf '%s\n' "$list" | grep '^su-dummy-a')" "$(printf 'su-dummy-a\t1.0\t2.0\tsu-fixture:su-repo')"
check "Inst parse new package (old=-)" "$(printf '%s\n' "$list" | grep '^su-dummy-newdep')" "$(printf 'su-dummy-newdep\t-\t1.0\tsu-fixture:su-repo')"
kept=$(apt-get -s --with-new-pkgs upgrade 2>/dev/null | awk '/^The following packages have been kept back:/{k=1;next} k&&/^ /{for(i=1;i<=NF;i++)print $i;next} {k=0}' | tr '\n' ' ')
check "kept-back parse" "$kept" "su-dummy-e "
alist=$(apt list --upgradable 2>/dev/null | sed -nE 's#^([^/]+)/([^ ]+) ([^ ]+) ([^ ]+) \[upgradable from: ([^]]+)\]$#\1\t\5\t\3\t\2#p' | grep '^su-dummy-a')
check "apt list parse" "$alist" "$(printf 'su-dummy-a\t1.0\t2.0\tsu-repo')"
# ---- 3. description
desc=$(apt-cache show --no-all-versions su-dummy-a | awk '
/^Description(-[a-z][a-z](_[A-Z][A-Z])?)?:/ { p=1; sub(/^[^:]*: ?/,""); print; next }
p && /^ / { l=substr($0,2); print (l=="." ? "" : l); next }
p { exit }')
check "description first line" "$(printf '%s\n' "$desc" | head -1)" "dummy package su-dummy-a for skeptical-updater tests"
check "description line count" "$(printf '%s\n' "$desc" | wc -l | tr -d ' ')" "4"
# ---- 4. rdepends / closure
RD="--installed --no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances"
rd=$(apt-cache rdepends $RD su-dummy-b | awk '/^Reverse Depends:/{p=1;next} p{sub(/^[ |]+/,""); print}' | sort -u | tr '\n' ' ')
check "rdepends su-dummy-b" "$rd" "su-dummy-a "
NI="--no-recommends --no-suggests --no-conflicts --no-breaks --no-replaces --no-enhances"
installed_names() { dpkg-query -W -f '${db:Status-Abbrev}\t${Package}\n' | awk -F'\t' 'substr($1,2,1) !~ /[nc]/ {print $2}' | sort -u; }
clos=$(comm -12 <(apt-cache depends --recurse $NI su-dummy-w | awk '/^[^ <]/' | sort -u) <(installed_names) | tr '\n' ' ')
check "closure su-dummy-w via virtual (no --installed)" "$clos" "su-dummy-v su-dummy-w "
clos_flag=$(apt-cache depends --recurse --installed $NI su-dummy-w | awk '/^[^ <]/' | sort -u | tr '\n' ' ')
check "closure su-dummy-w WITH --installed (documented defect: provider lost)" "$clos_flag" "su-dummy-w "
clos_dpkg=$(dpkg-query -W -f '${db:Status-Abbrev}\t${Package}\t${Pre-Depends}\t${Depends}\t${Provides}\n' | awk -F'\t' -v roots="su-dummy-w" -f "$HERE/closure-dpkg.awk" | sort -u | tr '\n' ' ')
check "closure su-dummy-w via dpkg awk" "$clos_dpkg" "su-dummy-v su-dummy-w "
# real package: base-files Pre-Depends on the virtual 'awk' (provided by the installed mawk)
real_dpkg=$(dpkg-query -W -f '${db:Status-Abbrev}\t${Package}\t${Pre-Depends}\t${Depends}\t${Provides}\n' | awk -F'\t' -v roots="base-files" -f "$HERE/closure-dpkg.awk" | sort -u | tr '\n' ' ')
case " $real_dpkg" in *" mawk "*) ok "closure-dpkg base-files reaches mawk through virtual awk" ;; *) bad "closure-dpkg base-files reaches mawk" "$real_dpkg" "... mawk ..." ;; esac
real_flag=$(apt-cache depends --recurse --installed $NI base-files | awk '/^[^ <]/' | sort -u | tr '\n' ' ')
case " $real_flag" in *" mawk "*) bad "apt-cache --recurse --installed base-files lacks mawk (documented defect)" "$real_flag" "no mawk" ;; *) ok "apt-cache --recurse --installed base-files lacks mawk (documented defect)" ;; esac
# ---- 5. hold / exclusion recipe + upgrade + restore
SU_STATE_DIR=$(mktemp -d); SU_HOLDS_ADDED=$SU_STATE_DIR/holds.added
su_holds_begin() {
mkdir -p "$SU_STATE_DIR" || return 1
local held p; held=$(apt-mark showhold) || return 1
: > "$SU_HOLDS_ADDED"
for p in "$@"; do
grep -qxF -- "$p" <<<"$held" && continue
echo "$p" >> "$SU_HOLDS_ADDED"
apt-mark hold "$p" >/dev/null || return 1
done
}
su_holds_restore() {
[ -f "$SU_HOLDS_ADDED" ] || return 0
apt-mark showhold | sort -u | comm -12 - <(sort -u "$SU_HOLDS_ADDED") | xargs -r apt-mark unhold >/dev/null
rm -f "$SU_HOLDS_ADDED"
}
apt-mark hold su-dummy-alt >/dev/null # pre-existing admin hold: must survive untouched
before=$(apt-mark showhold | sort | tr '\n' ' ')
su_holds_begin su-dummy-c su-dummy-alt
check "hold set during run" "$(apt-mark showhold | sort | tr '\n' ' ')" "su-dummy-alt su-dummy-c "
apt-get -y -o Dpkg::Options::=--force-confdef -o Dpkg::Options::=--force-confold -o DPkg::Lock::Timeout=60 \
--with-new-pkgs upgrade >/dev/null 2>&1; check "upgrade exit code" "$?" "0"
check "held pkg skipped (c)" "$(ver su-dummy-c)" "1.0"
check "a upgraded" "$(ver su-dummy-a)" "2.0"; check "b upgraded" "$(ver su-dummy-b)" "2.0"
check "new dep installed via --with-new-pkgs" "$(ver su-dummy-newdep)" "1.0"
check "kept back e untouched" "$(ver su-dummy-e)" "1.0"
su_holds_restore
check "hold set restored exactly" "$(apt-mark showhold | sort | tr '\n' ' ')" "$before"
# crash recovery: journal survives, admin edits in between are respected
su_holds_begin su-dummy-b su-dummy-e; apt-mark hold su-dummy-w >/dev/null; apt-mark unhold su-dummy-alt >/dev/null # (no restore = simulated kill -9)
su_holds_restore
check "crash recovery releases only our holds, keeps admin edits" "$(apt-mark showhold | sort | tr '\n' ' ')" "su-dummy-w "
apt-mark unhold su-dummy-w >/dev/null
apt-get -y --with-new-pkgs upgrade >/dev/null 2>&1; check "second upgrade exit code" "$?" "0"
check "c upgraded after restore" "$(ver su-dummy-c)" "2.0"
noop=$(apt-get -y --with-new-pkgs upgrade 2>&1); rc=$?
check "nothing-to-do exit code" "$rc" "0"
check "nothing-to-do summary" "$(printf '%s\n' "$noop" | grep -E '^[0-9]+ upgraded')" "0 upgraded, 0 newly installed, 0 to remove and 1 not upgraded."
# ---- 6. purge + autoremove
apt-mark auto su-dummy-b >/dev/null
apt-get -y purge su-dummy-a >/dev/null 2>&1; check "purge exit code" "$?" "0"
check "a purged (no dpkg status)" "$(dpkg-query -W -f '${db:Status-Abbrev}' su-dummy-a 2>/dev/null)" ""
check "autoremove --purge candidate" "$(apt-get -s autoremove --purge | awk '/^Purg /{print $2}' | tr '\n' ' ')" "su-dummy-b "
apt-get -y autoremove --purge >/dev/null 2>&1; check "autoremove exit code" "$?" "0"
check "b gone" "$(dpkg-query -W -f '${db:Status-Abbrev}' su-dummy-b 2>/dev/null)" ""
check "conffile of b gone" "$(ls /etc/su-dummy/su-dummy-b.conf 2>&1 | grep -c 'No such file')" "1"
rm -rf "$SU_STATE_DIR"
[ "$fails" -eq 0 ] && echo "ALL PASSED" || { echo "$fails FAILED"; exit 1; }
discovery/pacman.md
+570
View File
@@ -0,0 +1,570 @@
# Discovery: pacman (Arch Linux) and `pman`
Everything below was run in throwaway containers (`docker run --rm -i`, `LC_ALL=C`) on
2026-10-09 against `archlinux:latest` (pacman 7.1.0 / libalpm 16.0.1, bash 5.3.20).
Companion files (all in `discovery/pacman/`):
| file | purpose |
|--------------|---------|
| `fixture.sh` | E2E fixture: dummy packages `su-dummy-{a,b,c}` 1.0 installed, 2.0 offered by a local repo |
| `lib.sh` | proven bash helpers (`pm_upgradable`, `pm_field`, `pm_closure`, `pm_plan`, ...) |
| `checks.sh` | executable proof of this document (`ALL CHECKS PASSED` on `archlinux:latest` and `archlinux:base-devel`) |
Re-run the proof:
```
docker run --rm -i -v "$PWD/discovery/pacman:/d:ro" archlinux:latest bash /d/fixture.sh
docker run --rm -i -v "$PWD/discovery/pacman:/d:ro" archlinux:latest bash /d/checks.sh
```
## 0. Summary / chosen commands
| need | command |
|------|---------|
| refresh (root) | `pacman -Sy` (then apply with `pacman -Su`, see section 1) |
| upgradable list | `pacman -Qu` -> `name old -> new [ignored]`; repo from `pacman -Sl` (first repo with that name wins) |
| exact transaction (incl. new deps) | `pacman -Sup --noconfirm [--ignore a,b] --print-format '%r/%n %v'` |
| description | `pacman -Qi -- name` / `pacman -Si -- repo/name`, field `Description` |
| installed reverse deps | `pacman -Qi` fields `Required By` / `Optional For` |
| dependency closure | one `pacman -Qi` dump + awk BFS (`pm_closure`); `pactree` is not in the base image |
| per-run exclusion | `pacman -Su --noconfirm --ignore a,b` (or repeated `--ignore`); globs work |
| upgrade | `pacman -Su --noconfirm` (`-Syu` if you did not refresh before) |
| purge | `pacman -Rns --noconfirm -- pkg...` |
Top gotchas (details below):
1. The fresh image has **no sync databases**: `pacman -Si/-Sl/-Qu` are useless (and `-S bats` says
"not found") until `pacman -Sy` has run.
2. `pacman -Qu` has **no `--ignore`** (`error: invalid option '--ignore'`, exit 1). Per-run exclusions must be
filtered by the tool itself; `[ignored]` is only shown for IgnorePkg/IgnoreGroup from the config.
3. `pacman -Qu` exits **1** when nothing is upgradable (empty output); `-Su`/`-Syu` exit **0** with
` there is nothing to do`.
4. Excluding a package that another upgraded package needs at a higher version makes the **whole
transaction fail** under `--noconfirm` (exit 1, nothing upgraded). Pre-check with `pacman -Sup`.
5. `-Qi`/`-Si` **wrap** long values at `$COLUMNS` (even when piped) if `COLUMNS` is exported. Use `COLUMNS=0` and
a continuation-aware parser (lib.sh does both).
6. `pactree -l -u` prints **dependency strings** (`libncursesw.so=6-64`, `linux-api-headers>=4.10`), not package
names, and `pacman-contrib` is not installed.
7. The image's `/etc/pacman.conf` ends with a second `[options]` block (NoExtract lines). Appending
`Include = /etc/pacman.d/ignorepkg` at EOF works *by accident* here; on a stock Arch host the last section is `[extra]`
and pacman just warns `directive 'IgnorePkg' in section 'extra' not recognized.` and ignores nothing.
8. `makepkg` refuses root (exit 10); `runuser -u <user> --` works, `sudo` is absent.
## 1. Refreshing metadata
```
$ pacman -Sy # root; image has only /var/lib/pacman/{local,sync(empty)} before this
:: Synchronizing package databases...
core downloading...
extra downloading...
exit=0
```
Timing: cold `-Sy` 0.21-0.25 s, warm 0.12 s (fast CDN; core.db 130 KB, extra.db 8.8 MB). A second `-Sy`
prints the same "downloading..." lines (NoProgressBar), so the output cannot tell "up to date" from "refreshed".
On a fresh image (no `-Sy`):
```
$ pacman -Qu ; echo $?
warning: database file for 'core' does not exist (use '-Sy' to download)
warning: database file for 'extra' does not exist (use '-Sy' to download)
1
$ pacman -Si bats
error: package 'bats' was not found
```
How many upgrades does a fresh image have? Today only 6 (image built 5 days earlier):
```
$ pacman -Sy && pacman -Qu
ca-certificates-mozilla 3.130-1 -> 3.131-1
device-mapper 2.03.42-1 -> 2.03.43-2
expat 2.8.5-1 -> 2.9.0-1
glib2 2.88.3-1 -> 2.90.1-1
hwdata 0.411-1 -> 0.412-1 (+ libsysprof-capture)
```
The count is time-dependent; tests must not assert on it. Use `FIXTURE_ISOLATE=1` (section 10) for an exact set.
### Partial-upgrade concern
`pacman -Sy` alone moves the sync DB ahead of the installed packages. That is only dangerous if you then install
something (`pacman -S foo`) without a full upgrade; a `-Sy` immediately followed by `-Su` is the same as `-Syu`.
Two safe designs:
* **A (recommended, simple):** `pacman -Sy`, list with `-Qu`, let the user exclude, then apply with
`pacman -Su --noconfirm --ignore ...` (note `-Su`, not `-Syu`: it applies exactly the reviewed DB snapshot;
`-Syu` would re-sync and could add newer, unreviewed versions). If the user aborts after the refresh, tell them
the DB is refreshed (do not run `pacman -S x` without `-u`).
* **B (no side effects, root, no extra packages):** temporary sync DB. Verified:
```
tmp=$(mktemp -d /tmp/checkdb.XXXXXX); chmod 755 "$tmp" # 755 is REQUIRED (see below)
ln -s /var/lib/pacman/local "$tmp/local"
pacman -Sy --dbpath "$tmp" --logfile /dev/null # exit 0
pacman -Qu --dbpath "$tmp" # same list as design A
pacman -Sup --dbpath "$tmp" --print-format '%r/%n %v' # same transaction view
ls /var/lib/pacman/sync # still empty: system DB untouched
```
With the default `mktemp -d` mode 0700 it fails: `error: could not open file
/tmp/checkdb.X/sync/download-XXXX/core.db.part: Permission denied` (the sandboxed download user `alpm` cannot
traverse it); `chmod 755` or `--disable-sandbox` fixes it. When applying, use `-Syu` (re-sync) since the real
DB was not refreshed. `lib.sh: pm_refresh_tmpdb` sets `PM_OPTS=(--dbpath ...)`.
* **`checkupdates` (pacman-contrib) is NOT in the base image** (`archlinux:latest` and `:base-devel` both lack it
and `pactree`), and it hard-requires `fakeroot` (`Cannot find the fakeroot binary`; also absent from `latest`,
present in `base-devel`) even as root. After `pacman -S pacman-contrib fakeroot` it works: prints the same `-Qu`
lines (drops `[ignored]` rows, per its source `grep -v '\[.*\]'`), exit **0** = updates (verified), **2** = none
(verified), 1 = error (from the source: `Cannot fetch updates`). It is just B with
`fakeroot` instead of `chmod 755`; prefer B.
`pacman -Qu` and `pacman -Sup` need no root (verified as a normal user, exit 0), only the refresh and the real upgrade do.
## 2. Machine-parsable upgradable list
`pacman -Qu` (piped: no colour even with `Color` in pacman.conf; add `--color never` to be safe):
```
$ pacman -Qu
su-dummy-a 1.0-1 -> 2.0-1
su-dummy-b 1.0-1 -> 2.0-1
su-dummy-c 1.0-1 -> 2.0-1
$ pacman -Qu -q # names only
```
With `IgnorePkg` (from `Include = /etc/pacman.d/ignorepkg` inside `[options]`, one `IgnorePkg = x` per line,
several names per line allowed, globs allowed):
```
$ pacman -Qu
ca-certificates-mozilla 3.130-1 -> 3.131-1
expat 2.8.5-1 -> 2.9.0-1 [ignored]
glib2 2.88.3-1 -> 2.90.1-1 [ignored] # after "IgnorePkg = glib2 hwdata"
```
Format: `name SP oldver SP "->" SP newver [SP "[ignored]"]`; versions contain no spaces (epochs look like `1:1.37.2-3`).
Exit 0 if >=1 line, exit 1 and empty output otherwise (`[ignored]` rows count as lines, so exit stays 0 when
only ignored rows remain).
Repo of the candidate: `-Qu` does not print it. Use `pacman -Sl` (`repo name version [installed[: oldver]]`):
```
$ pacman -Sl | grep -E ' (expat|glib2) '
core expat 2.9.0-1 [installed: 2.8.5-1]
core glib2 2.90.1-1 [installed: 2.88.3-1]
```
A name can be in several repos. Verified with `su-dummy-b` 2.0-1 in `[su-dummy]` and 3.0-1 in a later
`[su-dummy2]`: `-Qu` reports `1.0-1 -> 2.0-1` (the **first repo in pacman.conf order** wins), `-Sl` lists both
rows in config order, and `-Si su-dummy-b` prints *both* blocks, so take the first `-Sl` row per name and use
`repo/name` for `-Si`. Exact parse (this is `lib.sh: pm_upgradable`, output
`name<TAB>old<TAB>new<TAB>repo<TAB>ignored(0|1)`):
```bash
awk '
FNR == NR { if (!($2 in repo)) repo[$2] = $1; next } # pacman -Sl
{ printf "%s\t%s\t%s\t%s\t%d\n", $1, $2, $4, repo[$1], ($5 == "[ignored]") } # pacman -Qu
' <(LC_ALL=C pacman -Sl) <(LC_ALL=C pacman -Qu)
```
```
su-dummy-a 1.0-1 2.0-1 su-dummy 0
ca-certificates-mozilla 3.130-1 3.131-1 core 0
```
Alternative that also yields the repo directly and is authoritative for what `-Su` will do:
`pacman -Sup --print-format '%r|%n|%v|%s|%l'` (`%s` download size, `%l` URL; works as non-root; dependency order;
**includes new dependencies and skips ignored packages**, which `-Qu` does not):
```
$ pacman -Sup --print-format '%r|%n|%v|%s'
core|ca-certificates-mozilla|3.131-1|391549
...
```
Verified with `su-dummy-a` 3.0 depending on a brand-new `su-dummy-new`: `-Qu` listed 3 packages, `-Sup`
listed 4 (`su-dummy-new 1.0-1` appears before `su-dummy-a`), and the new package is installed "as a dependency".
So a skeptical UI should show `-Qu` rows plus "also installs: ..." from `-Sup` minus `-Qu`.
Not covered by `-Qu`: packages pulled in via `replaces`.
## 3. Description and full info
```
$ pacman -Qi bash | head -5
Name : bash
Version : 5.3.20-1
Description : The GNU Bourne Again shell
Architecture : x86_64
URL : https://www.gnu.org/software/bash/bash.html
$ pacman -Si su-dummy/su-dummy-a | head -4 # the candidate (new version)
Repository : su-dummy
Name : su-dummy-a
Version : 2.0-1
Description : Skeptical-updater dummy package A
```
* Installed: `pacman -Qi -- name`; candidate: `pacman -Si -- repo/name` (always qualify with the repo, see the
two-repo note above). `-Si` has `Repository`, `Download Size`, `Build Date`, new `Depends On`; it has **no**
`Required By`/`Install Reason` (those only exist for `-Qi`).
* Description only (simple, single target, piped, no `COLUMNS` exported):
`pacman -Qi -- bash | sed -n 's/^Description *: //p'`.
* Robust version (any number of targets, wrapped lines joined, field split at the first colon) is
`lib.sh: pm_field -Qi|-Si Field target...` -> `name<TAB>value`:
```bash
pm_field() { local op=$1 field=$2; shift 2
LC_ALL=C COLUMNS=0 pacman "$op" -- "$@" 2>/dev/null | awk -v f="$field" '
function flush() { if (name != "") print name "\t" val; name = ""; val = ""; infield = 0 }
/^[ \t]*$/ { flush(); next }
/^[^ \t]/ { infield = 0; i = index($0, ":"); k = substr($0, 1, i-1); sub(/[ \t]+$/, "", k)
v = substr($0, i+1); sub(/^[ \t]+/, "", v)
if (k == "Name") name = v; else if (k == f) { val = v; infield = 1 }; next }
infield { sub(/^[ \t]+/, ""); val = val " " $0 }
END { flush() }'; }
```
`pm_field -Qi Description bash` -> `bash<TAB>The GNU Bourne Again shell`; also unaffected by `COLUMNS=20`
(verified: raw `COLUMNS=20 pacman -Qi bash` does wrap).
* Full dump = the raw command output, never wrapped when `COLUMNS=0` or unset and stdout is not a tty
(wrapping is driven by the `COLUMNS` env var, not by a real tty: `stty cols 100` + pipe did not wrap, `COLUMNS=80` +
pipe did). `Optional Deps` is the exception: one entry per line (continuation lines are *new entries*, not wraps):
```
Optional Deps : diffutils: for pacdiff
fakeroot: for checkupdates
```
* Missing target: `error: package 'x' was not found` on stderr, exit 1, other targets still printed.
## 4. Installed reverse dependencies
`pacman -Qi` fields (names only, no versions, two-space separated, `None` when empty; computed over installed
packages and already resolved through provides, e.g. `bash` is listed as a dependent of `readline` although it
depends on `libreadline.so=8-64`):
```
$ pacman -Qi bash | grep -E '^(Required By|Optional For)'
Required By : audit base bzip2 ca-certificates-utils device-mapper e2fsprogs gawk ...
Optional For : ncurses pcre2 tzdata
```
```bash
pm_required_by() { pm_field -Qi 'Required By' "$1" | cut -f2- | tr -s ' ' '\n' | grep -vxE 'None|' | sort -u; }
pm_optional_for() { pm_field -Qi 'Optional For' "$1" | cut -f2- | tr -s ' ' '\n' | grep -vxE 'None|' | sort -u; }
```
Proven: `pm_required_by su-dummy-b` -> `su-dummy-a`; `pm_required_by su-dummy-a` -> empty;
`pm_optional_for bash` -> `ncurses pcre2 tzdata`; `pm_required_by glibc | wc -l` -> 111 (a 1021-char line).
Note `-Si` does not have these fields; for the candidate, reverse deps = the installed ones.
## 5. Recursive dependency closure restricted to installed packages
Premise check: **`pacman -Qq`/`-Qi`/`-Q` DO resolve provides and version-constrained dependency strings in
pacman 7.1** (they use the satisfier lookup), so no special handling is needed on this version:
```
$ pacman -Qq sh -> bash (exit 0)
$ pacman -Qq 'glibc>=2.38' -> glibc (exit 0)
$ pacman -Qq libreadline.so=8-64 -> readline (exit 0)
$ pacman -Qq 'glibc>=99' -> error: package 'glibc>=99' was not found (exit 1)
$ pacman -T sh ; echo $? -> (nothing) 0 ; pacman -T nonexist -> "nonexist", exit 127
$ pacman -Qqs '^sh$' -> bash (-Qs also searches provides, but it is a regex search; do not use)
```
(Unquoted `>=` is a shell redirect, always quote dependency strings. I did not verify older pacman releases, so
`pm_closure` below does not rely on this.)
`pactree` (pacman-contrib, **absent** from `latest` and `base-devel`): after installing it,
`pactree -l -u bash` prints dependency strings, not names:
```
$ pactree -l -u bash
bash
readline
glibc
linux-api-headers>=4.10
tzdata
filesystem
iana-etc
libncursesw.so=6-64 <- provided name, the package "ncurses" itself never appears
libgcc
libstdc++
$ pactree -l -u pacman | wc -l -> 108 (contains libcrypt.so=2-64, libp11-kit=0.26.5-1, ca-certificates-utils>=20181109-3, ...)
```
So to use it you must resolve every line: `pactree -l -u P | xargs -r pacman -Qq -- | sort -u` (works on 7.1).
`pactree -r -l -u P` is the reverse closure. `pactree -l -u nonexist` -> `error: package 'nonexist' not found`, exit 1.
**Pure-pacman implementation** (`lib.sh: pm_closure`): a single `pacman -Qi` dump (all installed packages, ~10 ms)
parsed by one awk process that builds `name`, `Provides` -> provider map, `Depends On`, `Required By`,
`Optional For`, then BFS. A dependency string `d` is resolved as: strip the constraint (`sub(/[<>=].*/,"")`);
if it is a real installed package use it; otherwise use every installed package whose `Provides` has that base
name. Usage:
```
pm_closure bash # forward closure, roots excluded, sorted, one real name per line
pm_closure -r glibc # reverse closure via "Required By" (add -o to follow "Optional For" too)
pm_closure sh # roots may be provided names -> same as bash
```
Sample: `pm_closure bash` -> `filesystem glibc iana-etc libgcc libstdc++ linux-api-headers ncurses readline tzdata`
(9 packages; pactree printed 10 strings, including `libncursesw.so=6-64` for `ncurses`).
Proof (`checks.sh`, all PASS): for `bash` (9), `pacman` (107) and `su-dummy-a` (1), the output equals
`pactree -l -u P | xargs -r pacman -Qq -- | sort -u` minus the root; reverse closures of `glibc` and `bash` equal
`pactree -r -l -u`. If several installed packages provide the same name the closure is a superset of pactree's
single pick (does not happen in the base image). Optional deps are excluded (as in pactree's default).
## 6. Per-run exclusion
Both forms work (verified, `--noconfirm`, fixture):
```
pacman -Su --noconfirm --ignore su-dummy-a,su-dummy-c # comma separated
pacman -Su --noconfirm --ignore su-dummy-a --ignore su-dummy-c # repeated
pacman -Su --noconfirm --ignore 'su-dummy-[ab]' # globs work, like IgnorePkg
```
Result: `exit=0`, only `su-dummy-b` upgraded; the warning goes to **stderr**:
```
warning: su-dummy-a: ignoring package upgrade (1.0-1 => 2.0-1)
warning: su-dummy-c: ignoring package upgrade (1.0-1 => 2.0-1)
```
Ignoring everything: stdout `:: Starting full system upgrade...` + ` there is nothing to do`, warnings on stderr, exit 0.
* `pacman -Qu --ignore x` is **invalid** (`error: invalid option '--ignore'`, exit 1): `[ignored]` marks only
`IgnorePkg`/`IgnoreGroup` from the configuration. Effective list wherever it was configured:
`pacman-conf IgnorePkg` (one pattern per line; `IgnorePkg = glib2 hwdata` -> two lines).
* Include placement: `Include = /etc/pacman.d/ignorepkg` must be inside `[options]`. Inserted right after the first
header with `sed -i '0,/^\[options\]/s||[options]\nInclude = /etc/pacman.d/ignorepkg|' /etc/pacman.conf`
(that is what `fixture.sh` does). Appended at EOF of a stock config (last section `[extra]`):
`warning: config file /etc/pacman.d/ignorepkg, line 1: directive 'IgnorePkg' in section 'extra' not recognized.`
and the package is still upgraded. After writing, verify with `pacman-conf IgnorePkg`.
* **Dependency trap** (`FIXTURE_STRICT_DEP=1`: `su-dummy-a` 2.0 needs `su-dummy-b>=2.0`), `--ignore su-dummy-b`
(or `IgnorePkg = su-dummy-b`):
```
warning: su-dummy-b: ignoring package upgrade (1.0-1 => 2.0-1)
warning: cannot resolve "su-dummy-b>=2.0", a dependency of "su-dummy-a"
:: The following package cannot be upgraded due to unresolvable dependencies:
su-dummy-a
:: Do you want to skip the above package for this upgrade? [y/N]
:: unable to satisfy dependency 'su-dummy-b>=2.0' required by su-dummy-a
error: failed to prepare transaction (could not satisfy dependencies) exit=1
```
With `--noconfirm` the default answer is N: the whole run aborts and **nothing** (not even `su-dummy-c`) is
upgraded. Same for excluding a *new dependency* (`--ignore su-dummy-new`). Pre-check without root/side effects:
`pacman -Sup --noconfirm --ignore su-dummy-b --print-format '%r/%n %v' </dev/null` -> exit 1, stdout
`:: unable to satisfy dependency ...`, stderr `error: failed to prepare transaction ...`
(`lib.sh: pm_plan [skip...]`; exit 0 and an empty list when everything is ignored).
`--ask 16` (verified) answers that prompt "yes": `pacman -Su --noconfirm --ask 16 --ignore su-dummy-b` exits 0, upgrades
only `su-dummy-c` and silently leaves `su-dummy-a` behind. Probably not what a skeptical user wants; at most offer it
as an explicit choice after showing the `pm_plan` failure.
## 7. Non-interactive upgrade, exit codes
```
$ pacman -Syu --noconfirm; echo $? # upgrades; prints the ":: Proceed with installation? [Y/n]" line but auto-answers
0
$ pacman -Syu --noconfirm # nothing left
:: Synchronizing package databases...
su-dummy downloading...
:: Starting full system upgrade...
there is nothing to do <- leading space; exit 0
$ pacman -Qu; echo $? # nothing upgradable: no output
1
```
| situation | exit | message |
|-----------|------|---------|
| upgrade ok / nothing to do | 0 | ` there is nothing to do` (stdout) |
| `pacman -Qu` nothing upgradable | **1** | (empty) |
| not root (`-Sy`, `-Su`, `-Rns`) | 1 | `error: you cannot perform this operation unless you are root.` |
| db locked (`/var/lib/pacman/db.lck`) | 1 | `error: failed to synchronize all databases (unable to lock database)` (`-Qu`/`-Qi` still work, exit 0) |
| excluded dep unsatisfiable | 1 | see section 6 |
| `checkupdates` | 0 updates / 2 none / 1 error | |
`--noconfirm` answers every question with its default: install prompts are Y, but "skip unresolvable package?",
conflict removal and HoldPkg prompts are N (they abort with exit 1).
Messages are split over stdout and stderr (`warning:`/`error:` -> stderr, `:: unable to satisfy ...` -> stdout),
so capture both.
## 8. Purge
```
$ pacman -Rns --noconfirm su-dummy-a ; echo $? # a explicit, b installed --asdeps and only needed by a
removing su-dummy-a...
removing su-dummy-b... # -s also removed the now-unneeded dependency
0
$ pacman -Rns --noconfirm su-dummy-b ; echo $? # required by a
checking dependencies... (stdout)
:: removing su-dummy-b breaks dependency 'su-dummy-b' required by su-dummy-a
error: failed to prepare transaction (could not satisfy dependencies) (stderr)
1 # nothing removed
$ pacman -Rns --noconfirm nope ; echo $? -> error: target not found: nope 1
$ pacman -Rns --noconfirm su-dummy-c nope -> same error, exit 1, su-dummy-c NOT removed (all or nothing)
$ pacman -Rns --noconfirm su-dummy-b su-dummy-a -> 0 (order irrelevant, both removed)
$ pacman -Rns --noconfirm pacman -> breaks dependency 'pacman' required by base, exit 1
$ pacman -Rdd --noconfirm pacman -> ":: HoldPkg was found in target list. Do you want to continue? [y/N]" exit 1
```
`-R` without `-s` leaves the dependency as an orphan (`pacman -Qdtq` -> `su-dummy-b`).
## 9. Base image facts
| item | `archlinux:latest` (= `archlinux:base`, same manifest digest) | `archlinux:base-devel` |
|------|-----|-----|
| exists | yes; also `archlinux:multilib-devel` | yes (pulled for this test, 950 MB vs 399 MB) |
| bash | 5.3.20 | 5.3.20 |
| pacman | 7.1.0 (libalpm 16.0.1) | 7.1.0 |
| installed packages | 137 | 170 |
| sudo | **no** | yes (`/etc/sudoers` has only `root ALL=(ALL:ALL) ALL`) |
| python3 | **no** (core/python 3.14.7-1, 13.5 MB download) | yes |
| fakeroot | **no** (core/fakeroot 1:1.37.2-3, 77 KB) | yes |
| makepkg | yes (`/usr/sbin/makepkg`) but unusable without fakeroot | yes, works |
| gcc/make/debugedit | no | yes |
| pacman-contrib (`checkupdates`, `pactree`) | no (extra/pacman-contrib 1.13.1-1) | no |
| bats / git | no / no | no / no |
| su, runuser, bsdtar, repo-add, pacman-conf, vercmp, curl, awk(gawk) | yes | yes |
| default `$LANG` | `C.UTF-8` (set `LC_ALL=C` anyway) | same |
| sync DBs | **absent** until `pacman -Sy` | absent |
`which` is not installed; use `command -v`. All binaries live in `/usr/bin` (`/usr/sbin` is a symlink).
**bats**: `extra/bats 1.14.0-1` (installs `parallel`, `perl`, `db5.3` as deps). After `pacman -Sy`:
`pacman -S --noconfirm bats` took 6.3 s, `bats --version` -> `Bats 1.14.0`, a smoke test printed `1..1` / `ok 1 hello`.
Without a prior `-Sy`: `pacman -Si bats` -> `error: package 'bats' was not found`.
(Installing straight after `-Sy` works today; the proper form on a stale image is `pacman -Syu` first.)
**makepkg as root** (exit 10):
```
==> ERROR: Running makepkg as root is not allowed as it can cause permanent,
catastrophic damage to your system.
```
(`--asroot` no longer exists: `makepkg: invalid option '--asroot'`.) Recipe, verified in both images
(on `latest` first `pacman -Sy --noconfirm fakeroot`; the base-devel image already has it):
```
useradd -m builder
runuser -u builder -- bash -c 'cd /home/builder/pkg && makepkg --force --nodeps --noconfirm' # exit 0
su -s /bin/bash builder -c 'cd /home/builder/pkg && makepkg --force --nodeps' # also works
sudo -u builder ... # works in base-devel (verified); sudo does not exist in archlinux:latest
```
Use `PKGDEST=/dir` (writable by the build user!) to choose where the `.pkg.tar.zst` goes and
`options=('!debug' '!strip')` in the PKGBUILD for `arch=('any')` payloads: without it makepkg 7 aborts on `latest` with
`==> ERROR: Cannot find the debugedit binary required for including source files in debug packages.`
(debugedit is only in base-devel). `--nodeps` skips the dependency check (no sudo needed).
## 10. E2E fixture (`discovery/pacman/fixture.sh`)
```
docker run --rm -i -v "$PWD/discovery/pacman:/d:ro" archlinux:latest bash /d/fixture.sh
fixture: builder=tar isolate=0 repo=/srv/su-repo
fixture: installed: su-dummy-a 1.0-1;su-dummy-b 1.0-1;su-dummy-c 1.0-1;
fixture: repo list: core extra su-dummy
exit 0
```
What it does (root, inside the container):
1. Builds `su-dummy-{a,b,c}` at 1.0-1 (to install) and 2.0-1 (to offer). `su-dummy-a` has `depend = su-dummy-b`.
Each ships `/usr/share/su-dummy/<name>/VERSION` (contains the version) so tests can check an upgrade really
happened. Descriptions: `Skeptical-updater dummy package A` (B has "(dependency of A)", C "(independent)").
2. **Default builder = `tar`**: hand-made `.pkg.tar.zst` containing only `.PKGINFO` + payload
(`bsdtar --zstd -cf ... .PKGINFO usr`). Verified that `pacman -U`, `repo-add`, `-Qi`, `-Qk` and `-Syu` accept
it without `.MTREE`/`.BUILDINFO`. No network, no fakeroot, no build user.
`FIXTURE_BUILDER=makepkg` uses real makepkg as user `su-builder` via `runuser` (installs fakeroot with
`pacman -Sy fakeroot` if missing, so network; sets `PKGDEST`, `SOURCE_DATE_EPOCH`, `options=('!debug' '!strip')`).
Both verified on `latest` and `base-devel`; both produce identical `-Qu` results.
3. `repo-add` creates `/srv/su-repo/su-dummy.db.tar.gz` (+`.db` symlink) containing the 2.0 packages only;
appends to `/etc/pacman.conf`:
```
[su-dummy]
SigLevel = Optional TrustAll
Server = file:///srv/su-repo
```
4. Installs the 1.0 packages with `pacman -U`, then `pacman -D --asdeps su-dummy-b` (a and c explicit, b "Installed as
a dependency for another package", so `pacman -Rns su-dummy-a` removes b too).
5. Creates an empty `/etc/pacman.d/ignorepkg` and inserts `Include = /etc/pacman.d/ignorepkg` after the first
`[options]` header (pman layout).
6. Does **not** sync (unless `FIXTURE_SYNC=1`), so the tool under test performs the refresh itself.
Result after `pacman -Sy`:
```
$ pacman -Qu | tail -3
su-dummy-a 1.0-1 -> 2.0-1
su-dummy-b 1.0-1 -> 2.0-1
su-dummy-c 1.0-1 -> 2.0-1
$ pacman -Sl | grep dummy
su-dummy su-dummy-a 2.0-1 [installed: 1.0-1]
```
Knobs: `FIXTURE_ISOLATE=1` comments out `[core]`/`[extra]` so `-Qu` lists **exactly** the 3 dummies, works offline
and is deterministic (default mode additionally lists whatever real upgrades the image has, 6 today; filter with
`grep '^su-dummy-'`); `FIXTURE_STRICT_DEP=1` makes a-2.0 depend on `su-dummy-b>=2.0` (the section 6 trap);
`FIXTURE_REPO`, `FIXTURE_SYNC`. The file can be `source`d: it defines `fx_build_tar <outdir> <name> <ver> <desc> [dep...]`
and does not enable `set -e` in the caller (used to publish extra packages, e.g. the `su-dummy-new` and two-repo
experiments above).
Typical flow in a test: `FIXTURE_ISOLATE=1 bash fixture.sh; pacman -Sy; <tool>; pacman -Q su-dummy-a` ->
`su-dummy-a 2.0-1`, `cat /usr/share/su-dummy/su-dummy-a/VERSION` -> `2.0`.
Re-running the fixture in the same container is safe (verified): `[su-dummy]` and the `Include` are not duplicated,
the repo is rebuilt, and if the packages were already upgraded to 2.0 they are *downgraded* back to 1.0 by `pacman -U`
(so it also works as a reset between test cases).
## 11. Timings (this host, fast CDN, three runs agree within 0.05 s)
| step | time |
|------|------|
| container start (`docker run --rm archlinux:latest true`) | 0.30 s |
| `pacman -Sy` cold / warm | 0.21-0.25 s / 0.12 s |
| fixture (tar builder, includes 3 installs + repo-add) | 0.23 s |
| fixture (makepkg builder, includes `pacman -Sy fakeroot`, 6 makepkg runs) | 7.3-7.7 s (one cold run: 12.9 s) |
| `pm_upgradable` (`-Sl` + `-Qu` + awk) | 0.15 s |
| `pm_closure pacman` (107 packages) | 0.02 s |
| `pacman -S --noconfirm bats` | 6.3 s |
| `pacman -S pacman-contrib` | 0.4 s |
| whole `checks.sh` incl. container start, contrib install and a full real `-Su` | ~5-8 s |
| image pull `archlinux:latest` | ~10 s (399 MB); `base-devel` 950 MB |
## 12. pman mapping and bugs found
pman (`/home/bryanpedini/projects/sources/pman/pman.sh`) is a bash `case` over verbs; it prepends `sudo` when not
root and the verb needs it (`config`, `install`, `update`, `upgrade`, `remove`, `purge`, `clean`, `provides`,
`providefiles`, `reflector`, `ignore`, `unignore` when `$UID != 0`; it exits 1 if sudo is absent, as in the base image
when not root: verified `pman upgrade` as an unprivileged user in `archlinux:latest` -> exit 1; in that container the
`sudo command needed but not found` message itself was swallowed by `echo ... > /dev/stderr` failing with
`Permission denied`, a side effect of `runuser` + docker's root-owned stderr pipe).
| pman verb | runs | skeptical-updater uses |
|-----------|------|------------------------|
| `update` | `pacman -Sy` then prints `N packages are available for update` (`pacman -Qu \| wc -l`, **counts `[ignored]` rows**) | refresh |
| `upgradable` | `pacman -Qu` | list |
| `localinfo` / `info` | `pacman -Qi` / `-Si` | info (`info` shows both repos if duplicated) |
| `upgrade` | `pacman -Syu` + extra args (`pman upgrade --noconfirm --ignore a,b` works, verified) | apply (prefer `-Su` after a refresh) |
| `purge` / `remove` | `pacman -Rns` / `-Rs` | purge |
| `ignored` | `echo "$(sed 's/IgnorePkg = //' /etc/pacman.d/ignorepkg \| sort)"` | read |
| `ignore p...` | appends `IgnorePkg = p` to `/etc/pacman.d/ignorepkg` | write |
| `unignore p...` | `sed -i "/IgnorePkg = p/d"` | write |
Verified end to end with the fixture as root: `pman update` -> `3 packages are available for update`;
`pman ignore su-dummy-c` + `pman upgradable` -> `su-dummy-c 1.0-1 -> 2.0-1 [ignored]`; `pman upgrade --noconfirm`
printed `warning: su-dummy-c: ignoring package upgrade (1.0-1 => 2.0-1)` and upgraded a and b (exit 0);
`pman purge --noconfirm su-dummy-a` removed a and b.
pman bugs (verified; relevant if the tool reuses `/etc/pacman.d/ignorepkg`):
* `pman ignore foo` after `pman ignore barfoo` prints `foo is already ignored, skipping...` (the check is
`grep -e "$pkg$"`, an unanchored suffix match) and `foo` is never added.
* `pman unignore su-dummy` deletes the line `IgnorePkg = su-dummy-c` (`sed "/IgnorePkg = su-dummy/d"` is an
unanchored prefix/substring match); regex characters in names are not escaped either.
* `ignored`/`ignore`/`unignore` assume one package per line in `IgnorePkg = <pkg>` form and never check that
`pacman.conf` actually includes the file in `[options]` (silently ineffective, section 6).
* The tool should read the effective list with `pacman-conf IgnorePkg` and write with anchored matches
(`grep -qxF "IgnorePkg = $pkg"`, `sed -i "/^IgnorePkg = ${pkg}\$/d"` after escaping).
discovery/pacman/checks.sh
+80
View File
@@ -0,0 +1,80 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# Executable proof for discovery/pacman.md. Run inside archlinux:latest:
# docker run --rm -i -v "$PWD/discovery/pacman:/d:ro" archlinux:latest bash /d/checks.sh
# Needs network (real repos + pacman-contrib for the pactree comparison).
export LC_ALL=C
fails=0
ok() { printf 'PASS %s\n' "$*"; }
bad() { printf 'FAIL %s\n' "$*"; fails=$((fails+1)); }
eq() { # eq <desc> <expected> <actual>
if [ "$2" = "$3" ]; then ok "$1"; else bad "$1"; printf ' expected: %q\n actual: %q\n' "$2" "$3"; fi
}
d=$(dirname "$(readlink -f "$0")")
bash "$d/fixture.sh" 2>&1 | grep -v 'database file for'
. "$d/lib.sh"
echo "### 1/2 refresh + upgradable"
pm_refresh >/dev/null 2>&1; eq "pm_refresh exit" 0 $?
pm_upgradable | grep '^su-dummy' > /tmp/up.tsv
eq "upgradable su-dummy rows" $'su-dummy-a\t1.0-1\t2.0-1\tsu-dummy\t0\nsu-dummy-b\t1.0-1\t2.0-1\tsu-dummy\t0\nsu-dummy-c\t1.0-1\t2.0-1\tsu-dummy\t0' "$(cat /tmp/up.tsv)"
pm_upgradable | head -3 | sed 's/^/ /'
echo 'IgnorePkg = su-dummy-c' > /etc/pacman.d/ignorepkg
eq "ignored flag" $'su-dummy-c\t1.0-1\t2.0-1\tsu-dummy\t1' "$(pm_upgradable | grep '^su-dummy-c')"
eq "pacman-conf IgnorePkg" su-dummy-c "$(pm_ignored_patterns)"
: > /etc/pacman.d/ignorepkg
echo "### 3 descriptions"
eq "local desc" $'bash\tThe GNU Bourne Again shell' "$(pm_desc_local bash)"
eq "cand desc" $'su-dummy-a\tSkeptical-updater dummy package A' "$(pm_desc_cand su-dummy/su-dummy-a)"
eq "desc wrapped input is unwrapped" $'bash\tThe GNU Bourne Again shell' "$(COLUMNS=20 pm_desc_local bash)"
eq "desc via raw COLUMNS=20 wraps" yes "$( [ "$(COLUMNS=20 pacman -Qi bash | grep -c '^ \{10,\}')" -gt 0 ] && echo yes || echo no )"
echo "### 4 reverse deps"
eq "required-by su-dummy-b" su-dummy-a "$(pm_required_by su-dummy-b)"
eq "required-by su-dummy-a (None => empty)" "" "$(pm_required_by su-dummy-a)"
eq "required-by readline (soname dep)" "bash" "$(pm_required_by readline | grep -x bash)"
eq "optional-for bash" "ncurses pcre2 tzdata" "$(pm_optional_for bash | tr '\n' ' ' | sed 's/ $//')"
echo "### 5 closure vs pactree"
pacman -S --noconfirm --needed pacman-contrib fakeroot >/dev/null 2>&1 # fakeroot only for checkupdates
for p in bash pacman su-dummy-a; do
mine=$(pm_closure "$p" | tr '\n' ' ')
ref=$(pactree -l -u "$p" | xargs -r pacman -Qq -- 2>/dev/null | sort -u | grep -vx "$p" | tr '\n' ' ')
eq "closure($p) == pactree|resolve" "$ref" "$mine"
printf ' %s -> %s packages\n' "$p" "$(echo $mine | wc -w)"
done
eq "closure(sh) resolves provider" "$(pm_closure bash)" "$(pm_closure sh)"
eq "reverse closure(su-dummy-b)" su-dummy-a "$(pm_closure -r su-dummy-b)"
for p in glibc bash; do
mine=$(pm_closure -r "$p" | tr '\n' ' ')
ref=$(pactree -r -l -u "$p" | xargs -r pacman -Qq -- 2>/dev/null | sort -u | grep -vx "$p" | tr '\n' ' ')
eq "reverse closure($p) == pactree -r" "$ref" "$mine"
done
echo "### 6 plan / ignore / apply"
eq "plan all" $'su-dummy/su-dummy-b 2.0-1\nsu-dummy/su-dummy-a 2.0-1\nsu-dummy/su-dummy-c 2.0-1' "$(pm_plan | grep su-dummy)"
eq "plan skip a,c" $'su-dummy/su-dummy-b 2.0-1' "$(pm_plan su-dummy-a su-dummy-c | grep su-dummy)"
pm_apply su-dummy-a,su-dummy-c >/dev/null 2>&1; eq "apply (comma list passed as one arg) exit" 0 $?
eq "after partial apply" $'su-dummy-a 1.0-1\nsu-dummy-b 2.0-1\nsu-dummy-c 1.0-1' "$(pacman -Q su-dummy-a su-dummy-b su-dummy-c)"
pm_apply su-dummy-a >/dev/null 2>&1; pm_apply >/dev/null 2>&1
eq "after full apply" $'su-dummy-a 2.0-1\nsu-dummy-b 2.0-1\nsu-dummy-c 2.0-1' "$(pacman -Q su-dummy-a su-dummy-b su-dummy-c)"
echo "### 7 nothing to do / exit codes"
pm_apply >/dev/null 2>&1 # real repos: upgrade everything so nothing is left
pacman -Qu >/dev/null; eq "pacman -Qu exit when fully upgraded" 1 $?
out=$(pacman -Su --noconfirm 2>&1); rc=$?
eq "pacman -Su nothing to do: exit" 0 "$rc"
eq "pacman -Su nothing to do: message" $':: Starting full system upgrade...\n there is nothing to do' "$out"
checkupdates >/dev/null 2>&1; eq "checkupdates exit when nothing to do" 2 $?
echo "### 8 purge"
pm_purge su-dummy-b >/dev/null 2>&1; eq "purge b (needed by a) exit" 1 $?
pm_purge su-dummy-a >/dev/null 2>&1; eq "purge a exit" 0 $?
pacman -Q su-dummy-b >/dev/null 2>&1; eq "b removed with a (was --asdeps)" 1 $?
echo
[ "$fails" -eq 0 ] && echo "ALL CHECKS PASSED" || echo "$fails CHECK(S) FAILED"
exit "$fails"
discovery/pacman/fixture.sh
+211
View File
@@ -0,0 +1,211 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# Deterministic pacman fixture for skeptical-updater E2E tests.
#
# Creates three dummy packages installed at 1.0 and a local pacman repo
# ([su-dummy], file:///srv/su-repo) that offers them at 2.0:
#
# su-dummy-a depends=(su-dummy-b) installed explicitly
# su-dummy-b installed as a dependency (--asdeps)
# su-dummy-c installed explicitly
#
# It also pre-wires /etc/pacman.d/ignorepkg (empty) and the matching
# "Include" line inside the [options] section of /etc/pacman.conf, i.e. the
# same layout that pman expects (IgnorePkg = <pkg> lines).
#
# Run as root inside an Arch container:
# docker run --rm -i -v "$PWD/discovery/pacman:/d:ro" archlinux:latest bash /d/fixture.sh
#
# Environment (all optional):
# FIXTURE_BUILDER tar (default) | makepkg
# tar : hand-built .pkg.tar.zst (.PKGINFO + bsdtar). No network, no
# fakeroot, no build user. ~0.1 s.
# makepkg : real makepkg run as the unprivileged user "su-builder" via
# runuser. Needs fakeroot (installed with `pacman -Sy fakeroot`
# if missing, so it needs network). Slower.
# FIXTURE_ISOLATE 0 (default) | 1
# 1 comments out every repo section except [su-dummy], so `pacman -Qu`
# reports EXACTLY the three dummy packages (no real upgrades, no network
# needed after the fixture is built).
# FIXTURE_STRICT_DEP 0 (default) | 1
# 1 makes su-dummy-a 2.0 depend on "su-dummy-b>=2.0" (instead of plain
# "su-dummy-b"), so excluding su-dummy-b from an upgrade (--ignore /
# IgnorePkg) while upgrading su-dummy-a fails with unsatisfied deps.
# FIXTURE_REPO repo directory (default /srv/su-repo)
# FIXTURE_SYNC 0 (default) | 1 -> run `pacman -Sy` at the end
#
# The fixture deliberately does NOT sync by default: the tool under test is
# expected to perform the refresh itself (pacman -Sy), after which
# `pacman -Qu` lists su-dummy-{a,b,c} (1.0-1 -> 2.0-1).
export LC_ALL=C
FIXTURE_BUILDER=${FIXTURE_BUILDER:-tar}
FIXTURE_ISOLATE=${FIXTURE_ISOLATE:-0}
FIXTURE_STRICT_DEP=${FIXTURE_STRICT_DEP:-0}
FIXTURE_REPO=${FIXTURE_REPO:-/srv/su-repo}
FIXTURE_SYNC=${FIXTURE_SYNC:-0}
FIXTURE_REPO_NAME=su-dummy
FIXTURE_EPOCH=1700000000 # fixed build date => reproducible tarballs
fx_log() { printf 'fixture: %s\n' "$*" >&2; }
fx_die() { fx_log "ERROR: $*"; exit 1; }
# pacman wrapper: stdout dropped, the harmless "database file for X does not
# exist" warnings (fresh image, no sync yet) filtered, real errors kept, exit
# status preserved.
fx_pacman() {
local rc=0
pacman "$@" 2>&1 >/dev/null | { grep -v "^warning: database file for" >&2 || true; } || rc=$?
return $rc
}
# fx_build_tar <outdir> <name> <pkgver> <pkgdesc> [depend...]
# Hand-built package: only a .PKGINFO and the payload are required by pacman -U
# and repo-add (no .MTREE / .BUILDINFO needed; `pacman -Qk` is happy too).
fx_build_tar() {
local out=$1 name=$2 ver=$3 desc=$4; shift 4
local w payload
w=$(mktemp -d)
payload="usr/share/su-dummy/$name"
mkdir -p "$w/$payload"
printf '%s\n' "$ver" >"$w/$payload/VERSION"
{
printf 'pkgname = %s\n' "$name"
printf 'pkgbase = %s\n' "$name"
printf 'pkgver = %s-1\n' "$ver"
printf 'pkgdesc = %s\n' "$desc"
printf 'url = https://example.invalid/su-dummy\n'
printf 'builddate = %s\n' "$FIXTURE_EPOCH"
printf 'packager = su-fixture <su-fixture@example.invalid>\n'
printf 'size = %s\n' "$(wc -c <"$w/$payload/VERSION")"
printf 'arch = any\n'
printf 'license = custom\n'
local d
for d in "$@"; do printf 'depend = %s\n' "$d"; done
} >"$w/.PKGINFO"
(cd "$w" && bsdtar --zstd --uid 0 --gid 0 --uname root --gname root \
-cf "$out/$name-$ver-1-any.pkg.tar.zst" .PKGINFO usr)
rm -rf "$w"
}
# fx_build_makepkg <outdir> <name> <pkgver> <pkgdesc> [depend...]
# Real makepkg. makepkg refuses to run as root, so run it as an unprivileged
# user with `runuser -u` (no sudo needed; `su -s /bin/bash -c` also works).
fx_build_makepkg() {
local out=$1 name=$2 ver=$3 desc=$4; shift 4
local w depends="" d
for d in "$@"; do depends+="'$d' "; done
w=/home/su-builder/build/$name-$ver
mkdir -p "$w"
cat >"$w/PKGBUILD" <<EOF
pkgname=$name
pkgver=$ver
pkgrel=1
pkgdesc='$desc'
arch=('any')
url='https://example.invalid/su-dummy'
license=('custom')
options=('!debug' '!strip') # arch=any payload: no debugedit/binutils needed
depends=($depends)
package() {
install -Dm644 /dev/stdin "\$pkgdir/usr/share/su-dummy/\$pkgname/VERSION" <<<"\$pkgver"
}
EOF
chown -R su-builder: "$w"
runuser -u su-builder -- env \
PKGDEST="$out" SOURCE_DATE_EPOCH="$FIXTURE_EPOCH" \
PACKAGER='su-fixture <su-fixture@example.invalid>' \
bash -c "cd '$w' && makepkg --force --nodeps --noconfirm --nocolor >/dev/null 2>&1" \
|| { runuser -u su-builder -- bash -c "cd '$w' && makepkg --force --nodeps --noconfirm --nocolor" >&2; fx_die "makepkg failed for $name"; }
}
fx_prepare_makepkg() {
if ! command -v fakeroot >/dev/null; then
fx_log "makepkg builder: installing fakeroot (needs network)"
fx_pacman -Sy --noconfirm --needed fakeroot
fi
id su-builder >/dev/null 2>&1 || useradd --create-home su-builder
}
fx_build() { # fx_build <outdir> <name> <ver> <desc> [dep...]
case $FIXTURE_BUILDER in
tar) fx_build_tar "$@" ;;
makepkg) fx_build_makepkg "$@" ;;
*) fx_die "unknown FIXTURE_BUILDER=$FIXTURE_BUILDER" ;;
esac
}
fx_main() {
set -euo pipefail
[ "$(id -u)" -eq 0 ] || fx_die "must run as root"
local old new
old=$(mktemp -d); new=$FIXTURE_REPO
rm -rf "$FIXTURE_REPO"; mkdir -p "$FIXTURE_REPO"
chmod 755 "$old"
if [ "$FIXTURE_BUILDER" = makepkg ]; then
fx_prepare_makepkg
chown su-builder: "$old" "$new" # PKGDEST dirs must be writable by the build user
fi
# 1.0 packages (installed) and 2.0 packages (offered by the repo)
fx_build "$old" su-dummy-a 1.0 'Skeptical-updater dummy package A' su-dummy-b
fx_build "$old" su-dummy-b 1.0 'Skeptical-updater dummy package B (dependency of A)'
fx_build "$old" su-dummy-c 1.0 'Skeptical-updater dummy package C (independent)'
local a2_dep=su-dummy-b
[ "$FIXTURE_STRICT_DEP" = 1 ] && a2_dep='su-dummy-b>=2.0'
fx_build "$new" su-dummy-a 2.0 'Skeptical-updater dummy package A' "$a2_dep"
fx_build "$new" su-dummy-b 2.0 'Skeptical-updater dummy package B (dependency of A)'
fx_build "$new" su-dummy-c 2.0 'Skeptical-updater dummy package C (independent)'
# Local repository database (repo-add ships with pacman)
(cd "$FIXTURE_REPO" && repo-add --quiet "$FIXTURE_REPO_NAME.db.tar.gz" ./*.pkg.tar.zst)
chmod -R a+rX "$FIXTURE_REPO"; chmod a+rx /srv 2>/dev/null || true
# pacman.conf: register the repo (appended at the end => lowest priority)
if ! grep -q "^\[$FIXTURE_REPO_NAME\]" /etc/pacman.conf; then
{
printf '\n[%s]\n' "$FIXTURE_REPO_NAME"
printf 'SigLevel = Optional TrustAll\n'
printf 'Server = file://%s\n' "$FIXTURE_REPO"
} >>/etc/pacman.conf
fi
# pman-style ignore file, included from the [options] section
# (inserted right after the FIRST "[options]" header; appending at EOF would
# land in whatever section happens to be last).
: >/etc/pacman.d/ignorepkg
if ! grep -q '^Include *= */etc/pacman.d/ignorepkg' /etc/pacman.conf; then
sed -i '0,/^\[options\]/s||[options]\nInclude = /etc/pacman.d/ignorepkg|' /etc/pacman.conf
fi
if [ "$FIXTURE_ISOLATE" = 1 ]; then
# comment out all repos except [su-dummy]; keep [options] intact
awk -v keep="$FIXTURE_REPO_NAME" '
/^\[.*\][[:space:]]*$/ { sec=$0; sub(/^\[/,"",sec); sub(/\].*$/,"",sec); active = (sec=="options" || sec==keep) }
{ if (sec != "" && !active && $0 !~ /^[[:space:]]*#/ && $0 !~ /^[[:space:]]*$/) print "#" $0; else print }
' /etc/pacman.conf >/etc/pacman.conf.new && mv /etc/pacman.conf.new /etc/pacman.conf
fi
# Install the 1.0 packages: b as a dependency, a and c explicit.
fx_pacman -U --noconfirm "$old"/su-dummy-a-1.0-1-any.pkg.tar.zst \
"$old"/su-dummy-b-1.0-1-any.pkg.tar.zst \
"$old"/su-dummy-c-1.0-1-any.pkg.tar.zst
fx_pacman -D --asdeps su-dummy-b
rm -rf "$old"
if [ "$FIXTURE_SYNC" = 1 ]; then fx_pacman -Sy; fi
fx_log "builder=$FIXTURE_BUILDER isolate=$FIXTURE_ISOLATE repo=$FIXTURE_REPO"
fx_log "installed: $(pacman -Q su-dummy-a su-dummy-b su-dummy-c 2>/dev/null | tr '\n' ';')"
fx_log "repo list: $(pacman-conf --repo-list | tr '\n' ' ')"
}
# Run when executed; do nothing when sourced (so tests can reuse fx_build_tar etc.
# without inheriting `set -e`).
if [ "${BASH_SOURCE[0]}" = "$0" ]; then
fx_main "$@"
fi
discovery/pacman/lib.sh
+171
View File
@@ -0,0 +1,171 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# pacman helper functions for skeptical-updater (proven on pacman 7.1.0 /
# archlinux:latest by discovery/pacman/checks.sh). Source this file.
#
# Conventions
# * every pacman call runs with LC_ALL=C (stable field names / messages) and
# COLUMNS=0 (never wrap -Qi/-Si output, even if COLUMNS is exported).
# * PM_OPTS is an optional array of extra global pacman options, e.g.
# PM_OPTS=(--dbpath /tmp/checkdb) to work against a temporary sync DB.
# * nothing here needs pacman-contrib, sudo, python or fakeroot.
PM_OPTS=("${PM_OPTS[@]}")
_pm() { LC_ALL=C COLUMNS=0 pacman "${PM_OPTS[@]}" "$@"; }
# ---------------------------------------------------------------- refresh ---
# Refresh the real sync DBs (root). Safe as long as it is followed by -Su
# (never `pacman -S foo` after a bare -Sy: that is the partial-upgrade case).
pm_refresh() { LC_ALL=C pacman -Sy "$@"; }
# Refresh a THROWAWAY sync DB (root, no fakeroot/pacman-contrib needed) and
# point PM_OPTS at it; the system DB under /var/lib/pacman/sync is untouched.
# The temp dir must be world-traversable (mode 755) because the sandboxed
# download user "alpm" has to write into it, mktemp -d's 0700 is not enough.
pm_refresh_tmpdb() {
local db
db=$(mktemp -d /tmp/su-checkdb.XXXXXX) || return 1
chmod 755 "$db"
ln -s "$(pacman-conf DBPath)local" "$db/local" || return 1
LC_ALL=C pacman -Sy --dbpath "$db" --logfile /dev/null >/dev/null || return 1
PM_OPTS=(--dbpath "$db")
PM_TMPDB=$db
}
# ------------------------------------------------------------ upgradable ---
# name<TAB>oldversion<TAB>newversion<TAB>repo<TAB>ignored(0|1)
# -Qu line : "name old -> new" or "name old -> new [ignored]"
# -Sl line : "repo name version [installed[: oldver]]"
# The candidate repo is the FIRST repo (config order) that carries the name,
# which is what both `-Qu` and `-S name` pick (verified with a dup in 2 repos).
# Prints nothing (and returns 1) when nothing is upgradable, like `pacman -Qu`.
pm_upgradable() {
local out
out=$(awk '
FNR == NR { if (!($2 in repo)) repo[$2] = $1; next }
{ printf "%s\t%s\t%s\t%s\t%d\n", $1, $2, $4, repo[$1], ($5 == "[ignored]") }
' <(_pm -Sl 2>/dev/null) <(_pm -Qu 2>/dev/null))
[ -n "$out" ] || return 1
printf '%s\n' "$out"
}
# Effective IgnorePkg patterns (globs allowed), wherever they are configured
# (pacman.conf or an Include such as /etc/pacman.d/ignorepkg).
pm_ignored_patterns() { pacman-conf IgnorePkg; }
# ------------------------------------------------------------------ info ---
# pm_field <-Qi|-Si> <Field> <target>...
# -> "<name>\t<value>" per package; wrapped continuation lines are joined with
# one space. Use "repo/name" targets with -Si (a name in 2 repos prints twice).
# List fields keep pacman's two-space separators (split with `tr -s ' ' '\n'`);
# "None" is returned verbatim. Missing targets are skipped (the pacman error
# goes to /dev/null).
pm_field() {
local op=$1 field=$2; shift 2
_pm "$op" -- "$@" 2>/dev/null | awk -v f="$field" '
function flush() { if (name != "") print name "\t" val; name = ""; val = ""; infield = 0 }
/^[ \t]*$/ { flush(); next }
/^[^ \t]/ {
infield = 0
i = index($0, ":"); k = substr($0, 1, i - 1); sub(/[ \t]+$/, "", k)
v = substr($0, i + 1); sub(/^[ \t]+/, "", v)
if (k == "Name") name = v
else if (k == f) { val = v; infield = 1 }
next
}
infield { sub(/^[ \t]+/, ""); val = val " " $0 }
END { flush() }'
}
# One-line description of the installed package / of the upgrade candidate.
pm_desc_local() { pm_field -Qi Description "$@"; } # name<TAB>desc
pm_desc_cand() { pm_field -Si Description "$@"; } # args: repo/name
# Full dumps (verbatim pacman output, never wrapped).
pm_info_local() { _pm -Qi -- "$@"; }
pm_info_cand() { _pm -Si -- "$@"; } # args: repo/name
# Installed reverse dependencies as plain names, one per line (sorted).
pm_required_by() { pm_field -Qi 'Required By' "$1" | cut -f2- | tr -s ' ' '\n' | grep -vxE 'None|' | sort -u; }
pm_optional_for() { pm_field -Qi 'Optional For' "$1" | cut -f2- | tr -s ' ' '\n' | grep -vxE 'None|' | sort -u; }
# ------------------------------------------------------------ dependency ---
# pm_closure [-r] [-o] <pkg-or-dep>...
# Recursive closure over INSTALLED packages, one real package name per line,
# sorted, roots excluded.
# default : forward closure (Depends On, with provides/soname/version
# constraints resolved: `libfoo.so=1-64`, `glibc>=2.38`, `sh`)
# -r : reverse closure (Required By)
# -o : with -r also follow "Optional For"
# Roots may be package names or provided names. One `pacman -Qi` call,
# one awk process.
pm_closure() {
local mode=deps opt=0
while [ $# -gt 0 ]; do
case $1 in -r) mode=rdeps ;; -o) opt=1 ;; --) shift; break ;; *) break ;; esac
shift
done
_pm -Qi 2>/dev/null | awk -v roots="$*" -v mode="$mode" -v opt="$opt" '
function norm(s) { gsub(/[ \t]+/, " ", s); sub(/^ /, "", s); sub(/ $/, "", s); return (s == "None") ? "" : s }
function flush( c, a, i, p) {
if (name == "") return
real[name] = 1; dep[name] = norm(F["Depends On"]); rb[name] = norm(F["Required By"])
of[name] = norm(F["Optional For"]); pv[name] = norm(F["Provides"])
name = ""; delete F; cur = ""
}
function resolve(d, b) { b = d; sub(/[<>=].*/, "", b); if (b in real) return b; return prov[b] }
/^[ \t]*$/ { flush(); next }
/^[^ \t]/ { i = index($0, ":"); k = substr($0, 1, i - 1); sub(/[ \t]+$/, "", k)
v = substr($0, i + 1); sub(/^[ \t]+/, "", v); cur = k; F[k] = v
if (k == "Name") name = v; next }
{ sub(/^[ \t]+/, ""); F[cur] = F[cur] " " $0 }
END {
flush()
for (n in real) { c = split(pv[n], a, " "); for (i = 1; i <= c; i++) { p = a[i]; sub(/[<>=].*/, "", p); prov[p] = (p in prov) ? prov[p] " " n : n } }
nr = split(roots, r, " "); head = 0; tail = 0
for (i = 1; i <= nr; i++) { m = split(resolve(r[i]), a, " "); for (j = 1; j <= m; j++) if (!(a[j] in seen)) { seen[a[j]] = 1; isroot[a[j]] = 1; q[++tail] = a[j] } }
while (head < tail) {
n = q[++head]
if (mode == "deps") { lst = dep[n]; c = split(lst, a, " "); for (i = 1; i <= c; i++) { m = split(resolve(a[i]), b, " "); for (j = 1; j <= m; j++) if (!(b[j] in seen)) { seen[b[j]] = 1; q[++tail] = b[j] } } }
else { lst = rb[n] (opt ? " " of[n] : ""); c = split(lst, a, " "); for (i = 1; i <= c; i++) if (!(a[i] in seen)) { seen[a[i]] = 1; q[++tail] = a[i] } }
}
for (n in seen) if (!(n in isroot)) print n | "sort"
}'
}
# ------------------------------------------------------- apply / dry-run ---
# Join array elements with commas (for --ignore a,b,c).
_pm_join() { local IFS=,; printf '%s' "$*"; }
# pm_plan [pkg-to-skip...] -> "repo/name newversion" per package the upgrade
# would install (dependency order, includes NEW dependencies and respects
# IgnorePkg). Exit 1 when the exclusions make the transaction unsatisfiable.
# Needs a synced DB (run pm_refresh first); does not need root.
pm_plan() {
local ign=() out err rc
[ $# -gt 0 ] && ign=(--ignore "$(_pm_join "$@")")
err=$(mktemp)
out=$(_pm -Sup --noconfirm "${ign[@]}" --print-format '%r/%n %v' </dev/null 2>"$err"); rc=$?
if [ "$rc" -eq 0 ]; then [ -z "$out" ] || printf '%s\n' "$out"
else printf '%s\n' "$out" >&2; cat "$err" >&2; fi
rm -f "$err"; return "$rc"
}
# pm_apply [pkg-to-skip...] (root) non-interactive upgrade of the already
# refreshed DB. Use `-Su`, not `-Syu`, to apply exactly what was reviewed.
pm_apply() {
local ign=()
[ $# -gt 0 ] && ign=(--ignore "$(_pm_join "$@")")
LC_ALL=C pacman -Su --noconfirm "${ign[@]}"
}
# pm_purge <pkg>... (root) -Rns: also removes now-unneeded deps + config backups
pm_purge() { LC_ALL=C pacman -Rns --noconfirm -- "$@"; }
discovery/rpm.md
+706
View File
@@ -0,0 +1,706 @@
# RPM family discovery: DNF (AlmaLinux / Rocky / Fedora) and ZYPPER (openSUSE)
Everything below was run in throwaway `docker run --rm -i` containers (Docker 29.8.2 on the host, 2026-10-09).
All outputs are real; "exit=N" is the real exit status. All commands run with `LC_ALL=C`.
Companion files (all in `discovery/rpm/`, all proven on every image listed in section 0):
| file | purpose |
|---|---|
| `fixture.sh` | E2E fixture: builds 3 dummy RPMs (+ optional extras), local repo, 1.0 installed / 2.0 offered. dnf vs zypper auto-detected |
| `lib-rpm.sh` | the proven bash building blocks quoted in this document (`su_refresh`, `su_upgradable`, `su_describe`, `su_rdeps`, `su_closure`, `su_upgrade`, `su_plan`, `su_remove`, ...) |
| `proof.sh` | runs the fixture + every `lib-rpm.sh` function and asserts the results (43-53 PASS lines per image) |
Reproduce on any image: `docker run --rm -i -v <project>/discovery/rpm:/d:ro <image> bash /d/fixture.sh` or `... bash /d/proof.sh`.
---------------------------------------------------------------------------------------------------------
## 0. Verdict, images, and the surprises
### 0.1 Chosen commands (one line each)
| need | DNF (dnf4 and dnf5, `yum` is the same binary) | ZYPPER |
|---|---|---|
| refresh | `dnf -q --refresh --setopt=skip_if_unavailable=0 makecache >/dev/null` (exit 0/1) | `zypper --non-interactive --quiet refresh` (exit 0; 4 repo error; 3 unknown repo; 6 no repos) |
| upgradable list | `dnf -q check-update --setopt=skip_if_unavailable=0` (exit 100 = updates, 0 = none, 1 = error), parse 3 columns `name.arch evr repo`, old version from `rpm -qa` | `zypper --non-interactive --xmlout list-updates` (exit 0 always), parse `<update ... name edition edition-old arch>` + `<source alias>` |
| summary/description | `dnf -q repoquery --upgrades --latest-limit=1 --queryformat $'%{summary}\n%{description}\n' PKG`, fallback `rpm -q --qf '%{SUMMARY}\n%{DESCRIPTION}\n' PKG` | `zypper -q -n info PKG` (shows candidate, else installed), parse `Summary :` / indented `Description :` |
| installed reverse deps | pure rpm: provides + owned files joined against all REQUIRENAMEs (`su_rdeps`); == `dnf repoquery --installed --whatrequires` | same pure-rpm function (identical on both families) |
| recursive installed closure | pure rpm BFS `su_closure` (rpm -q REQUIRENAME + rpm -q --whatprovides); == dnf4 `repoquery --installed --requires --resolve --recursive`; dnf5 has no `--resolve` | same function |
| per-run exclusion | `dnf -y upgrade --exclude=a,b` (comma list; repeated flags also work; dnf4 and dnf5) | no `--exclude`. Chosen: private `ZYPP_CONF` with its own `locksfile.path` (`su_zypper_excluding`). Alternative with exact restore: snapshot/restore `/etc/zypp/locks` + trap (`su_zypper_excluding_snapshot`) |
| non-interactive upgrade | `dnf -y upgrade` | Leap/SLE: `zypper --non-interactive update`; Tumbleweed (os-release `ID=opensuse-tumbleweed`): `zypper --non-interactive dup` |
| remove + unneeded deps | `dnf -y remove PKG` (`clean_requirements_on_remove=1` is the default on dnf4 and dnf5) | `zypper --non-interactive remove --clean-deps PKG` |
| plan preview (new deps, removals, obsoletes) | `dnf --assumeno upgrade [--exclude=..]` + table parse (`su_plan_dnf`) | `zypper --non-interactive --xmlout update` or `dup` plus `--dry-run` (`<install-summary><to-upgrade>/<to-install>/<to-remove>`) |
### 0.2 Correct image names
| asked | result |
|---|---|
| `almalinux:9` | exists. AlmaLinux 9.8, **dnf 4.14.0**, rpm 4.16.1.3, bash 5.1.8 |
| `almalinux:10` | exists. AlmaLinux 10.2, **dnf 4.20.0 (NOT dnf5)**, rpm 4.19.1.1, bash 5.2.26 |
| `rockylinux:9` | exists but **stale**: Docker "official" library image = Rocky 9.3 created 2023-11-28 (96 pending upgrades on day one), dnf 4.14.0. Fresh equivalent: `rockylinux/rockylinux:9` or `quay.io/rockylinux/rockylinux:9` = Rocky 9.8 (same image id `686e4558d0a5`) |
| `rockylinux:10` | **does not exist**: `docker manifest inspect rockylinux:10` -> "no such manifest" (also `:10.0`, `:10.1`, `:10-minimal` missing). **Correct: `rockylinux/rockylinux:10`** (Docker Hub) **or `quay.io/rockylinux/rockylinux:10`** |
| quay vs Docker Hub Rocky 10 | **same image**: both resolve to id `sha256:0b5329d806d0...`, repo digest `sha256:827d37bc128288ccf160ee318bb3cb92d591164cb217e92f8bc61e3982ae1834`. Rocky 10.2, dnf 4.20.0, rpm 4.19.1.1. (`fixture.sh` also passes on the quay tag, 8 s.) |
| `opensuse/tumbleweed:latest` | openSUSE Tumbleweed (os-release `ID=opensuse-tumbleweed`, `VERSION_ID=20261007`), zypper 1.14.101, rpm 4.20.1, bash 5.3.20 |
| `opensuse/leap:latest` | **Leap 16.0** (`ID=opensuse-leap`), image created 2025-08-26, zypper 1.14.101, rpm 4.20.1, bash 5.2.37 |
| extra, for dnf5 only | `fedora:latest` = Fedora 44, **dnf5 5.4.3.0**, rpm 6.0.2 (pulled only to verify dnf5 syntax; not a target) |
### 0.3 Surprises that change the design
1. **EL10 is dnf4 (4.20.0), not dnf5.** AlmaLinux 10 has no `dnf5` package anywhere (BaseOS/AppStream/CRB/Extras/EPEL: `dnf -q --enablerepo='*' list --available dnf5` -> "No matching Packages"; only `microdnf 3.10.1`). Rocky 10 ships `dnf5 5.1.12` only in the *disabled* `devel` repo. So dnf5 is only met on Fedora (or a user-installed dnf5). The tool must support **dnf4 and dnf5 from one code path**; the only target images that run dnf5 are not in the requested list, so dnf5 was verified on `fedora:latest`.
2. `dnf5` silently ignores a dead repo (exit 0, `-q` hides the warning) unless `--setopt=skip_if_unavailable=0`. dnf4 errors by default (exit 1).
3. `rpm -qa --qf '[%{REQUIRENAME}\t%{NAME}\n]'` is **broken** (`error: incorrect format: array iterator used with different sized arrays`, ~50% of packages) on every rpm 4.16..6.0; the scalar tag must be written `%{=NAME}` inside `[...]`.
4. Missing tools in base images: no `awk`/`find`/`xargs`/`hostname`/`python3`/`xmllint` on Tumbleweed; no `find`/`xargs`/`python3`/`xmllint` on Leap; no `diff`/`cmp`/`ps`/`which`/`sudo` almost everywhere. All proven code uses only bash + rpm + sed/grep/tr/sort/join/cut/mktemp.
5. `rpm -q --whatrequires bash` returns **1** package on EL9 where `dnf repoquery --installed --whatrequires bash` and `su_rdeps bash` return **52** (file deps `/bin/sh`, `/usr/bin/bash`, sonames).
6. `zypper removelock` is not an undo (deletes *all* matching locks, leaves an empty `/etc/zypp/locks` file even if there was none).
7. `dnf list --upgrades` and (dnf4) `repoquery --upgrades` ignore the versionlock plugin; only `check-update` honours it on both majors.
---------------------------------------------------------------------------------------------------------
### 0.4 Base image facts (this is item 9 of the brief; repeated as a pointer in section 9)
| | alma:9 | alma:10 | rocky:9 (9.3 lib) | rocky 10 | tumbleweed | leap 16.0 |
|---|---|---|---|---|---|---|
| package mgr | dnf 4.14.0 | dnf 4.20.0 | dnf 4.14.0 | dnf 4.20.0 | zypper 1.14.101 | zypper 1.14.101 |
| `yum` | symlink -> `dnf-3` | `dnf-3` | `dnf-3` | `dnf-3` | absent | absent |
| rpm | 4.16.1.3 | 4.19.1.1 | 4.16.1.3 | 4.19.1.1 | 4.20.1 | 4.20.1 |
| bash | 5.1.8 | 5.2.26 | 5.1.8 | 5.2.26 | 5.3.20 | 5.2.37 |
| `sudo` | no (installable, baseos) | no | no | no | no (installable) | no (installable) |
| `su` | yes | **no** | yes | yes | yes | yes |
| `python3` | yes | yes | yes | yes | **no** | **no** |
| awk / find / xargs | yes | yes | yes | yes | **no / no / no** | awk yes, **find, xargs no** |
| xmllint | yes | yes | yes | yes | no | no |
| runs as | root | root | root | root | root | root |
`bats`:
* EL9/EL10 (Alma and Rocky): **not in BaseOS/AppStream/CRB**; needs EPEL: `dnf -y install epel-release && dnf -y install bats` (epel-release is in `extras`, enabled by default). Verified: EL9 -> `Bats 1.8.0` (bats-1.8.0-1.el9), EL10 -> `Bats 1.11.1` (bats-1.11.1-1.el10_0). `bats` install itself took 3-5 s; `epel-release` 1-12 s (measured on all four EL images).
* Tumbleweed: `zypper -n in bats` -> `Bats 1.14.0` (bats-1.14.0-1.1), main OSS repo, no extra repo. Leap 16.0: `Bats 1.11.1` (bats-1.11.1-160000.2.2), main repo. (install of bats+sudo: 8-9 s.)
* `sudo` installable everywhere: EL baseos `1.9.17p2` / `1.9.17-10.p2.el10_2.7`; Tumbleweed `1.9.17p2`; Leap `1.9.17p1`.
* `python3` on openSUSE: Leap has `python3` / `python313`; Tumbleweed has versioned `python311`/`python312`/... (no unversioned package).
* `rpm-build` and `createrepo_c` are installable on all six images (BaseOS/AppStream on EL, main OSS on openSUSE). EL9: rpm-build 4.16.1.3-40.el9 + createrepo_c 0.20.1-4.el9; EL10: rpm-build 4.19.1.1-23.el10 + createrepo_c 1.1.2-4.el10; Tumbleweed: rpm-build 4.20.1-11.1 + createrepo_c 1.2.3-1.4; Leap 16: rpm-build 4.20.1-160000.3.1 + createrepo_c 1.1.0-160000.2.2. No EPEL needed for them.
---------------------------------------------------------------------------------------------------------
## 1. Refresh metadata non-interactively
### DNF
```
$ dnf makecache # alma9 (dnf4), cold cache, 9.0 s
AlmaLinux 9 - AppStream 23 MB/s | 28 MB 00:01
AlmaLinux 9 - BaseOS 32 MB/s | 45 MB 00:01
AlmaLinux 9 - Extras 52 kB/s | 33 kB 00:00
Last metadata expiration check: 0:00:01 ago on Fri Oct 9 08:20:43 2026.
Metadata cache created. exit=0
```
Variants tested (stdout lines / stderr lines / exit):
| command | dnf4 (alma9/10) | dnf5 (fedora 44) |
|---|---|---|
| `dnf makecache` | 5 / 0 / 0 (progress + "Metadata cache created." on **stdout**) | 1 / 3 / 0 (progress "Updating and loading repositories:" ... "Repositories loaded." on **stderr**, "Metadata cache created." on stdout) |
| `dnf -q makecache` | 0 / 0 / 0 (silent) | 1 / 0 / 0 (**still prints "Metadata cache created." to stdout**) -> `>/dev/null` |
| `dnf --refresh makecache` and `dnf makecache --refresh` | both accepted, forces re-download | both accepted |
| plain `makecache` (no `--refresh`) | no re-download while the cache is younger than `metadata_expire` (dnf4 dump on alma9: `metadata_expire = 172800` = 48 h; ~1-2 s of revalidation measured) | same |
* `--refresh` (= "set metadata as expired") is the right switch for a skeptical tool: `dnf -q --refresh makecache` re-downloads every enabled repo (alma9 1.6-7 s, alma10 2.5-7 s, rocky 1-1.4 s, fedora 1.7 s measured warm; cold 3-9.5 s, section 11).
* `dnf check-update` exit codes (verified on dnf4 and dnf5): **100** = updates available, **0** = nothing (also 0 when a name pattern matches nothing: `dnf -q check-update 'nonexist*'` -> exit=0), **1** = error.
* **Dead repo handling differs** (repodata removed from the local repo):
| command | dnf4 alma10 | dnf5 fedora |
|---|---|---|
| `dnf -q --refresh makecache` | exit 1: `Error: Failed to download metadata for repo 'su-dummy': Cannot download repomd.xml: Cannot download repodata/repomd.xml: All mirrors were tried` | **exit 0**, no message (repo silently ignored, default `skip_if_unavailable=true` for repos that do not set it) |
| same + `--setopt=skip_if_unavailable=0` | exit 1 (same message) | exit 1: `Failed to download metadata (baseurl: "file:///var/lib/su-dummy-repo") for repository "su-dummy": Usable URL not found` |
| `dnf -y upgrade su-dummy-a` | exit 1 | **exit 0, prints `Nothing to do.`; su-dummy-a stays 1.0** (the dead repo is only a stderr warning `>>> Curl error (37) ...`, absent with `-q`) unless `skip_if_unavailable=0` |
So always pass `--setopt=skip_if_unavailable=0` (harmless on dnf4) and never rely on `-q` to see problems.
* Oddity seen on dnf 4.14.0 (EL9): with the repo gone, `dnf -q check-update` still returned **100 from stale cache**, while `makecache --refresh`, `repoquery` and `upgrade` failed with exit 1. => run the explicit refresh first and abort on its failure, do not infer repo health from check-update.
* Real-world flake observed once on `rockylinux:9`: `Error: Failed to download metadata for repo 'extras': repomd.xml parser error: Parse error at line: 1 (Extra content at the end of the document` (mirror served garbage), exit 1; re-run was clean. The refresh step correctly failed the run; the tool should surface this and let the user retry.
* `yum`: `/usr/bin/yum -> dnf-3` on all EL images (prints `4.14.0` / `4.20.0`); `/usr/bin/yum -> dnf5` on Fedora. Detection: `dnf --version | head -1` starts with `dnf5 version` on dnf5, with a bare version (`4.14.0`) on dnf4.
### ZYPPER
```
$ zypper --non-interactive refresh # tumbleweed, metadata fresh, 0.6 s
Repository 'openSUSE-Tumbleweed-Update' is up to date.
Repository 'openSUSE-Tumbleweed-Non-Oss' is up to date.
Repository 'Open H.264 Codec (openSUSE Tumbleweed)' is up to date.
Repository 'openSUSE-Tumbleweed-Oss' is up to date.
Repository 'su-dummy' is up to date.
All repositories have been refreshed. exit=0
```
* `-q` silences it; exit 0 either way. `zypper refresh --force su-dummy` re-downloads ("Forcing raw metadata refresh ... Building repository 'su-dummy' cache [....done]", exit 0).
* Normal `refresh` only checks whether the repo changed (cheap); it is also what `zypper lu/up/dup` do implicitly (autorefresh=on).
* Broken repo: `Retrieving repository 'su-dummy' metadata [.error]` ... `Could not refresh the repositories because of errors.` **exit=4**. Unknown name (`refresh nonexist`): `Repository 'nonexist' not found by its alias, number, or URI.` **exit=3**.
* Leap prints `Refreshing service 'openSUSE'.` as first line of nearly every command (it is a service, not a repo) - in `-q` mode it disappears, in `--xmlout` mode it is a `<message type="info">`.
* GPG: the test repo is `--no-gpgcheck`. For real third-party repos `--non-interactive` would refuse unknown keys; `--gpg-auto-import-keys` is the (security-relevant) opt-in. Not used by the tool.
---------------------------------------------------------------------------------------------------------
## 2. Machine-parsable list of upgradable packages (`name<TAB>old<TAB>new<TAB>repo`)
### 2.1 DNF: candidates compared (alma9/alma10 = dnf4, fedora = dnf5)
| | `dnf -q check-update` | `dnf -q repoquery --upgrades --queryformat ...` | `dnf -q list --upgrades` |
|---|---|---|---|
| first line(s) | dnf4: one **blank line**; dnf5: a header line `Upgrades` (printed even with `-q`) | none | `Available Upgrades` (dnf4) / `Available upgrades` (dnf5) |
| columns | 3: `name.arch evr repo` (arch suffix attached, epoch shown as `2:...` when non-zero) | whatever you ask for | same 3 columns |
| honours `--exclude` / `excludepkgs` | yes (dnf4, dnf5) | yes | yes |
| honours **versionlock** plugin | **yes** (dnf4 and dnf5) | dnf4: **no** (locked pkg still listed), dnf5: yes | **no** on both |
| same code path as `dnf upgrade` | yes | no | no |
| "Obsoleting Packages" | dnf4: trailing section `Obsoleting Packages` (+ indented old pkg `@System`); dnf5: not listed | not listed | not listed |
| exit | 100 / 0 / 1 | 0 | 0 |
| queryformat escapes | - | dnf4 expands `\t` `\n` **and appends its own newline** (blank line after each record); dnf5 does **not** expand `\t` (prints literal `\t`), expands `\n`, appends nothing | - |
| old (installed) version | not given | not given (no installed-version tag) | not given |
Samples (`cat -A`; EL9 shown, EL10 identical in shape):
```
$ dnf -q check-update | cat -A # dnf4, alma9, exit=100
$
gnutls.x86_64 3.8.10-9.el9_8 baseos $
su-dummy-a.noarch 2.0-1 su-dummy$
su-dummy-b.noarch 2.0-1 su-dummy$
su-dummy-c.x86_64 2.0-1 su-dummy$
vim-minimal.x86_64 2:8.2.2637-26.el9_8.23 baseos $
$ dnf -q check-update | head -3 # dnf5, fedora 44, exit=100
Upgrades
ca-certificates.noarch 2026.2.90_v9.0.317-1.fc44 updates
curl.x86_64 8.18.0-12.fc44 updates
$ dnf -q check-update 'nonexist*' ; echo exit=$? # both: nothing printed, exit=0
$ dnf -q repoquery --upgrades --queryformat '%{name}\t%{evr}\t%{repoid}\n' 'su-dummy-*'
su-dummy-a 2.0-1 su-dummy # dnf4: ...followed by a BLANK line after every record
su-dummy-a\t2.0-1\tsu-dummy # dnf5: literal "\t" (not expanded!)
$ dnf -q repoquery --upgrades --queryformat $'%{name}\t%{arch}\t%{evr}\t%{repoid}\n' 'su-dummy-*' | cat -A
su-dummy-a^Inoarch^I2.0-1^Isu-dummy$ # dnf4 and dnf5 identical when real TAB chars are passed
$ dnf -q repoquery --upgrades # default format on both: name-epoch:ver-rel.arch
su-dummy-a-0:2.0-1.noarch
```
Other tag differences: `%{reponame}` is the repo *id* on dnf4 but the human name on dnf5 (`skeptical-updater dummy packages`); `%{repoid}` is the id on both. `%{evr}` omits epoch `0` on both, includes `1:` when non-zero (`su-dummy-e` with `Epoch: 1` -> `1:2.0-1`).
dnf4 long names do **not** wrap in a non-tty even at `COLUMNS=30` (a 108-character package name stays on one line, padded): the 3-field read is safe; the same holds on dnf5.
**Decision: parse `dnf -q check-update`** (only listing that honours excludes *and* versionlock on both majors and is the same solver view as `dnf upgrade`), take the *old* version from `rpm -qa`, and use `repoquery` only for summary/description. Parse (from `lib-rpm.sh`, proven on 5 dnf images):
```bash
_su_installed_evr() { # "name.arch<TAB>evr", ascending so the highest version (installonly pkgs have several) wins
rpm -qa --qf '%{NAME}.%{ARCH}\t%|EPOCH?{%{EPOCH}:}|%{VERSION}-%{RELEASE}\n' | LC_ALL=C sort -t $'\t' -k1,1 -k2,2V
}
su_upgradable_dnf() {
local out rc na ver repo rest name arch k evr; local -A old=() oldn=()
out=$(dnf -q check-update --setopt=skip_if_unavailable=0); rc=$?
case $rc in 0) return 0 ;; 100) ;; *) return "$rc" ;; esac
while IFS=$'\t' read -r k evr; do evr=${evr#0:}; old[$k]=$evr; oldn[${k%.*}]=$evr; done < <(_su_installed_evr)
while read -r na ver repo rest; do
[ "$na" = Obsoleting ] && break # dnf4 trailing "Obsoleting Packages" section
[ -n "$repo" ] && [ -z "$rest" ] || continue # drops the blank line (dnf4), the "Upgrades" header (dnf5), anything not 3 fields
name=${na%.*}; arch=${na##*.} # plain name; the arch never contains a dot
printf '%s\t%s\t%s\t%s\t%s\n' "$name" "${old[$na]:-${oldn[$name]:-?}}" "$ver" "$repo" "$arch"
done <<<"$out" | LC_ALL=C sort
}
```
Output from `proof.sh` (alma10, tab shown as `^I`):
```
gnutls^I3.8.10-4.el10_2^I3.8.10-5.el10_2^Ibaseos^Ix86_64$
rpm-sequoia^I1.10.1.1-2.el10^I1.10.2.1-1.el10_2^Ibaseos^Ix86_64$
su-dummy-a^I1.0-1^I2.0-1^Isu-dummy^Inoarch$
su-dummy-b^I1.0-1^I2.0-1^Isu-dummy^Inoarch$
su-dummy-c^I1.0-1^I2.0-1^Isu-dummy^Ix86_64$
```
Epoch example (alma9): `vim-minimal 2:8.2.2637-26.el9_8.21 2:8.2.2637-26.el9_8.23 baseos x86_64`.
**Excluded / locked packages**: both are *removed from the sack*, so they simply do not appear in `check-update`/`repoquery` (with `--exclude=a,b`: only `su-dummy-c` remains). To see them anyway: dnf4 `--disableexcludes=all`; **dnf5 has no such option** (`Unknown argument "--disableexcludes=all" for command "repoquery"`, also no `--disable-excludes`/`--no-excludes`). Versionlock: dnf4 `python3-dnf-plugin-versionlock` (`/etc/dnf/plugins/versionlock.list`, line `su-dummy-a-0:1.0-1.*`), dnf5 `dnf5-plugins` (`/etc/dnf/versionlock.toml`); after `versionlock add su-dummy-a`, `check-update` lists only b and c on both.
**Blind spot - obsoletes**: a package that *obsoletes* an installed one (`su-dummy-new` obsoleting `su-dummy-old`) is listed only by dnf4 `check-update` (in the trailing section, which the parser drops) and by **no** `repoquery --upgrades`/dnf5 listing, but `dnf upgrade` will install it and remove the old one:
```
$ dnf --assumeno upgrade # dnf4
Installing:
su-dummy-new noarch 1.0-1 su-dummy 6.5 k
replacing su-dummy-old.noarch 1.0-1
```
=> use the plan preview of section 7 (`su_plan`) when the user must see *everything* that will change.
### 2.2 ZYPPER: candidates compared
| | `zypper -n --xmlout list-updates` | `zypper -q -n list-updates` (table) | `... lu --all` |
|---|---|---|---|
| exit | 0 (also with updates; there is no 100) | 0 | 0 |
| noise | `<message>` tags (`Loading repository data...`, Leap: `Refreshing service &apos;openSUSE&apos;.`) | `-q` removes all non-table lines | |
| fields | name, edition (new), edition-old, arch, summary, description, `<source alias=...>` | `S \| Repository \| Name \| Current Version \| Available Version \| Arch` (repo = display *name*, e.g. `openSUSE-Tumbleweed-Update`) | same table, locked rows get status `vl` |
| locked packages | hidden | hidden | **shown with status `vl`** |
| vendor-change candidates | hidden | hidden | shown (`v`) |
| when nothing | empty `<update-list>` | prints nothing (even no header) | |
```
$ zypper -q -n list-updates # tumbleweed
S | Repository | Name | Current Version | Available Version | Arch
---+----------------------------+--------------------+-----------------+-------------------+-------
v | openSUSE-Tumbleweed-Update | openSUSE-build-key | 1.0-68.1 | 1.0-69.1 | x86_64
v | su-dummy | su-dummy-a | 1.0-1 | 2.0-1 | noarch
v | su-dummy | su-dummy-b | 1.0-1 | 2.0-1 | noarch
v | su-dummy | su-dummy-c | 1.0-1 | 2.0-1 | x86_64
$ zypper -n --xmlout list-updates # one <update> element per package; attributes + summary + description (candidate!) + source
<update-list>
<update kind="package" name="su-dummy-a" edition="2.0-1" arch="noarch" edition-old="1.0-1"><summary>skeptical-updater dummy su-dummy-a (v2.0)</summary><description>Dummy package su-dummy-a version 2.0 for skeptical-updater tests.
...</description><license/><source url="file:/var/lib/su-dummy-repo" alias="su-dummy"/></update><update kind="package" ...
```
Note the XML puts *all `<update>` elements on one physical line* and descriptions span several lines, `xmllint` does not exist on SUSE images, `python3` neither. Parse with `tr`+`sed`+bash (proven on Tumbleweed and Leap):
```bash
_su_xattr() { # _su_xattr '<tag text>' attr -> $REPLY (XML-unescaped); rc 1 if absent. ' edition="' never matches ' edition-old="'
local v=${1#* $2=\"}; if [ "$v" = "$1" ]; then REPLY=; return 1; fi
v=${v%%\"*}; v=${v//&lt;/<}; v=${v//&gt;/>}; v=${v//&quot;/\"}; v=${v//&apos;/\'}; v=${v//&amp;/&}; REPLY=$v
}
su_upgradable_zypper() {
local xml rc line tag name new old arch src alias
xml=$(zypper --non-interactive --xmlout list-updates); rc=$?; [ "$rc" -eq 0 ] || return "$rc"
# tr leaves no trailing newline and GNU sed keeps it that way: without `|| [ -n "$line" ]` the LAST package is silently dropped
printf '%s\n' "$xml" | tr '\n' ' ' | sed 's/<update /\n<update /g' | while IFS= read -r line || [ -n "$line" ]; do
case $line in '<update kind="package" '*) ;; *) continue ;; esac
tag=${line%%>*}
_su_xattr "$tag" name; name=$REPLY; _su_xattr "$tag" edition; new=$REPLY
_su_xattr "$tag" edition-old; old=$REPLY; _su_xattr "$tag" arch; arch=$REPLY
src=${line#*<source }; alias=; [ "$src" != "$line" ] && { _su_xattr "$src" alias && alias=$REPLY; }
printf '%s\t%s\t%s\t%s\t%s\n' "$name" "$old" "$new" "$alias" "$arch"
done | LC_ALL=C sort
}
```
Output (tumbleweed): `openSUSE-build-key^I1.0-68.1^I1.0-69.1^Irepo-update^Ix86_64$`, `su-dummy-a^I1.0-1^I2.0-1^Isu-dummy^Inoarch$` ... The repo column is the stable **alias** (`repo-update`, Leap: `openSUSE:repo-oss`).
Table fallback (also proven; repo = display name, may contain spaces, e.g. `repo-oss (16.0)`):
```bash
trim() { local v=$1; v=${v#"${v%%[![:space:]]*}"}; v=${v%"${v##*[![:space:]]}"}; REPLY=$v; }
zypper -q -n list-updates | while IFS='|' read -r s repo name cur avail arch; do
case $s in v*) ;; *) continue ;; esac # data rows only (header/separator rows do not start with "v")
trim "$repo"; repo=$REPLY; trim "$name"; name=$REPLY; trim "$cur"; cur=$REPLY; trim "$avail"; avail=$REPLY; trim "$arch"; arch=$REPLY
printf '%s\t%s\t%s\t%s\t%s\n' "$name" "$cur" "$avail" "$repo" "$arch"
done
```
zypper already gives plain names (arch is a separate attribute/column).
**Locks** (see section 6): after `zypper addlock su-dummy-a su-dummy-b`, `lu` shows only `su-dummy-c`; `lu --all` shows
```
vl | su-dummy | su-dummy-a | 1.0-1 | 2.0-1 | noarch
vl | su-dummy | su-dummy-b | 1.0-1 | 2.0-1 | noarch
v | su-dummy | su-dummy-c | 1.0-1 | 2.0-1 | x86_64
```
**Vendor change**: package whose candidate has another vendor (`Vendor: FooCorp` installed, `BarCorp` in repo) is hidden by `lu`, shown by `lu --all`, and `zypper up` prints `There is an update candidate for 'su-dummy-v' from vendor 'BarCorp', while the current vendor is 'FooCorp'. Use 'zypper install su-dummy-v-2.0-1.noarch' to install this candidate.` followed by `Nothing to do.` (the update is skipped).
---------------------------------------------------------------------------------------------------------
## 3. One-line description and full info dump
Fixture packages carry `Summary: skeptical-updater dummy su-dummy-a (v1.0|v2.0)` and a two-paragraph description (blank line between paragraphs) so installed vs candidate and paragraph handling are distinguishable.
### 3.1 Installed version (all backends): rpm
```
$ rpm -q --qf '%{SUMMARY}\n%{DESCRIPTION}\n' su-dummy-a
skeptical-updater dummy su-dummy-a (v1.0)
Dummy package su-dummy-a version 1.0 for skeptical-updater tests.
Second paragraph of su-dummy-a 1.0 (blank line above on purpose).
$ rpm -qi su-dummy-a # Name/Version/Release/Architecture/Install Date/Group/Size/License/Signature/Source RPM/Build Date/Build Host/Summary/Description/Distribution
```
### 3.2 Candidate (new) version
**DNF**: `dnf info` prints *both* an `Installed Packages` and an `Available Packages` block (dnf4 `Description : first line` + ` : continuation` lines; dnf5 `info` adds `Epoch`, `From repository : <unknown>`, `Vendor`). `dnf info --upgrades PKG` (dnf4 and dnf5) prints only the candidate block (`Available Upgrades` / `Available upgrades`), as does `dnf repoquery -i --upgrades PKG`. For machine use take `repoquery` with a queryformat (same on dnf4/dnf5):
```bash
dnf -q repoquery --upgrades --latest-limit=1 --queryformat $'%{summary}\n%{description}\n' su-dummy-a
# -> line 1 summary, then the description with paragraph breaks intact; empty output => no candidate => fall back to rpm -q
```
dnf4 appends one extra blank line (harmless; `$(...)` strips it). Verified output (both dnf4 and dnf5): `skeptical-updater dummy su-dummy-a (v2.0)` / `Dummy package su-dummy-a version 2.0 ...` / blank / `Second paragraph of su-dummy-a 2.0 ...`.
Caveat: dnf4 `repoquery --upgrades` does not honour versionlock, so the "candidate" may be one the lock blocks; for the summary only this is irrelevant.
**ZYPPER**: `zypper info PKG` already shows the *best candidate* (and marks the installed state), falling back to the installed package when no repo has it:
```
$ zypper -q -n info su-dummy-a
Information for package su-dummy-a:
-----------------------------------
Repository : su-dummy
Name : su-dummy-a
Version : 2.0-1
Arch : noarch
Vendor :
Installed Size : 15 B
Installed : Yes
Status : out-of-date (version 1.0-1 installed)
Source package : su-dummy-a-2.0-1.src
Summary : skeptical-updater dummy su-dummy-a (v2.0)
Description :
Dummy package su-dummy-a version 2.0 for skeptical-updater tests.
Second paragraph of su-dummy-a 2.0 (blank line above on purpose).
```
`zypper info nonexistentpkg` -> `package 'nonexistentpkg' not found.` **exit=104**. `--xmlout info` is useless (one big `<message>` blob). `-q` does not remove the `Information for package` banner. Description lines are indented 4 spaces; **paragraph breaks are real empty lines and the block also ends with an empty line** (and a second empty line before the next `Information for package` banner when several names are given), so a plain `/^Description/,/^$/` sed range truncates after the first paragraph. State machine (proven):
```bash
zypper --non-interactive --quiet info "$pkg" 2>/dev/null | {
indesc=0; pend=
while IFS= read -r l; do
if [ $indesc = 1 ]; then
case $l in ' '*) printf '%s%s\n' "$pend" "${l# }"; pend= ;; # text line: flush held blank lines first
'') pend+=$'\n' ;; # blank: paragraph break OR end of block - decide on next line
*) break ;; esac # anything else = next block
else
case $l in Summary*:*) [ -z "${sum:-}" ] && { sum=${l#*: }; printf '%s\n' "$sum"; } ;; Description*:*) indesc=1 ;; esac
fi
done; }
# if zypper info exits non-zero (104) fall back to: rpm -q --qf '%{SUMMARY}\n%{DESCRIPTION}\n' "$pkg"
```
The XML of `list-updates`/`update --dry-run` (sections 2.2 and 7) also carries the candidate `summary`+`description` for upgradable packages.
`su_describe PKG` in `lib-rpm.sh` wraps all of this; `proof.sh` asserts candidate summary `skeptical-updater dummy su-dummy-a (v2.0)`, the preserved blank line, and installed-only `su-dummy-d (v1.0)` on all 7 images.
---------------------------------------------------------------------------------------------------------
## 4. Installed reverse dependencies
Candidates and what they really do:
| command | result on EL9 for `bash` | verdict |
|---|---|---|
| `rpm -q --whatrequires bash` | **1** package (`ca-certificates`) - matches only a Requires entry literally named `bash` | misses file deps (`/bin/sh`, `/usr/bin/bash`), sonames, virtual provides |
| `dnf repoquery --installed --whatrequires bash` | **52** (dnf4 default = `--alldeps`: all provides *and files*; `--exactdeps` drops to 1) | correct, dnf only; works on dnf4 and dnf5 (fedora: 42) |
| `zypper search --installed-only -t package --requires bash` | = naive (name only); `--requires-pkg bash` uses all provides but over-reports on Tumbleweed (43 hits vs 4 direct: includes packages that depend via `/bin/sh` -> `bash-sh` -> `bash`) | not the reference |
| **pure rpm `su_rdeps`** (below) | EL9 52, EL10 40, Fedora 42, Tumbleweed 4 direct (69 recursive), Leap 5 direct (67 recursive) | **chosen**; identical to the dnf answer wherever dnf can answer |
Why name != capability: on Tumbleweed `/bin/sh` is provided by `bash-sh`, not `bash` (`rpm -q --whatprovides /bin/sh` -> `bash-sh`), so `aaa_base`, `binutils`, ... are *direct* dependents of `bash-sh` and only *transitive* dependents of `bash`; `su_rdeps_recursive bash` (69) is a superset of zypper's 43 (`comm -23` empty).
Algorithm: (1) the set of names the package is known by = `[%{PROVIDENAME}\n]` + `rpm -ql` (owned files, so file deps like `/bin/sh` match); (2) one table of every installed package's requirements `capability<TAB>package` from `rpm -qa --qf '[%{REQUIRENAME}\t%{=NAME}\n]'` with `rpmlib(...)` dropped and rich deps expanded; (3) `join` the two on the capability, drop the package itself. **Mandatory trick `%{=NAME}`** (a bare `%{NAME}` inside `[...]` makes rpm print `error: incorrect format: array iterator used with different sized arrays` for roughly half of the packages; reproduced on rpm 4.16.1.3, 4.19.1.1, 4.20.1, 6.0.2 - and the same error appears for `[%{PROVIDENAME}\t%{NAME}\n]`).
```bash
su_req_table() { # "capability<TAB>requiring-package", sorted; rich deps expanded via su_cap_names (section 5)
local out=$1 cap name t all; all=$(mktemp)
rpm -qa --qf '[%{REQUIRENAME}\t%{=NAME}\n]' > "$all"
{ grep -v -e '^rpmlib(' -e '^(' "$all" || true
{ grep -e '^(' "$all" || true; } | while IFS=$'\t' read -r cap name; do
su_cap_names <<<"$cap" | while IFS= read -r t; do printf '%s\t%s\n' "$t" "$name"; done
done
} | LC_ALL=C sort -u > "$out"; rm -f "$all"
}
su_rdeps() { # direct installed dependents of PKG, plain names, sorted
local pkg=$1 tab caps own=0
if [ -n "${SU_REQ_TAB:-}" ] && [ -s "$SU_REQ_TAB" ]; then tab=$SU_REQ_TAB; else tab=$(mktemp); su_req_table "$tab"; own=1; fi
caps=$(mktemp)
{ rpm -q --qf '[%{PROVIDENAME}\n]' "$pkg"; rpm -ql "$pkg" | grep -v -e '^(contains no files)$'; } | LC_ALL=C sort -u > "$caps"
LC_ALL=C join -t $'\t' "$caps" "$tab" | cut -f2 | LC_ALL=C sort -u | grep -v -x -F -e "$pkg" || true
rm -f "$caps"; [ "$own" = 1 ] && rm -f "$tab"; return 0
}
```
`su_rdeps_recursive PKG...` (also in the lib) loops `su_rdeps` with one shared table. Proof assertions: `su_rdeps su-dummy-b` = `su-dummy-a su-dummy-d`; `su_rdeps su-dummy-c` = `su-dummy-d` (c is only required through the rich dep `(su-dummy-c if su-dummy-b)`); `su_rdeps su-dummy-d` = empty; `su_rdeps(bash)` equals `dnf repoquery --installed --whatrequires bash` (EL9: 52 = 52, EL10: 40 = 40, Fedora/dnf5: 42 = 42). Cost: ~60-130 ms on these minimal images.
Plain names: `%{NAME}` has no arch/version; multilib duplicates collapse through `sort -u`. `dnf repoquery ... --queryformat $'%{name}\n' | sed '/^$/d'` is the dnf-native equivalent (dnf4 blank lines).
---------------------------------------------------------------------------------------------------------
## 5. Recursive dependency closure restricted to installed packages
* `dnf repoquery --installed --requires --resolve --recursive --queryformat $'%{name}\n' PKG`: **works on dnf4** (alma9/alma10); **dnf5 rejects it**: `Unknown argument "--resolve" for command "repoquery". ... The argument is available for commands: download` (rc=2). Also dnf-only.
* **Chosen: pure-rpm breadth-first search**, identical on dnf and zypper distros. Per BFS level: `rpm -q --qf '[%{REQUIRENAME}\n]' <frontier>` -> filter -> `rpm -q --whatprovides --qf '%{NAME}\n' <caps>`.
Input handling (all verified):
| dependency kind | example | handling |
|---|---|---|
| `rpmlib(...)` | `rpmlib(CompressedFileNames)` | dropped (not a package; `--whatprovides` would just say "no package provides") |
| file deps | `/bin/sh`, `/usr/bin/perl` | looked up with `rpm -q --whatprovides /bin/sh` (file owner or explicit Provides: `bash` on EL, `bash-sh` on SUSE) |
| soname / virtual | `libc.so.6(GLIBC_2.34)(64bit)`, `perl(Foo::Bar)`, `config(bash)` | kept verbatim (REQUIRENAME already carries no version); contain parentheses but do not *start* with `(` |
| versioned | `su-dummy-b >= 1.0` | `%{REQUIRENAME}` returns only `su-dummy-b`; the constraint is ignored (installed state is already consistent) |
| rich / boolean | `(su-dummy-c if su-dummy-b)`, `(glibc-gconv-extra(x86-64) = 2.34-275.el9_8 if redhat-rpm-config)`, `(account-utils or shadow-pw-mgmt = 4.20.3)`, `(annobin if (gcc or clang))` | `su_cap_names` tokenises with paren-depth tracking: members kept, comparison operators and the version token after them dropped, `and/or/with/without` ignored, the **condition** after `if`/`unless` dropped (until `else` or the closing paren). Conditions are not evaluated -> safe superset |
| unresolvable | nothing installed provides it | `no package provides X` lines are filtered out (rpm prints them on **stdout**, exit 1) |
`su_cap_names` unit results (proven, EL9):
```
rpmlib(CompressedFileNames) =>
/bin/sh => /bin/sh
libc.so.6(GLIBC_2.34)(64bit) => libc.so.6(GLIBC_2.34)(64bit)
(su-dummy-c if su-dummy-b) => su-dummy-c
(glibc-gconv-extra(x86-64) = 2.34-275.el9_8 if redhat-rpm-config) => glibc-gconv-extra(x86-64)
(foo >= 1.0-2 or (bar and baz)) => foo bar baz
((a or b) if c) => a b
(a if b else c) => a c
(a unless (b and c) else d) => a d
(libx.so.1()(64bit) if foo) => libx.so.1()(64bit)
(annobin if (gcc or clang)) => annobin
(account-utils or shadow-pw-mgmt = 4.20.3) => account-utils shadow-pw-mgmt
```
Why the condition must be dropped: with the naive "all tokens" version, `glibc` on EL9 (rich dep `(glibc-gconv-extra ... if redhat-rpm-config)`) appeared to depend on `redhat-rpm-config`, which dragged `rpm`, `rpm-build`, `binutils`, `gdb-minimal` and the perl modules into the closure of `filesystem` (167 packages instead of ~15).
```bash
su_closure() { # su_closure PKG... -> installed packages PKG... need transitively (plain names, sorted, roots excluded)
local -A seen=(); local -a frontier=("$@") caps provs next out=(); local p
for p in "$@"; do seen[$p]=1; done
while [ "${#frontier[@]}" -gt 0 ]; do
mapfile -t caps < <(rpm -q --qf '[%{REQUIRENAME}\n]' "${frontier[@]}" 2>/dev/null | sort -u | su_cap_names | sort -u)
[ "${#caps[@]}" -gt 0 ] || break
mapfile -t provs < <(rpm -q --whatprovides --qf '%{NAME}\n' "${caps[@]}" 2>/dev/null | grep -v -e '^no package provides ' | sort -u)
next=()
for p in "${provs[@]}"; do [ -n "$p" ] && [ -z "${seen[$p]:-}" ] && { seen[$p]=1; next+=("$p"); out+=("$p"); }; done
frontier=("${next[@]}")
done
[ "${#out[@]}" -gt 0 ] && printf '%s\n' "${out[@]}" | sort -u; return 0
}
```
Proof (`proof.sh`, every image): `su_closure su-dummy-a` = `su-dummy-b`; `su_closure su-dummy-d` contains `su-dummy-a su-dummy-b su-dummy-c glibc` and the provider of `/bin/sh` (`bash` on EL, `bash-sh` on SUSE), no `rpmlib`, not the root. On dnf4 the result **equals** `dnf repoquery --installed --requires --resolve --recursive`: alma9 18 = 18, alma10 17 = 17 (dnf lists `bash` in its own closure because of the `filesystem` <-> `bash` cycle; ours excludes roots by design). Sample (alma10): `almalinux-gpg-keys almalinux-release almalinux-repos basesystem bash filesystem glibc glibc-common glibc-gconv-extra glibc-minimal-langpack libgcc ncurses-base ncurses-libs setup su-dummy-a su-dummy-b su-dummy-c tzdata`; Tumbleweed `closure(su-dummy-d)` = `bash bash-sh filesystem glibc libncurses6 libreadline8 su-dummy-a su-dummy-b su-dummy-c system-user-root terminfo-base`. Timing: 70-130 ms.
---------------------------------------------------------------------------------------------------------
## 6. Per-run exclusion
### 6.1 DNF (`--exclude`, verified on dnf4 4.14/4.20 and dnf5 5.4.3)
| form | dnf4 | dnf5 |
|---|---|---|
| `dnf -y upgrade --exclude=su-dummy-a,su-dummy-b` (comma list) | ok | ok (documented as `-x package,..., --exclude=package,...`, global option) |
| `--exclude=a --exclude=b` (repeated) | ok | ok |
| `-x a -x b` | ok | ok |
| globs `--exclude='su-dummy-[ab]'` | ok | ok |
| space separated in one value `--exclude='a b'` | ok (repoquery) | ok (repoquery) |
| works on `check-update`, `repoquery`, `upgrade` | yes | yes |
| `--disableexcludes=all` to see them again | yes | **not available** |
Result of `dnf -y upgrade --exclude=su-dummy-a,su-dummy-b 'su-dummy-*'` (dnf4 and dnf5): `su-dummy-a=1.0 su-dummy-b=1.0 su-dummy-c=2.0` (both syntaxes). Excluded packages disappear from `check-update` too (only `su-dummy-c` left).
Edge cases (verified):
* all packages matched by an explicit pattern are excluded: dnf4 `No match for argument: su-dummy-*` / `Error: No packages marked for upgrade.` **exit 1**; dnf5 `Argument 'su-dummy-*' matches only excluded packages.` **exit 1**. With *no* package arguments and nothing to do both print `Nothing to do.` **exit 0**.
* **an excluded dependency blocks the upgrade of its dependant** (`su-dummy-p` 2.0 `Requires: su-dummy-q >= 2.0`, `--exclude=su-dummy-q`):
* dnf4 (EL default `best = 1`, `skip_if_unavailable = 0` in the dnf4 config dump): `Error: Problem: package su-dummy-p-2.0-1.noarch from su-dummy requires su-dummy-q >= 2.0, but none of the providers can be installed ... package su-dummy-q-2.0-1.noarch from su-dummy is filtered out by exclude filtering` **exit 1**; `--skip-broken` does *not* help (same error); `--nobest` -> `Skip 1 Package ... Nothing to do.` exit 0.
* dnf5: `Skipping packages with broken dependencies: su-dummy-p noarch 2.0-1 su-dummy` then `Nothing to do.` **exit 0** (no flag needed; `--skip-broken` is rejected on `upgrade`: `Unknown argument "--skip-broken" for command "upgrade"`).
=> exit codes cannot tell "everything upgraded" from "some skipped because of the exclusion": re-run `su_upgradable` afterwards (the proof does) and report what is left.
### 6.2 ZYPPER (no `--exclude`)
Findings that drive the recipe:
* `zypper update/dup` have no exclude option. Locks (`zypper addlock NAME...`, glob via `*`/`?`) are honoured by the solver: a **full** `zypper update` (no package args) silently skips locked packages; a lock on `a`,`b` -> only `c` is upgraded.
* An **explicit** `zypper update LOCKED` or an update whose dependency is locked ends in an interactive "Problem" which `--non-interactive` answers with *cancel*: **exit 4**:
```
Problem: 1: Detailed information: - conflicting requests
Solution 1: Following actions will be done: remove lock to allow installation of su-dummy-a-2.0-1.noarch[su-dummy] ...
Solution 2: do not ask to install a solvable providing su-dummy-a.noarch = 2.0-1
Choose from above solutions by number or skip, retry or cancel [1/2/s/r/c/d/?] (c): c exit=4
```
while a full update with a locked dependency of a newer package just skips both: `The following 2 package updates will NOT be installed: su-dummy-p su-dummy-q` (exit 0), `p`/`q` stay 1.0.
* Naming the packages explicitly instead (`zypper update a b c`) is **not** an exclusion mechanism: `zypper update su-dummy-p` (p 2.0 needs q >= 2.0) also upgraded `su-dummy-q` (dependency pull) - verified.
* Lock file `/etc/zypp/locks` (path = `locksfile.path` in zypp.conf; created on first `addlock`; on Tumbleweed `/etc/zypp/zypp.conf` does not exist at all, only `/usr/etc/zypp/zypp.conf`):
```
$ cat -A /etc/zypp/locks
$
type: package$
match_type: glob$
case_sensitive: on$
solvable_name: su-dummy-a$
$
```
`zypper locks` table: `# | Name | Type | Repository | Comment`; `zypper -q ll` prints the same.
* `zypper removelock NAME` is **not** a safe undo: it deletes *every* lock that matches NAME (a pre-existing user lock of the same name is destroyed - verified), and it leaves a 0-byte `/etc/zypp/locks` behind even when no file existed before (verified: `-rw-r--r-- 1 root root 0`).
#### Recipe A (chosen): private zypp.conf, nothing persisted - `su_zypper_excluding`
libzypp reads `$ZYPP_CONF` instead of `/etc/zypp/zypp.conf`. Copy the current config (fall back to `/usr/etc/zypp/zypp.conf` on Tumbleweed), append `[main] locksfile.path = <tmp>/locks`, seed `<tmp>/locks` with a copy of the real locks, `addlock` the exclusions *there*, run, `rm -rf` the temp dir. The real lock set is never opened for writing, so there is nothing to restore (Ctrl-C safe, concurrent-run safe).
```bash
su_zypper_excluding() { # su_zypper_excluding NAME... -- zypper-args... e.g. ... a b -- update | ... a -- --xmlout dup --dry-run
local -a ex=(); local d src locks rc
while [ $# -gt 0 ] && [ "$1" != -- ]; do ex+=("$1"); shift; done; [ "${1:-}" = -- ] && shift
d=$(mktemp -d) || return 1
src=/etc/zypp/zypp.conf; [ -r "$src" ] || src=/usr/etc/zypp/zypp.conf
locks=$(sed -n 's/^[[:space:]]*locksfile\.path[[:space:]]*=[[:space:]]*//p' "$src" | tail -n1); : "${locks:=/etc/zypp/locks}"
cp "$src" "$d/zypp.conf" || { rm -rf "$d"; return 1; }
if [ -e "$locks" ]; then cp "$locks" "$d/locks"; else : > "$d/locks"; fi
printf '\n[main]\nlocksfile.path = %s\n' "$d/locks" >> "$d/zypp.conf" # second [main] block: last assignment wins (verified)
if [ "${#ex[@]}" -gt 0 ]; then
ZYPP_CONF=$d/zypp.conf zypper --non-interactive --quiet addlock "${ex[@]}" >/dev/null || { rm -rf "$d"; return 1; }
fi
ZYPP_CONF=$d/zypp.conf zypper --non-interactive "$@"; rc=$?
rm -rf "$d"; return $rc
}
```
Proof (Tumbleweed `dup` and Leap `update`, `proof.sh` section 6): `su_upgrade --exclude su-dummy-a --exclude su-dummy-b` -> exit 0, `su-dummy-a=1.0 su-dummy-b=1.0 su-dummy-c=2.0`; `/etc/zypp/locks` unchanged (absent before, absent after); no leftover `/tmp/tmp.*`; `su_upgradable` still lists a and b afterwards; the following unrestricted `su_upgrade` upgrades them (`a=2.0 b=2.0 c=2.0`).
#### Recipe B (alternative with exact restore of the real locks file) - `su_zypper_excluding_snapshot`
Use this only if the real locks must be the ones libzypp sees (e.g. another tool reads `/etc/zypp/locks` concurrently - note it is then visible to that tool for the duration).
```bash
su_zypper_excluding_snapshot() ( # subshell => traps are local
ex=(); while [ $# -gt 0 ] && [ "$1" != -- ]; do ex+=("$1"); shift; done; [ "${1:-}" = -- ] && shift
src=/etc/zypp/zypp.conf; [ -r "$src" ] || src=/usr/etc/zypp/zypp.conf
locks=$(sed -n 's/^[[:space:]]*locksfile\.path[[:space:]]*=[[:space:]]*//p' "$src" | tail -n1); : "${locks:=/etc/zypp/locks}"
bak=$(mktemp) || exit 1; had=0; restored=0
if [ -e "$locks" ]; then cp -p -- "$locks" "$bak" || exit 1; had=1; fi # snapshot: bytes + mode + mtime, or "absent"
_restore() { [ "$restored" = 1 ] && return 0; restored=1
if [ "$had" = 1 ]; then cp -p -- "$bak" "$locks"; else rm -f -- "$locks"; fi; rm -f -- "$bak"; }
trap '_restore' EXIT; trap '_restore; exit 130' INT; trap '_restore; exit 143' TERM HUP
if [ "${#ex[@]}" -gt 0 ]; then zypper --non-interactive --quiet addlock "${ex[@]}" >/dev/null || exit 1; fi
zypper --non-interactive "$@"
)
```
Proof (`proof.sh` section 10, Tumbleweed; Leap likewise): with a pre-existing user lock on `su-dummy-d` (comment "user lock"): `cksum`+mtime identical after a run (`834034310 97 1791570407` before and after); user lock still present, temporary locks gone; a user lock on the *same* name as an exclusion survives (`zypper removelock` would have deleted it - asserted); file absent before => absent after; run killed with SIGTERM mid-way (shadowed `zypper` that kills its parent subshell) -> exit 143 and locks restored byte-identical.
#### Recipe C (rejected): explicit package list
`zypper update <list of everything except X>`: dependencies pull X anyway (shown above) and any name that is already newest prints `No update candidate for ...`. Rejected.
---------------------------------------------------------------------------------------------------------
## 7. Non-interactive upgrade, exit codes, plan preview
### 7.1 DNF
* `dnf -y upgrade [--exclude=a,b] [--setopt=skip_if_unavailable=0]`
* Exit codes (4 and 5): **0** success *and* "Nothing to do." (also `Dependencies resolved. Nothing to do. Complete!` on dnf4); **1** any error (unknown package argument `No match for argument: X` + `Error: No packages marked for upgrade.`, dependency problem, dead repo with `skip_if_unavailable=0`); **100 exists only for `check-update`**; `--assumeno` (dry run) ends with **exit 1** (`Operation aborted.` / `Operation aborted by the user.`) after printing the transaction table.
* `-q` removes the progress chatter but dnf5 still prints `Nothing to do.`; dnf5 prints `Warning: skipped OpenPGP checks for 3 packages from repository: su-dummy` for gpgcheck=0 repos.
* On the stale `rockylinux:9` (9.3) the first `-y` transaction imports the Rocky 9 GPG key automatically (`Importing GPG key 0x350D275D: ... From : /etc/pki/rpm-gpg/RPM-GPG-KEY-Rocky-9`) - harmless with `-y`, but a non-`-y` path would prompt.
* There is no machine-readable transaction output in dnf4. `dnf5 check-upgrade --json` exists (dnf5 only), not used.
### 7.2 ZYPPER
Detection (verified): `/etc/os-release` `ID=opensuse-tumbleweed` (Tumbleweed) -> **`dup`**; `ID=opensuse-leap` (Leap 16.0) -> **`update`**; `ID_LIKE` is `opensuse suse` / `suse opensuse` on both, so test `ID`, not `ID_LIKE`. (`opensuse-slowroll` is rolling too and treated like Tumbleweed in the lib - not tested; MicroOS/Aeon/Leap Micro are transactional and out of scope.)
```bash
su_zypper_verb() { case "$(su_os_id)" in opensuse-tumbleweed|opensuse-slowroll) echo dup ;; *) echo update ;; esac; }
zypper --non-interactive dup # prints: Warning: You are about to do a distribution upgrade with all enabled repositories. ... Computing distribution upgrade...
zypper --non-interactive update
```
Observed exit codes:
| situation | exit |
|---|---|
| success / "Nothing to do." (`update` and `dup`; `No update candidate for 'su-dummy-a-2.0-1.noarch'. The highest available version is already installed.` for explicit names) | **0** |
| `list-updates` with or without updates; `patch-check` with 0 patches | 0 |
| repo cannot be refreshed (`Could not refresh the repositories because of errors.`) | **4** |
| unknown repository name | 3 |
| unresolved Problem answered by `--non-interactive` (default = cancel): explicit update of a locked package; dup with a vendor/"distupgrade repository" problem (`the installed su-dummy-v-1.0-1.noarch does not belong to a distupgrade repository and must be replaced` / Solution 1 install from vendor BarCorp / Solution 2 keep obsolete) | **4** |
| `info`/`remove` of a name nothing provides (`No provider of 'nonexistent-xx' found.`) | **104** |
| `update --dry-run` / `dup --dry-run` (even with `Continue? [y/n/...] (y): y` echoed) | 0 (dry run, nothing changed) |
| update of a package listed in `/etc/zypp/needreboot(.d)` | **0**, plus the text `Since the last system boot core libraries or services have been updated. Reboot is suggested to ensure that your system benefits from these updates.` |
Not reproduced here (documented zypper(8) semantics, no fixture can trigger them without real SUSE patches): `100`/`101` (`patch-check`: updates / security updates needed), `102` (reboot needed after a patch with the reboot flag), `103` (zypper itself/libzypp was updated, restart zypper), `106` (some repos skipped), `107` (an rpm scriptlet failed). The tool should treat any non-zero exit as failure to be shown, `0` as success, and treat 100-103 as "success with advice" if it ever sees them.
`dup` vs `update` on Tumbleweed: in this snapshot `update --dry-run` and `dup --dry-run` computed the same plan (4 upgrades `openSUSE-build-key su-dummy-a su-dummy-b su-dummy-c`, 11 new packages `krb5 libbrotlicommon1 ... libverto1`, 1 removal `libcurl-mini4` - i.e. a package *swap* that `list-updates` never shows). The documented difference shows with vendor changes: `list-updates` hides the candidate, `update` skips it with a message, `dup` raises the Problem above (exit 4 under `-n`) - so Tumbleweed must use `dup`, and a skeptical tool must expect exit 4 there and show the Problem text (re-run without `-n`... or `--dry-run` text) instead of retrying.
### 7.3 Plan preview (what would REALLY change: new deps, removals, obsoletes)
`list-updates`/`check-update` never show newly installed dependencies, removals or obsolete-replacements. `su_plan [--exclude N]...` (in `lib-rpm.sh`) prints `section<TAB>name<TAB>old<TAB>new<TAB>repo<TAB>arch<TAB>replaces`, honouring exclusions:
* zypper: `zypper --non-interactive --xmlout dup|update --dry-run` yields exact data (no table parsing):
```
<install-summary download-size="19047" space-usage-diff="0" ... packages-to-change="3" need-restart="0" need-reboot="0">
<to-upgrade>
<solvable type="package" name="su-dummy-a" edition="2.0-1" arch="noarch" repository="su-dummy" edition-old="1.0-1" arch-old="noarch" summary="..."><description>...</description></solvable>
...</to-upgrade><to-install>...</to-install><to-remove>...</to-remove></install-summary>
```
(the `<prompt>` and `<progress>` elements that follow are ignored; `need-reboot`/`need-restart` attributes are available).
* dnf: `dnf --assumeno upgrade` table parse - section headers are col-0 lines ending in `:` (`Upgrading:`, `Installing:`, `Installing dependencies:`, `Installing weak dependencies:`, `Removing:`, `Removing unused dependencies:`, `Skipping packages with broken dependencies:` ...), rows start with one space, parsing stops at `Transaction Summary`. dnf4 prints no `replacing` line for plain upgrades (old version then comes from `rpm -q`), dnf5 prints `replacing` rows with `0:`-prefixed epochs.
Proof section 9 (builds `su-dummy-new` with `Obsoletes: su-dummy-old < 2` + `Provides: su-dummy-old = 2`): with `--exclude su-dummy-a`:
```
zypper (tumbleweed) dnf4 (alma9) dnf5 (fedora)
upgrade su-dummy-b 1.0-1 2.0-1 su-dummy noarch - install su-dummy-new - 1.0-1 su-dummy noarch su-dummy-old upgrade su-dummy-b 1.0-1 2.0-1 su-dummy noarch -
upgrade su-dummy-c 1.0-1 2.0-1 su-dummy x86_64 - upgrade su-dummy-b 1.0-1 2.0-1 su-dummy noarch - upgrade su-dummy-c 1.0-1 2.0-1 su-dummy x86_64 -
install su-dummy-new - 1.0-1 su-dummy noarch - upgrade su-dummy-c 1.0-1 2.0-1 su-dummy x86_64 - install su-dummy-new - 1.0-1 su-dummy noarch su-dummy-old
remove su-dummy-old - 1.0-1 @System noarch -
```
and `su_upgradable` shows 0 rows for `su-dummy-new` on all of them (the blind spot).
---------------------------------------------------------------------------------------------------------
## 8. Remove / purge
### DNF (dnf4 and dnf5 identical in effect)
* `clean_requirements_on_remove` default **1** on both (dnf4: `dnf config-manager --dump` -> `clean_requirements_on_remove = 1`; dnf5 behaves the same: its plan shows `Removing unused dependencies: su-dummy-s noarch 0:1.0-1 su-dummy`).
```
$ dnf -y install su-dummy-r # r Requires s; both installed by dnf
$ dnf -y remove su-dummy-r # dnf4: "Erasing: su-dummy-r-1.0-1.noarch ... Erasing: su-dummy-s-1.0-1.noarch" exit=0 (both removed)
$ dnf -y remove --setopt=clean_requirements_on_remove=0 su-dummy-r # only r removed; s stays
$ dnf -y autoremove # then removes the leftover s
```
* Only dependencies **installed by dnf as dependencies** are cleaned. `su-dummy-b` (installed by plain `rpm -Uvh`) stays after `dnf -y remove su-dummy-a` on both majors.
* `dnf remove nonexistent-xx` exits **0** on dnf4 (`Nothing to do.`) and dnf5 (`No packages to remove for argument: nonexistent-xx` / `Nothing to do.`) -> confirm with `rpm -q` afterwards.
* dnf4 refuses protected packages: `dnf -y remove dnf` -> `Error: Problem: The operation would result in broken dependencies for the following protected packages: yum ...` **exit 1**.
* There is no `apt purge` equivalent in the rpm world; `%config` handling on removal (`*.rpmsave`) was not exercised here.
### ZYPPER
* `zypper --non-interactive remove --clean-deps PKG` (`-u`). Plain `remove` leaves the dependency: after `zypper -n install su-dummy-r` (pulls `su-dummy-s`), `zypper -n remove su-dummy-r` -> only r removed, `rpm -q su-dummy-s` still present; with `--clean-deps` -> `2 packages to remove.` `(1/2) Removing: su-dummy-r ... (2/2) Removing: su-dummy-s`, exit 0.
* Which deps are "unneeded" is tracked by zypper in `/var/lib/zypp/AutoInstalled`; packages installed with plain `rpm` (the fixture's `su-dummy-b`) are never cleaned: `remove --clean-deps su-dummy-a` left `su-dummy-b` installed.
* Unknown name: `'nonexistent-xx' not found in package names. Trying capabilities.` ... `No provider of 'nonexistent-xx' found.` / `Nothing to do.` **exit 104**.
* `proof.sh` section 7 asserts all of the above through `su_remove` on every image.
---------------------------------------------------------------------------------------------------------
## 9. Base image facts
See section 0.4 for the table (bash versions, sudo/su/python3/awk/find/xmllint presence), bats (EPEL on EL9/EL10; main repos on openSUSE) and `rpm-build`/`createrepo_c` availability. Short version: bash is present everywhere (5.1-5.3), `sudo` nowhere, `python3` only on EL, `awk`/`find`/`xargs` missing on Tumbleweed, `find`/`xargs` missing on Leap, `su` missing on alma10; `bats` needs EPEL on Alma/Rocky; `rpm-build` and `createrepo_c` install from the base repos everywhere.
---------------------------------------------------------------------------------------------------------
## 10. E2E fixture - `discovery/rpm/fixture.sh`
```
docker run --rm -i -v <project>/discovery/rpm:/d:ro <image> bash /d/fixture.sh # SU_FIXTURE_EXTRAS=1 for the extras
```
What it does (single script, detects `zypper` first, then `dnf`/`yum`; refuses to run as non-root):
1. installs `rpm-build` + `createrepo_c` (dnf: `dnf -y -q install --setopt=install_weak_deps=False ...`; zypper: `zypper --non-interactive --quiet install --no-recommends ...`) - no EPEL/extra repo needed anywhere;
2. generates minimal specs and builds with `rpmbuild -bb --define "_topdir /var/tmp/su-fixture"`: `su-dummy-a` (noarch, `Requires: su-dummy-b`), `su-dummy-b` (noarch), `su-dummy-c` (**arch-specific**, `%global debug_package %{nil}`, so the `.x86_64` suffix path is exercised), versions 1.0-1 and 2.0-1, one file each, `Summary: skeptical-updater dummy <name> (v<ver>)`, two-paragraph `%description`;
3. installs the three 1.0 packages with `rpm -Uvh --oldpackage --replacepkgs` (distro-agnostic; re-running the script resets to the 1.0 state);
4. publishes only the 2.0 packages in `/var/lib/su-dummy-repo` and runs `createrepo_c`;
5. registers the repo: dnf `/etc/yum.repos.d/su-dummy.repo` (`baseurl=file:///var/lib/su-dummy-repo`, `gpgcheck=0`, `repo_gpgcheck=0`, `metadata_expire=0`) + `dnf -q makecache --repo su-dummy`; zypper `zypper addrepo --no-gpgcheck --no-check --refresh file:///var/lib/su-dummy-repo su-dummy` + `zypper refresh su-dummy`;
6. verifies that `check-update` / `list-updates` lists `su-dummy-a`, `-b`, `-c`, else exits 1.
`SU_FIXTURE_EXTRAS=1` additionally installs `su-dummy-d` 1.0 (not upgradable; `Requires: su-dummy-a`, `/bin/sh`, `su-dummy-b >= 1.0`, `(su-dummy-c if su-dummy-b)`, `rpmlib(CompressedFileNames)`) for rdeps/closure tests and publishes (not installs) `su-dummy-r` (Requires `su-dummy-s`) / `su-dummy-s` for remove tests.
Side effect worth knowing: installing `rpm-build` pulls `redhat-rpm-config` etc. on EL, which flips the condition of rich dependencies such as glibc's `(glibc-gconv-extra if redhat-rpm-config)`; the closure code must therefore not treat conditions as dependencies (it does not).
Real output (`fixture.sh` standalone, each run exit 0):
```
[fixture] backend=dnf # almalinux:9
[fixture] build tools installed in 14s
[fixture] rpmbuild done in 0s
[fixture] repo refresh in 0s
[fixture] OK: su-dummy-{a,b,c} 1.0 installed and 2.0 offered by repo 'su-dummy' (total 15s, since start 15s)
```
and the same `OK` line (totals 8-16 s) on almalinux:10, rockylinux:9, rockylinux/rockylinux:10, quay.io/rockylinux/rockylinux:10, opensuse/tumbleweed (`backend=zypper`, 13 s), opensuse/leap (`backend=zypper`, 14 s), and fedora:latest (dnf5, 16 s). Also verified: a second run on the same container is a clean reset (`proof.sh` section 8).
`proof.sh` results (final run, all rc=0): almalinux:9 44 PASS, almalinux:10 44, rockylinux:9 44, rockylinux/rockylinux:10 44, opensuse/tumbleweed 53, opensuse/leap 53, fedora:latest 43 (dnf5). (zypper images run two extra sections: lock snapshot/restore.) One transient failure was seen and is not a code issue: the first `rockylinux:9` run failed section 1 (`su_refresh` exit 1: Rocky `extras` mirror returned a broken `repomd.xml`); re-run passed (the refresh gate did exactly what it is for).
---------------------------------------------------------------------------------------------------------
## 11. Rough timings (host with fast network, Docker 29.8.2; wall clock, one run each, sequential)
| image | `docker pull` | cold metadata refresh (first `dnf makecache` / `zypper refresh` in the container) | warm refresh | `fixture.sh` wall (of which tool install) | `proof.sh` wall |
|---|---|---|---|---|---|
| almalinux:9 | 4.7 s | 9.5 s | 1.6 s | 15.1 s (14 s) | 29.5 s |
| almalinux:10 | 4.5 s | 5.9 s | 1.9 s | 11.5 s (9 s) | 25.5 s |
| rockylinux:9 (9.3 lib image, 96 pending upgrades) | 6.1 s | 8.4 s | 1.1 s | 16.6 s (15 s) | 29.8 s |
| rockylinux/rockylinux:10 | 5.9 s | 3.3 s | 1.6 s | 10.5 s (8 s) | 21.0 s |
| quay.io/rockylinux/rockylinux:10 | 1.0 s (layers cached) | 4.2 s | - | 8.1 s (7 s) | not run (same image) |
| opensuse/tumbleweed | 3.4 s | 5.9 s | 0.9 s | 14.3 s (12 s) | 32.7 s |
| opensuse/leap (16.0) | 3.5 s | 6.3 s | 0.6 s | 14.4 s (12 s) | 34.3 s |
| fedora:latest (dnf5, reference) | n/a | 5.3 s | 0.3 s | 16.0 s (15 s) | 29.2 s |
Inside `proof.sh` (warm containers): forced refresh (`su_refresh`) 0.5-2.6 s (up to 7 s on alma when the mirror is slow), `su_upgradable` 0.3-0.8 s, `su_closure` 0.07-0.13 s, `su_rdeps` ~0.06-0.13 s, dummy upgrade 0.1-0.3 s (dnf) / 1.6-7 s (zypper, because a full `update`/`dup` also upgrades real packages). "Warm refresh" for dnf is a plain `dnf makecache` without `--refresh` (it still revalidates); `--refresh` forces a full download and is the number to budget for a skeptical run (3-9 s cold).
---------------------------------------------------------------------------------------------------------
## 12. Gotcha checklist for the implementer
1. Never assume dnf5 on EL10; support dnf4 + dnf5 through one parser (`check-update`, 3 fields, tolerate blank line, `Upgrades` header, `Obsoleting Packages` section).
2. Always `--setopt=skip_if_unavailable=0` (dnf5 otherwise hides dead repos, `-q` hides the warning) and gate on the refresh exit status; do not trust `check-update` alone on dnf 4.14.
3. dnf `repoquery --queryformat`: pass real TAB/newline (`$'%{name}\t%{evr}\n'`), then `sed '/^$/d'` (dnf4 adds blank lines, dnf5 expands only `\n`, `\t` stays literal). `--qf` and `--queryformat` both work on both majors.
4. dnf4 `repoquery --upgrades` and `dnf list --upgrades` ignore versionlock; `check-update` does not. dnf5 has no `--disableexcludes`.
5. `check-update`/`list-updates` hide obsoleters, new dependencies and removals. Use `su_plan` when the user must see the real transaction; compare list vs result afterwards because exit codes do not reveal skipped packages (dnf5 skips broken-dependency packages with exit 0; dnf4 fails with exit 1 unless `--nobest`).
6. `rpm --qf '[%{=NAME}...]'`, never `%{NAME}` inside `[...]`.
7. `rpm -q --whatrequires pkg` is name-only; use provides + owned files (`su_rdeps`). Rich deps: members only, conditions dropped.
8. zypper XML: all `<update>` elements are on one line, descriptions multi-line, no xmllint/python on the images, trailing-newline trap with `tr`+`sed`+`read`.
9. zypper `list-updates` exits 0 even with updates; never look for 100. Locked and vendor-change candidates are hidden (`lu --all` shows them).
10. zypper has no `--exclude`: use `ZYPP_CONF` private locks (or snapshot/restore of the real locks file; `removelock` is not an undo). Tumbleweed has no `/etc/zypp/zypp.conf`, only `/usr/etc/zypp/zypp.conf`.
11. Tumbleweed -> `dup`, Leap -> `update`, decided from `ID=` in `/etc/os-release`; `dup`/`update` under `--non-interactive` turn unresolved Problems into exit 4 (cancel) - show the Problem, do not blindly retry.
12. Base images lack `awk`, `find`, `xargs`, `python3`, `xmllint`, `sudo`, `hostname`, `diff`; `rockylinux:9` is a stale 9.3 image (use `rockylinux/rockylinux:9`); `rockylinux:10` does not exist.
13. `dnf remove` of a non-existent package exits 0; zypper exits 104. Verify with `rpm -q`.
14. Packages installed with plain `rpm -i` are never auto-removed by `dnf remove` / `zypper remove --clean-deps`.
## 13. Not verified / limits
* dnf5 was verified on `fedora:latest` (Fedora 44, dnf5 5.4.3.0 - an image outside the requested list), not on an EL10 userland (no dnf5 package in Alma 10; Rocky 10 has `dnf5 5.1.12` only in the disabled `devel` repo and was not exercised).
* zypper exit codes 100-103, 106, 107 were not reproduced (see 7.2). `opensuse-slowroll`, MicroOS/Aeon (transactional), SLES were not tested.
* Multi-arch (x86_64 + i686) and installonly kernels were not exercised; the parser keys on `name.arch` and keeps the highest installed `evr` per key for the "old" column.
* Docker images pulled during this work (all kept, none removed or re-tagged): `almalinux:9`, `almalinux:10`, `rockylinux:9`, `rockylinux/rockylinux:9`, `rockylinux/rockylinux:10`, `quay.io/rockylinux/rockylinux:9`, `quay.io/rockylinux/rockylinux:10`, `opensuse/tumbleweed:latest`, `opensuse/leap:latest`, `fedora:latest`.
discovery/rpm/fixture.sh
Executable
+158
View File
@@ -0,0 +1,158 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# fixture.sh - deterministic E2E fixture for RPM distros (dnf: Alma/Rocky/..., zypper: openSUSE)
#
# Builds three dummy packages with rpmbuild, installs version 1.0 of each, publishes
# version 2.0 in a local file:// repo and registers that repo, so that the package
# manager reports exactly these upgrades:
#
# su-dummy-a 1.0-1 -> 2.0-1 (noarch, Requires: su-dummy-b)
# su-dummy-b 1.0-1 -> 2.0-1 (noarch)
# su-dummy-c 1.0-1 -> 2.0-1 (ARCH-SPECIFIC, so the ".x86_64" suffix path is exercised)
#
# Optional (SU_FIXTURE_EXTRAS=1):
# - installs su-dummy-d 1.0 (NOT upgradable): Requires su-dummy-a, /bin/sh (file dep),
# "su-dummy-b >= 1.0" (versioned), "(su-dummy-c if su-dummy-b)" (rich dep) and rpmlib(...)
# -> for reverse-dep / dependency-closure tests;
# - publishes su-dummy-r 1.0 (Requires su-dummy-s) and su-dummy-s 1.0 in the repo, NOT installed
# -> for install/remove/--clean-deps tests.
#
# Re-runnable: re-running resets everything to the "1.0 installed, 2.0 available" state.
#
# Usage (inside the container, as root): bash fixture.sh
# docker run --rm -i -v <project>/discovery/rpm:/d:ro <image> bash /d/fixture.sh
set -euo pipefail
export LC_ALL=C
T0=$SECONDS
log() { printf '[fixture] %s\n' "$*" >&2; }
die() { printf '[fixture] ERROR: %s\n' "$*" >&2; exit 1; }
[ "$(id -u)" -eq 0 ] || die "must run as root"
# ---- 1. backend detection ---------------------------------------------------
BACKEND=
if command -v zypper >/dev/null 2>&1; then BACKEND=zypper
elif command -v dnf >/dev/null 2>&1; then BACKEND=dnf
elif command -v yum >/dev/null 2>&1; then BACKEND=yum
else die "neither zypper nor dnf/yum found"; fi
log "backend=$BACKEND"
TOP=/var/tmp/su-fixture # rpmbuild topdir
REPO=/var/lib/su-dummy-repo # file:// repo (only 2.0 packages)
SPEC_DIR=$TOP/SPECS
# ---- 2. build tools ---------------------------------------------------------
t=$SECONDS
case $BACKEND in
zypper) zypper --non-interactive --quiet install --no-recommends rpm-build createrepo_c >/dev/null ;;
dnf|yum) "$BACKEND" -y -q install --setopt=install_weak_deps=False rpm-build createrepo_c >/dev/null ;;
esac
command -v rpmbuild >/dev/null || die "rpmbuild missing after install"
command -v createrepo_c >/dev/null || die "createrepo_c missing after install"
log "build tools installed in $((SECONDS - t))s"
# ---- 3. build RPMs ----------------------------------------------------------
rm -rf "$TOP" "$REPO"
mkdir -p "$TOP"/{BUILD,BUILDROOT,RPMS,SRPMS,SOURCES,SPECS} "$REPO"
# mkspec <name> <version> <arch|noarch> <extra spec header lines...>
mkspec() {
local name=$1 ver=$2 arch=$3; shift 3
local f=$SPEC_DIR/$name-$ver.spec
{
echo "Name: $name"
echo "Version: $ver"
echo "Release: 1"
echo "Summary: skeptical-updater dummy $name (v$ver)"
echo "License: MIT"
[ "$arch" = noarch ] && echo "BuildArch: noarch"
local l; for l in "$@"; do echo "$l"; done
echo "%global debug_package %{nil}"
echo "%description"
echo "Dummy package $name version $ver for skeptical-updater tests."
echo ""
echo "Second paragraph of $name $ver (blank line above on purpose)."
echo "%install"
echo "mkdir -p %{buildroot}/usr/share/su-dummy"
echo "echo '$name $ver' > %{buildroot}/usr/share/su-dummy/$name"
echo "%files"
echo "/usr/share/su-dummy/$name"
} > "$f"
printf '%s\n' "$f"
}
build() { rpmbuild -bb --quiet --define "_topdir $TOP" "$1" >/dev/null 2>"$TOP/rpmbuild.err" \
|| { cat "$TOP/rpmbuild.err" >&2; die "rpmbuild failed for $1"; }; }
t=$SECONDS
for v in 1.0 2.0; do
build "$(mkspec su-dummy-a $v noarch 'Requires: su-dummy-b')"
build "$(mkspec su-dummy-b $v noarch)"
build "$(mkspec su-dummy-c $v arch)"
done
if [ "${SU_FIXTURE_EXTRAS:-0}" = 1 ]; then
build "$(mkspec su-dummy-s 1.0 noarch)" # published in the repo, NOT installed
build "$(mkspec su-dummy-r 1.0 noarch 'Requires: su-dummy-s')" # (used to test remove/--clean-deps)
build "$(mkspec su-dummy-d 1.0 noarch \
'Requires: su-dummy-a' \
'Requires: /bin/sh' \
'Requires: su-dummy-b >= 1.0' \
'Requires: (su-dummy-c if su-dummy-b)' \
'Requires: rpmlib(CompressedFileNames)')"
fi
log "rpmbuild done in $((SECONDS - t))s"
# ---- 4. install 1.0 (rpm directly: distro-agnostic, resets to 1.0 on re-run) ----
shopt -s nullglob
v1=( "$TOP"/RPMS/*/su-dummy-[abc]-1.0-1.*.rpm )
[ "${#v1[@]}" -eq 3 ] || die "expected 3 built 1.0 rpms, got ${#v1[@]}"
rpm -Uvh --oldpackage --replacepkgs "${v1[@]}" >/dev/null
if [ "${SU_FIXTURE_EXTRAS:-0}" = 1 ]; then
rpm -Uvh --oldpackage --replacepkgs "$TOP"/RPMS/noarch/su-dummy-d-1.0-1.*.rpm >/dev/null
fi
# ---- 5. publish 2.0 as a local repo -------------------------------------------
v2=( "$TOP"/RPMS/*/su-dummy-[abc]-2.0-1.*.rpm )
[ "${#v2[@]}" -eq 3 ] || die "expected 3 built 2.0 rpms, got ${#v2[@]}"
cp "${v2[@]}" "$REPO"/
if [ "${SU_FIXTURE_EXTRAS:-0}" = 1 ]; then cp "$TOP"/RPMS/noarch/su-dummy-[rs]-1.0-1.*.rpm "$REPO"/; fi
createrepo_c --quiet "$REPO" >/dev/null
# ---- 6. register repo ---------------------------------------------------------
case $BACKEND in
zypper)
zypper --non-interactive --quiet removerepo su-dummy >/dev/null 2>&1 || true
zypper --non-interactive --quiet addrepo --no-gpgcheck --no-check --refresh "file://$REPO" su-dummy >/dev/null
t=$SECONDS
zypper --non-interactive --quiet refresh su-dummy >/dev/null
;;
dnf|yum)
cat > /etc/yum.repos.d/su-dummy.repo <<REPOEOF
[su-dummy]
name=skeptical-updater dummy packages
baseurl=file://$REPO
enabled=1
gpgcheck=0
repo_gpgcheck=0
metadata_expire=0
REPOEOF
t=$SECONDS
"$BACKEND" -q makecache --repo su-dummy >/dev/null
;;
esac
log "repo refresh in $((SECONDS - t))s"
# ---- 7. verify: the three must be listed as upgradable --------------------------
want="su-dummy-a su-dummy-b su-dummy-c"
case $BACKEND in
zypper) listing=$(zypper --non-interactive --quiet list-updates 2>&1 || true) ;;
dnf|yum) listing=$("$BACKEND" -q check-update 2>&1 || true) ;;
esac
bad=0
for p in $want; do
printf '%s\n' "$listing" | grep -Eq "(^|[| ])$p([. ]|$)" || { log "NOT listed as upgradable: $p"; bad=1; }
done
if [ "$bad" -ne 0 ]; then printf '%s\n' "$listing" >&2; die "fixture verification failed"; fi
log "OK: su-dummy-{a,b,c} 1.0 installed and 2.0 offered by repo 'su-dummy' (total ${SECONDS}s, since start $((SECONDS - T0))s)"
discovery/rpm/lib-rpm.sh
Executable
+396
View File
@@ -0,0 +1,396 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# lib-rpm.sh - proven building blocks for RPM distros: dnf4, dnf5 (yum alias) and zypper.
#
# SOURCE this file; nothing runs on source. Every function here was exercised by proof.sh on
# almalinux:9, almalinux:10, rockylinux:9, rockylinux/rockylinux:10, opensuse/tumbleweed,
# opensuse/leap (16.0) and (dnf5 reference) fedora:latest.
#
# Runtime needs only: bash >= 4.2, rpm, sed, grep, tr, sort (GNU, for -V), join, cut, mktemp.
# NOT assumed (missing on at least one target image): awk, find, xargs, python3, xmllint, sudo,
# hostname, diff, cmp, column.
#
# All upgradable-package lists use one record format (TAB separated):
# name <TAB> old-evr <TAB> new-evr <TAB> repo <TAB> arch
# (name is the PLAIN rpm name, arch is a separate 5th column; "old-evr" is "?" if unknown)
export LC_ALL=C
# ---------------------------------------------------------------- detection
su_backend() { # -> "zypper" | "dnf" (dnf covers dnf4, dnf5 and the yum alias on EL9+)
if command -v zypper >/dev/null 2>&1; then echo zypper
elif command -v dnf >/dev/null 2>&1; then echo dnf
else return 1; fi
}
su_os_id() { ( . /etc/os-release 2>/dev/null; printf '%s' "${ID:-}" ); }
su_dnf_major() { dnf --version 2>/dev/null | grep -q '^dnf5' && echo 5 || echo 4; }
# zypper verb for "upgrade everything": Tumbleweed (and Slowroll) are rolling -> dup; Leap/SLE -> update
su_zypper_verb() {
case "$(su_os_id)" in opensuse-tumbleweed|opensuse-slowroll) echo dup ;; *) echo update ;; esac
}
# ---------------------------------------------------------------- 1. refresh
# exit 0 = fresh metadata for ALL repos. dnf: 1 on any failure (we force skip_if_unavailable=0 because
# dnf5 otherwise silently ignores a dead repo and exits 0 - and `-q` hides even the warning).
# zypper: 4 = repo error, 3 = bad repo name, 6 = no repos defined.
su_refresh() {
case "$(su_backend)" in
dnf) dnf -q --refresh --setopt=skip_if_unavailable=0 makecache >/dev/null ;;
zypper) zypper --non-interactive --quiet refresh ;;
esac
}
# ---------------------------------------------------------------- 2. upgradable list
# installed evr table "name.arch<TAB>evr", highest version last (installonly packages have several)
_su_installed_evr() {
rpm -qa --qf '%{NAME}.%{ARCH}\t%|EPOCH?{%{EPOCH}:}|%{VERSION}-%{RELEASE}\n' \
| LC_ALL=C sort -t $'\t' -k1,1 -k2,2V
}
# dnf (4 and 5): authoritative source = `dnf -q check-update` (the only listing that honours excludes AND
# versionlock in both majors; repoquery/list do not honour dnf4 versionlock). exit 100 = updates, 0 = none.
su_upgradable_dnf() {
local out rc na ver repo rest name arch k evr
local -A old=() oldn=()
out=$(dnf -q check-update --setopt=skip_if_unavailable=0); rc=$?
case $rc in 0) return 0 ;; 100) ;; *) return "$rc" ;; esac
while IFS=$'\t' read -r k evr; do evr=${evr#0:}; old[$k]=$evr; oldn[${k%.*}]=$evr; done < <(_su_installed_evr)
while read -r na ver repo rest; do
[ "$na" = Obsoleting ] && break # dnf4 appends an "Obsoleting Packages" section
[ -n "$repo" ] && [ -z "$rest" ] || continue # skips blank line, dnf5 "Upgrades" header, etc.
name=${na%.*}; arch=${na##*.}
printf '%s\t%s\t%s\t%s\t%s\n' "$name" "${old[$na]:-${oldn[$name]:-?}}" "$ver" "$repo" "$arch"
done <<<"$out" | LC_ALL=C sort
}
# XML attribute helper: _su_xattr '<tag text>' attr -> $REPLY (unescaped); rc 1 if absent
_su_xattr() {
local v=${1#* $2=\"}
if [ "$v" = "$1" ]; then REPLY=; return 1; fi
v=${v%%\"*}
v=${v//&lt;/<}; v=${v//&gt;/>}; v=${v//&quot;/\"}; v=${v//&apos;/\'}; v=${v//&amp;/&}
REPLY=$v
}
# zypper: `zypper --xmlout list-updates` (locked packages are hidden; `lu --all` would show them as "vl").
# The XML is flattened with tr so each <update ...>...</update> becomes one line, then split with sed.
su_upgradable_zypper() {
local xml rc line tag name new old arch src alias
xml=$(zypper --non-interactive --xmlout list-updates); rc=$?
[ "$rc" -eq 0 ] || return "$rc"
# NB: after tr the stream has no trailing newline; GNU sed keeps it that way, so the LAST record would be
# silently dropped by a plain `while read` -> `|| [ -n "$line" ]` is required.
printf '%s\n' "$xml" | tr '\n' ' ' | sed 's/<update /\n<update /g' | while IFS= read -r line || [ -n "$line" ]; do
case $line in '<update kind="package" '*) ;; *) continue ;; esac
tag=${line%%>*}
_su_xattr "$tag" name; name=$REPLY
_su_xattr "$tag" edition; new=$REPLY
_su_xattr "$tag" edition-old; old=$REPLY
_su_xattr "$tag" arch; arch=$REPLY
src=${line#*<source }; alias=
[ "$src" != "$line" ] && { _su_xattr "$src" alias && alias=$REPLY; }
printf '%s\t%s\t%s\t%s\t%s\n' "$name" "$old" "$new" "$alias" "$arch"
done | LC_ALL=C sort
}
su_upgradable() {
case "$(su_backend)" in dnf) su_upgradable_dnf ;; zypper) su_upgradable_zypper ;; esac
}
# ---------------------------------------------------------------- 3. summary + description
# su_describe PKG : line 1 = Summary, remaining lines = Description (paragraph breaks kept).
# Candidate (upgrade) version if there is one, otherwise the installed one.
su_describe() {
local pkg=$1 out
case "$(su_backend)" in
dnf)
out=$(dnf -q repoquery --upgrades --latest-limit=1 --queryformat $'%{summary}\n%{description}\n' "$pkg" 2>/dev/null)
[ -n "$out" ] || out=$(rpm -q --qf '%{SUMMARY}\n%{DESCRIPTION}\n' "$pkg" 2>/dev/null)
printf '%s\n' "$out" ;;
zypper)
out=$(zypper --non-interactive --quiet info "$pkg" 2>/dev/null) || { rpm -q --qf '%{SUMMARY}\n%{DESCRIPTION}\n' "$pkg"; return; }
printf '%s\n' "$out" | {
local l indesc=0 pend=
while IFS= read -r l; do
if [ $indesc = 1 ]; then # description lines are indented by 4 spaces;
case $l in # blank lines are real empty lines (paragraph break OR end of block)
' '*) printf '%s%s\n' "$pend" "${l# }"; pend= ;;
'') pend+=$'\n' ;;
*) break ;;
esac
else
case $l in
Summary*:*) [ -z "${sum:-}" ] && { sum=${l#*: }; printf '%s\n' "$sum"; } ;;
Description*:*) indesc=1 ;;
esac
fi
done
} ;;
esac
}
# ---------------------------------------------------------------- 4/5. installed dependency graph (pure rpm)
# su_cap_names: stdin = one REQUIRENAME per line; stdout = plain capability names to look up.
# - drops rpmlib(...) pseudo-deps
# - expands rich/boolean deps "(a if b)", "(a >= 1.0 or b)", "((a and b) unless c else d)" to their
# *members*; the CONDITION of "if"/"unless" is dropped (it is not a dependency). Conditions are not
# evaluated, so "(a if b)" yields "a" even if b is not installed = safe superset.
# - names like libc.so.6(GLIBC_2.34)(64bit), perl(Foo::Bar), /bin/sh, config(x) are kept verbatim
su_cap_names() {
local cap tok w depth cond skip o c n
set -f
while IFS= read -r cap; do
case $cap in
''|rpmlib\(*) ;;
\(*)
depth=0; cond=-1; skip=0
for tok in $cap; do
w=$tok; n=0
while [ "${w:0:1}" = '(' ]; do w=${w:1}; n=$((n+1)); done # structural opens (a cap never starts with '(')
depth=$((depth+n))
o=${w//[^(]/}; c=${w//[^)]/}; n=$(( ${#c} - ${#o} )) # structural closes = surplus ')' at the end
[ "$n" -lt 0 ] && n=0
[ "$n" -gt 0 ] && w=${w%"${w: -$n}"}
if [ "$skip" = 1 ]; then skip=0
else
case $w in
if|unless) cond=$depth ;;
else) [ "$cond" = "$depth" ] && cond=-1 ;;
and|or|with|without|'') ;;
'='|'<'|'>'|'<='|'>='|'==') skip=1 ;; # next token is a version
*) [ "$cond" -lt 0 ] && printf '%s\n' "$w" ;;
esac
fi
depth=$((depth-n))
[ "$cond" -ge 0 ] && [ "$depth" -lt "$cond" ] && cond=-1
done ;;
*) printf '%s\n' "$cap" ;;
esac
done
set +f
}
# su_closure PKG...: installed packages (plain names, sorted; the roots themselves are not listed) that PKG...
# need, transitively. Breadth-first; 2 rpm calls per level. Identical results to
# `dnf repoquery --installed --requires --resolve --recursive` on dnf4 (dnf5 has no such option).
su_closure() {
local -A seen=(); local -a frontier=("$@") caps provs next out=(); local p
for p in "$@"; do seen[$p]=1; done
while [ "${#frontier[@]}" -gt 0 ]; do
mapfile -t caps < <(rpm -q --qf '[%{REQUIRENAME}\n]' "${frontier[@]}" 2>/dev/null | sort -u | su_cap_names | sort -u)
[ "${#caps[@]}" -gt 0 ] || break
mapfile -t provs < <(rpm -q --whatprovides --qf '%{NAME}\n' "${caps[@]}" 2>/dev/null | grep -v -e '^no package provides ' | sort -u)
next=()
for p in "${provs[@]}"; do
[ -n "$p" ] && [ -z "${seen[$p]:-}" ] && { seen[$p]=1; next+=("$p"); out+=("$p"); }
done
frontier=("${next[@]}")
done
[ "${#out[@]}" -gt 0 ] && printf '%s\n' "${out[@]}" | sort -u
return 0
}
# su_req_table FILE: "capability<TAB>requiring-package" for every installed package, sorted (LC_ALL=C).
# NB: inside [...] the scalar tag MUST be written %{=NAME}; plain %{NAME} makes rpm fail with
# "array iterator used with different sized arrays" for ~50% of packages (all rpm versions 4.16..6.0).
su_req_table() {
local out=$1 cap name t all
all=$(mktemp)
rpm -qa --qf '[%{REQUIRENAME}\t%{=NAME}\n]' > "$all"
{
grep -v -e '^rpmlib(' -e '^(' "$all" || true
{ grep -e '^(' "$all" || true; } | while IFS=$'\t' read -r cap name; do
su_cap_names <<<"$cap" | while IFS= read -r t; do printf '%s\t%s\n' "$t" "$name"; done
done
} | LC_ALL=C sort -u > "$out"
rm -f "$all"
}
# su_rdeps PKG: installed packages (plain names, sorted) that DIRECTLY require something PKG provides: its name,
# any Provides (sonames, virtual capabilities; versions ignored) or any file it owns (file deps like /bin/sh).
# Same result as `dnf repoquery --installed --whatrequires PKG` (verified); plain `rpm -q --whatrequires PKG`
# only matches the literal capability "PKG" and misses e.g. 51 of 52 dependents of bash on EL9.
# (Set SU_REQ_TAB=<file made by su_req_table> to reuse one table across many calls.)
su_rdeps() {
local pkg=$1 tab caps own=0
if [ -n "${SU_REQ_TAB:-}" ] && [ -s "$SU_REQ_TAB" ]; then tab=$SU_REQ_TAB; else tab=$(mktemp); su_req_table "$tab"; own=1; fi
caps=$(mktemp)
{ rpm -q --qf '[%{PROVIDENAME}\n]' "$pkg"; rpm -ql "$pkg" | grep -v -e '^(contains no files)$'; } | LC_ALL=C sort -u > "$caps"
LC_ALL=C join -t $'\t' "$caps" "$tab" | cut -f2 | LC_ALL=C sort -u | grep -v -x -F -e "$pkg" || true
rm -f "$caps"; [ "$own" = 1 ] && rm -f "$tab"
return 0
}
# su_rdeps_recursive PKG...: everything installed that (transitively) depends on PKG... (roots excluded).
# NB: "direct" dependents can be far fewer than you expect: on Tumbleweed `/bin/sh` is provided by bash-sh, not
# bash, so aaa_base/binutils/... are dependents of bash-sh (which requires bash), i.e. only in the recursive set.
su_rdeps_recursive() {
local -A seen=(); local -a frontier=("$@") next out=(); local p r SU_REQ_TAB
SU_REQ_TAB=$(mktemp); su_req_table "$SU_REQ_TAB"
for p in "$@"; do seen[$p]=1; done
while [ "${#frontier[@]}" -gt 0 ]; do
next=()
for p in "${frontier[@]}"; do
while IFS= read -r r; do
[ -n "$r" ] && [ -z "${seen[$r]:-}" ] && { seen[$r]=1; next+=("$r"); out+=("$r"); }
done < <(su_rdeps "$p")
done
frontier=("${next[@]}")
done
rm -f "$SU_REQ_TAB"
[ "${#out[@]}" -gt 0 ] && printf '%s\n' "${out[@]}" | sort -u
return 0
}
# ---------------------------------------------------------------- 6. upgrade with per-run exclusions
# su_zypper_excluding NAME... -- zypper-args...
# zypper has no --exclude. Per-run locks WITHOUT touching /etc/zypp/locks: point libzypp at a private
# zypp.conf (env ZYPP_CONF) whose locksfile.path is a temp copy of the current locks, add the exclusions there,
# run zypper, delete the temp dir. Nothing to restore, nothing persisted, safe on Ctrl-C.
su_zypper_excluding() {
local -a ex=(); local d src locks rc
while [ $# -gt 0 ] && [ "$1" != -- ]; do ex+=("$1"); shift; done
[ "${1:-}" = -- ] && shift
d=$(mktemp -d) || return 1
src=/etc/zypp/zypp.conf; [ -r "$src" ] || src=/usr/etc/zypp/zypp.conf # Tumbleweed ships only /usr/etc
locks=$(sed -n 's/^[[:space:]]*locksfile\.path[[:space:]]*=[[:space:]]*//p' "$src" | tail -n1)
: "${locks:=/etc/zypp/locks}"
cp "$src" "$d/zypp.conf" || { rm -rf "$d"; return 1; }
if [ -e "$locks" ]; then cp "$locks" "$d/locks"; else : > "$d/locks"; fi
printf '\n[main]\nlocksfile.path = %s\n' "$d/locks" >> "$d/zypp.conf"
if [ "${#ex[@]}" -gt 0 ]; then
ZYPP_CONF=$d/zypp.conf zypper --non-interactive --quiet addlock "${ex[@]}" >/dev/null || { rm -rf "$d"; return 1; }
fi
ZYPP_CONF=$d/zypp.conf zypper --non-interactive "$@"; rc=$?
rm -rf "$d"
return $rc
}
# su_upgrade [--exclude NAME]... [-- extra-pm-args...] (non-interactive; exit status of the package manager)
# dnf : dnf -y upgrade --exclude=a,b (comma list works on dnf4 AND dnf5; repeated flags too)
# zypper : update (Leap/SLE) or dup (Tumbleweed) with temporary locks (see su_zypper_excluding)
su_upgrade() {
local -a ex=() extra=()
while [ $# -gt 0 ]; do
case $1 in
--exclude) ex+=("$2"); shift 2 ;;
--) shift; extra=("$@"); break ;;
*) echo "su_upgrade: bad arg $1" >&2; return 2 ;;
esac
done
case "$(su_backend)" in
dnf)
local ox=(); if [ "${#ex[@]}" -gt 0 ]; then local IFS=,; ox=("--exclude=${ex[*]}"); fi
dnf -y --setopt=skip_if_unavailable=0 upgrade "${ox[@]}" "${extra[@]}" ;;
zypper)
su_zypper_excluding "${ex[@]}" -- "$(su_zypper_verb)" "${extra[@]}" ;;
esac
}
# su_zypper_excluding_snapshot NAME... -- zypper-args...
# Alternative recipe (what you would do if ZYPP_CONF were unavailable): add real locks to /etc/zypp/locks
# and restore the EXACT previous file afterwards. `zypper removelock NAME` is NOT a safe undo: it deletes ALL
# locks matching NAME (including a pre-existing user lock) and leaves an empty /etc/zypp/locks behind even if the
# file did not exist before. Hence: byte copy (cp -p) of the file, or "file absent" flag, restored by a trap.
# Runs in a subshell so the traps are local. Not safe against two concurrent runs (use su_zypper_excluding).
su_zypper_excluding_snapshot() (
ex=(); while [ $# -gt 0 ] && [ "$1" != -- ]; do ex+=("$1"); shift; done; [ "${1:-}" = -- ] && shift
src=/etc/zypp/zypp.conf; [ -r "$src" ] || src=/usr/etc/zypp/zypp.conf
locks=$(sed -n 's/^[[:space:]]*locksfile\.path[[:space:]]*=[[:space:]]*//p' "$src" | tail -n1); : "${locks:=/etc/zypp/locks}"
bak=$(mktemp) || exit 1; had=0; restored=0
if [ -e "$locks" ]; then cp -p -- "$locks" "$bak" || exit 1; had=1; fi
_restore() {
[ "$restored" = 1 ] && return 0; restored=1
if [ "$had" = 1 ]; then cp -p -- "$bak" "$locks"; else rm -f -- "$locks"; fi
rm -f -- "$bak"
}
trap '_restore' EXIT; trap '_restore; exit 130' INT; trap '_restore; exit 143' TERM HUP
if [ "${#ex[@]}" -gt 0 ]; then zypper --non-interactive --quiet addlock "${ex[@]}" >/dev/null || exit 1; fi
zypper --non-interactive "$@"
)
# ---------------------------------------------------------------- 7. plan preview (display only)
# su_plan [--exclude NAME]... -> section<TAB>name<TAB>old<TAB>new<TAB>repo<TAB>arch<TAB>replaces
# section = upgrade | install | remove | downgrade | reinstall | skipped | other ; old/replaces are "-" if n/a.
# Shows what `su_upgrade` would do INCLUDING new dependencies, removals and obsolete-replacements, which the
# upgradable list (check-update / list-updates) never shows. Nothing is changed.
su_plan_zypper() {
local out
out=$(su_zypper_excluding "$@" -- --xmlout "$(su_zypper_verb)" --dry-run) || return $?
# <install-summary><to-upgrade><solvable type="package" name= edition= arch= repository= edition-old= .../>...</to-upgrade><to-install>...
printf '%s\n' "$out" | tr '\n' ' ' | sed -e 's/<to-/\n<to-/g' -e 's/<solvable /\n<solvable /g' |
{
local line sec=other tag n e o a r
while IFS= read -r line || [ -n "$line" ]; do
case $line in
'<to-'*) sec=${line#<to-}; sec=${sec%%>*} ;;
'<solvable type="package" '*)
tag=${line%%>*}
_su_xattr "$tag" name; n=$REPLY
_su_xattr "$tag" edition; e=$REPLY
_su_xattr "$tag" edition-old && o=$REPLY || o=-
_su_xattr "$tag" arch; a=$REPLY
_su_xattr "$tag" repository; r=$REPLY
printf '%s\t%s\t%s\t%s\t%s\t%s\t-\n' "$sec" "$n" "$o" "$e" "$r" "$a" ;;
esac
done
}
}
# dnf: no machine-readable transaction output exists in dnf4; parse the (stable, non-tty) table printed by
# `dnf --assumeno upgrade`. Section headers are col-0 lines ending in ':'; rows start with one space:
# dnf4: " name arch evr repo size unit" , then optionally " replacing old.arch oldevr"
# dnf5: " name arch 0:evr repo size unit", then optionally " replacing old arch 0:oldevr repo size unit"
su_plan_dnf() {
local -a ex=(); local ox=() out l a b c d rest sec=other
local ps= pn= po=- pv= pr= pa= pp=- # pending row (printed when the next row/section/summary arrives)
while [ $# -gt 0 ]; do case $1 in --exclude) ex+=("$2"); shift 2 ;; *) shift ;; esac; done
if [ "${#ex[@]}" -gt 0 ]; then ox=("--exclude=$(IFS=,; echo "${ex[*]}")"); fi
out=$(dnf --assumeno --setopt=skip_if_unavailable=0 upgrade "${ox[@]}" 2>/dev/null) # --assumeno => rc 1 is normal
printf '%s\n' "$out" | grep -q '^Transaction Summary' || return 1
_flush() {
[ -n "$pn" ] || return 0
if [ "$ps" = upgrade ] && [ "$po" = - ]; then # dnf4 prints no "replacing" line for plain upgrades
po=$(rpm -q --qf '%|EPOCH?{%{EPOCH}:}|%{VERSION}-%{RELEASE}\n' "$pn.$pa" 2>/dev/null | LC_ALL=C sort -V | tail -n1); po=${po#0:}; : "${po:=-}"
fi
printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\n' "$ps" "$pn" "$po" "$pv" "$pr" "$pa" "$pp"; pn=; po=-; pp=-
}
while IFS= read -r l; do
case $l in
'Transaction Summary'*) break ;;
[A-Z]*:) _flush
case $l in Upgrading*) sec=upgrade ;; Installing*) sec=install ;; Removing*) sec=remove ;;
Downgrading*) sec=downgrade ;; Reinstalling*) sec=reinstall ;; Skipping*) sec=skipped ;; *) sec=other ;; esac ;;
' '*)
read -r a b c d rest <<<"$l"
case $a in
Package|=*|'') ;;
replacing)
if [ -n "$d" ]; then c=${d#0:}; else b=${b%.*}; c=${c#0:}; fi # dnf5: name arch evr repo ; dnf4: name.arch evr
if [ "$sec" = upgrade ]; then po=$c; else pp=$b; fi ;;
*) _flush; ps=$sec; pn=$a; pa=$b; pv=${c#0:}; pr=$d ;;
esac ;;
esac
done <<<"$out"
_flush
}
su_plan() {
case "$(su_backend)" in dnf) su_plan_dnf "$@" ;; zypper)
local -a ex=(); while [ $# -gt 0 ]; do case $1 in --exclude) ex+=("$2"); shift 2 ;; *) shift ;; esac; done
su_plan_zypper "${ex[@]}" ;; esac
}
# ---------------------------------------------------------------- 8. remove (+ unneeded dependencies)
# dnf: clean_requirements_on_remove=1 is the default on dnf4 and dnf5 -> unneeded deps go too.
# (A dependency installed via plain `rpm -i` is NOT considered unneeded; only deps installed by dnf are.)
# Exit status is 0 even if the package did not exist -> always verify with rpm -q.
# zypper: --clean-deps (-u). `remove` of an unknown name exits 104.
su_remove() {
case "$(su_backend)" in
dnf) dnf -y remove "$@" ;;
zypper) zypper --non-interactive remove --clean-deps "$@" ;;
esac
}
discovery/rpm/proof.sh
Executable
+175
View File
@@ -0,0 +1,175 @@
#!/usr/bin/env bash
# SPDX-License-Identifier: GPL-2.0-or-later
# Copyright (C) 2026 Bryan Joshua Pedini
# proof.sh - runs lib-rpm.sh against the fixture and asserts the behaviour documented in rpm.md.
# docker run --rm -i -v <project>/discovery/rpm:/d:ro <image> bash /d/proof.sh
# Prints PASS/FAIL lines + sample output; exit code = number of failures.
export LC_ALL=C
D=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
now() { printf '%s' "${EPOCHREALTIME/./}"; } # microseconds
T_START=$(now)
FAILS=0
pass() { printf 'PASS %s\n' "$1"; }
fail() { printf 'FAIL %s\n' "$1"; FAILS=$((FAILS+1)); }
check() { local name=$1; shift; if "$@" >/dev/null 2>&1; then pass "$name"; else fail "$name"; fi; }
eq() { if [ "$2" = "$3" ]; then pass "$1"; else fail "$1: got [$2] want [$3]"; fi; }
exec 3>&1 # fd 3 = real stdout, so tm's timing is not swallowed by redirections
tm() { local t0=$(now); "$@"; local rc=$?; printf ' (took %d ms)\n' $(( ($(now)-t0)/1000 )) >&3; return $rc; }
sec() { printf '\n== %s\n' "$*"; }
sec "fixture"
t0=$(now); SU_FIXTURE_EXTRAS=1 bash "$D/fixture.sh" 2>&1 | sed 's/^/ /' | tail -4; [ "${PIPESTATUS[0]}" -eq 0 ] || { echo "FIXTURE FAILED"; exit 99; }
FIXTURE_MS=$(( ($(now)-t0)/1000 ))
. "$D/lib-rpm.sh"
. /etc/os-release
BACKEND=$(su_backend)
echo "image=$PRETTY_NAME ID=$ID backend=$BACKEND dnf_major=$([ $BACKEND = dnf ] && su_dnf_major || echo -) zypper_verb=$([ $BACKEND = zypper ] && su_zypper_verb || echo -)"
sec "1. refresh"
t0=$(now); su_refresh; rc=$?; REFRESH_MS=$(( ($(now)-t0)/1000 )); eq "su_refresh exit code" "$rc" 0; echo " (took $REFRESH_MS ms)"
sec "2. upgradable list (name old new repo arch)"
t0=$(now); su_upgradable > /tmp/up.tsv; rc=$?; LIST_MS=$(( ($(now)-t0)/1000 )); eq "su_upgradable exit code" "$rc" 0
echo " (took $LIST_MS ms; $(wc -l </tmp/up.tsv) rows) first 5 rows:"; head -5 /tmp/up.tsv | cat -A | sed 's/^/ /'
for p in a b c; do
arch=noarch; [ $p = c ] && arch=$(rpm -q --qf '%{ARCH}' su-dummy-c)
grep -q -x -F "su-dummy-$p"$'\t'"1.0-1"$'\t'"2.0-1"$'\t'"su-dummy"$'\t'"$arch" /tmp/up.tsv && pass "row su-dummy-$p 1.0-1 -> 2.0-1 [su-dummy] $arch" || fail "row su-dummy-$p missing"
done
check "no su-dummy-d (not upgradable)" test "$(grep -c '^su-dummy-d' /tmp/up.tsv)" -eq 0
check "no '.arch' suffix in name column" test "$(cut -f1 /tmp/up.tsv | grep -c '\.\(noarch\|x86_64\|aarch64\)$')" -eq 0
sec "3. summary + description (candidate if upgradable, else installed)"
su_describe su-dummy-a > /tmp/d_a.txt; echo "--- su-dummy-a (candidate):"; sed 's/^/ /' /tmp/d_a.txt
eq "candidate summary" "$(head -n1 /tmp/d_a.txt)" "skeptical-updater dummy su-dummy-a (v2.0)"
check "candidate description has 2nd paragraph" grep -q 'Second paragraph of su-dummy-a 2.0' /tmp/d_a.txt
check "paragraph break preserved" test "$(sed -n 3p /tmp/d_a.txt)" = ""
su_describe su-dummy-d > /tmp/d_d.txt; echo "--- su-dummy-d (installed only):"; sed 's/^/ /' /tmp/d_d.txt
eq "installed-only summary" "$(head -n1 /tmp/d_d.txt)" "skeptical-updater dummy su-dummy-d (v1.0)"
rpm -qi su-dummy-a | sed -n '/^Summary/p' | sed 's/^/ rpm -qi: /'
sec "4. installed reverse dependencies"
eq "rdeps su-dummy-b" "$(su_rdeps su-dummy-b | tr '\n' ' ')" "su-dummy-a su-dummy-d "
eq "rdeps su-dummy-a" "$(su_rdeps su-dummy-a | tr '\n' ' ')" "su-dummy-d "
eq "rdeps su-dummy-c (only via rich dep (c if b))" "$(su_rdeps su-dummy-c | tr '\n' ' ')" "su-dummy-d "
eq "rdeps su-dummy-d (leaf)" "$(su_rdeps su-dummy-d | tr '\n' ' ')" ""
n_mine=$(su_rdeps bash | wc -l); n_naive=$(rpm -q --qf '%{NAME}\n' --whatrequires bash 2>/dev/null | sort -u | wc -l)
echo " bash: su_rdeps=$n_mine naive 'rpm -q --whatrequires bash'=$n_naive"
provider_sh=$(rpm -q --whatprovides --qf '%{NAME}\n' /bin/sh | head -n1)
check "su_rdeps($provider_sh) finds su-dummy-d via file dep /bin/sh" bash -c ". $D/lib-rpm.sh; su_rdeps $provider_sh | grep -qx su-dummy-d"
[ "$n_mine" -gt "$n_naive" ] && pass "su_rdeps(bash) > naive rpm --whatrequires" || fail "su_rdeps(bash) not > naive"
if [ "$BACKEND" = dnf ]; then
dnf -q repoquery --installed --whatrequires bash --queryformat $'%{name}\n' 2>/dev/null | sed '/^$/d' | sort -u > /tmp/native_rd.txt
su_rdeps bash > /tmp/mine_rd.txt; eq "su_rdeps(bash) == dnf repoquery --installed --whatrequires" "$(cat /tmp/mine_rd.txt | tr '\n' ' ')" "$(cat /tmp/native_rd.txt | tr '\n' ' ')"
else
zypper -q -n search --installed-only -t package --requires-pkg bash 2>/dev/null | grep -E '^[iv ][+ ]? *\|' | cut -d'|' -f2 | tr -d ' ' | grep -v -x Name | sort -u > /tmp/native_rd.txt
su_rdeps bash > /tmp/mine_rd.txt; su_rdeps_recursive bash > /tmp/mine_rrd.txt
echo " zypper se --requires-pkg bash : $(wc -l </tmp/native_rd.txt) pkgs"; echo " su_rdeps bash (direct) : $(wc -l </tmp/mine_rd.txt) pkgs: $(tr '\n' ' ' </tmp/mine_rd.txt)"
echo " su_rdeps_recursive bash : $(wc -l </tmp/mine_rrd.txt) pkgs"
echo " native minus recursive : $(LC_ALL=C comm -23 /tmp/native_rd.txt /tmp/mine_rrd.txt | tr '\n' ' ')"
fi
eq "su_rdeps_recursive(su-dummy-b)" "$(su_rdeps_recursive su-dummy-b | tr '\n' ' ')" "su-dummy-a su-dummy-d "
eq "su_rdeps_recursive(su-dummy-d) (leaf)" "$(su_rdeps_recursive su-dummy-d | tr '\n' ' ')" ""
sec "5. recursive installed dependency closure"
tm su_closure su-dummy-d > /tmp/clo_d.txt
echo " closure(su-dummy-d): $(wc -l </tmp/clo_d.txt) pkgs: $(head -c 300 /tmp/clo_d.txt | tr '\n' ' ')..."
for p in su-dummy-a su-dummy-b su-dummy-c glibc; do grep -qx "$p" /tmp/clo_d.txt && pass "closure(d) contains $p" || fail "closure(d) missing $p"; done
provider_sh=$(rpm -q --whatprovides --qf '%{NAME}\n' /bin/sh | head -n1); grep -qx "$provider_sh" /tmp/clo_d.txt && pass "closure(d) contains $provider_sh (provider of file dep /bin/sh)" || fail "closure(d) missing $provider_sh"
! grep -qx 'su-dummy-d' /tmp/clo_d.txt && pass "closure(d) excludes root" || fail "closure(d) contains root"
grep -q 'rpmlib' /tmp/clo_d.txt && fail "closure contains rpmlib" || pass "no rpmlib(...) leakage"
eq "closure(su-dummy-a)" "$(su_closure su-dummy-a | tr '\n' ' ')" "su-dummy-b "
if [ "$BACKEND" = dnf ] && [ "$(su_dnf_major)" = 4 ]; then
dnf -q repoquery --installed --requires --resolve --recursive --queryformat $'%{name}\n' su-dummy-d 2>/dev/null | sed '/^$/d' | sort -u > /tmp/clo_native.txt
eq "closure(d) == dnf4 repoquery --requires --resolve --recursive" "$(tr '\n' ' ' </tmp/clo_d.txt)" "$(tr '\n' ' ' </tmp/clo_native.txt)"
fi
if [ "$BACKEND" = dnf ] && [ "$(su_dnf_major)" = 5 ]; then
dnf -q repoquery --installed --requires --resolve --recursive su-dummy-d >/dev/null 2>&1; echo " dnf5 repoquery --requires --resolve --recursive -> rc=$? (unsupported)"
fi
sec "6. upgrade with per-run exclusion (a,b excluded) -- c must upgrade, a,b must stay"
if [ $BACKEND = dnf ]; then RESTRICT=(--disablerepo='*' --enablerepo=su-dummy); else RESTRICT=(); fi
LOCKS_BEFORE=$( [ -e /etc/zypp/locks ] && cksum < /etc/zypp/locks || echo absent )
tm su_upgrade --exclude su-dummy-a --exclude su-dummy-b -- "${RESTRICT[@]}" > /tmp/up_ex.log 2>&1; rc=$?
eq "exit code of excluded upgrade" "$rc" 0
eq "versions after excluded upgrade" "$(rpm -q --qf '%{NAME}=%{VERSION} ' su-dummy-a su-dummy-b su-dummy-c)" "su-dummy-a=1.0 su-dummy-b=1.0 su-dummy-c=2.0 "
if [ $BACKEND = zypper ]; then
LOCKS_AFTER=$( [ -e /etc/zypp/locks ] && cksum < /etc/zypp/locks || echo absent )
eq "/etc/zypp/locks untouched ($LOCKS_BEFORE)" "$LOCKS_AFTER" "$LOCKS_BEFORE"
check "no leftover temp zypp dirs" bash -c 'ls /tmp | grep -q "^tmp\." && exit 1 || exit 0'
fi
su_upgradable | cut -f1,2,3 | grep '^su-dummy' | sed 's/^/ still upgradable: /'
check "a and b still listed as upgradable" bash -c ". $D/lib-rpm.sh; su_upgradable | cut -f1 | grep -c '^su-dummy-[ab]$' | grep -qx 2"
echo "--- now without exclusions"
tm su_upgrade -- "${RESTRICT[@]}" > /tmp/up_all.log 2>&1; rc=$?; eq "exit code of plain upgrade" "$rc" 0
eq "versions after full upgrade" "$(rpm -q --qf '%{NAME}=%{VERSION} ' su-dummy-a su-dummy-b su-dummy-c)" "su-dummy-a=2.0 su-dummy-b=2.0 su-dummy-c=2.0 "
check "nothing left for su-dummy-*" test "$(su_upgradable | grep -c '^su-dummy')" -eq 0
sec "7. remove (+ unneeded deps)"
if [ $BACKEND = dnf ]; then dnf -y -q install su-dummy-r >/dev/null 2>&1; else zypper -n -q install su-dummy-r >/dev/null 2>&1; fi
eq "installed r and s" "$(rpm -q --qf '%{NAME} ' su-dummy-r su-dummy-s)" "su-dummy-r su-dummy-s "
su_remove su-dummy-r >/tmp/rm.log 2>&1; rc=$?; eq "remove exit code" "$rc" 0
eq "r AND its auto-installed dep s removed" "$(rpm -q su-dummy-r su-dummy-s 2>&1 | sed 's/ is not installed//;s/^package //' | tr '\n' ' ')" "su-dummy-r su-dummy-s "
su_remove su-dummy-a >/tmp/rm2.log 2>&1
eq "rpm-installed dep b NOT removed with a (not marked auto-installed)" "$(rpm -q su-dummy-b)" "su-dummy-b-2.0-1.noarch"
su_remove no-such-pkg-xyz >/tmp/rm3.log 2>&1; echo " remove of unknown pkg -> exit $?"
sec "8. fixture re-run resets state"
SU_FIXTURE_EXTRAS=1 bash "$D/fixture.sh" >/dev/null 2>&1; su_upgradable > /tmp/up2.tsv
check "after re-run a,b,c upgradable again" test "$(grep -c '^su-dummy-[abc] 1.0-1 2.0-1' /tmp/up2.tsv)" -eq 3
sec "9. plan preview (display only) incl. an obsoleting package"
TOP=/var/tmp/su-fixture; REPO=/var/lib/su-dummy-repo
mkp() { # mkp name ver [extra spec header lines...] -> builds noarch rpm, echoes path
local n=$1 v=$2; shift 2; local f=$TOP/SPECS/$n-$v.spec
{ echo "Name: $n"; echo "Version: $v"; echo "Release: 1"; echo "Summary: dummy $n"; echo "License: MIT"; echo "BuildArch: noarch"
local l; for l in "$@"; do echo "$l"; done
echo '%description'; echo "d"; echo '%install'; echo 'mkdir -p %{buildroot}/usr/share/su-dummy'; echo "echo $n > %{buildroot}/usr/share/su-dummy/$n"
echo '%files'; echo "/usr/share/su-dummy/$n"; } > "$f"
rpmbuild -bb --quiet --define "_topdir $TOP" "$f" >/dev/null 2>&1; ls "$TOP"/RPMS/noarch/$n-$v-1.*.rpm
}
rpm -Uvh "$(mkp su-dummy-old 1.0)" >/dev/null
cp "$(mkp su-dummy-new 1.0 'Obsoletes: su-dummy-old < 2' 'Provides: su-dummy-old = 2')" "$REPO"/ && createrepo_c --quiet --update "$REPO" >/dev/null
su_refresh
su_plan --exclude su-dummy-a > /tmp/plan.tsv; rc=$?; eq "su_plan exit code" "$rc" 0
echo " su_plan --exclude su-dummy-a (section name old new repo arch replaces), su-dummy rows only:"; grep -E $'\tsu-dummy-' /tmp/plan.tsv | sed 's/^/ /'
check "plan: b upgrade 1.0-1 -> 2.0-1" grep -q -x -F $'upgrade\tsu-dummy-b\t1.0-1\t2.0-1\tsu-dummy\tnoarch\t-' /tmp/plan.tsv
check "plan: excluded su-dummy-a is absent" test "$(grep -c $'\tsu-dummy-a\t' /tmp/plan.tsv)" -eq 0
check "plan: obsoleting install of su-dummy-new is visible" grep -q $'^install\tsu-dummy-new\t' /tmp/plan.tsv
echo " (upgradable list does NOT show the obsoleter:) $(su_upgradable | cut -f1 | grep -c '^su-dummy-new$') row(s) for su-dummy-new"
rpm -e su-dummy-old >/dev/null 2>&1
if [ $BACKEND = zypper ]; then
sec "10. zypper lock save/restore recipe (su_zypper_excluding_snapshot)"
zypper -n -q addlock -m "user lock" su-dummy-d >/dev/null
sum() { [ -e /etc/zypp/locks ] && { cksum < /etc/zypp/locks; stat -c %Y /etc/zypp/locks; } | tr '\n' ' ' || echo absent; }
B=$(sum); echo " before: $B"
su_zypper_excluding_snapshot su-dummy-a su-dummy-b -- "$(su_zypper_verb)" --dry-run > /tmp/snap.log 2>&1; rc=$?
eq "snapshot recipe exit code (dry-run)" "$rc" 0
eq "locks file byte-identical + same mtime after normal run" "$(sum)" "$B"
check "user lock still present afterwards" grep -q 'solvable_name: su-dummy-d' /etc/zypp/locks
check "temporary locks are gone" test "$(grep -c 'solvable_name: su-dummy-[ab]$' /etc/zypp/locks)" -eq 0
echo "--- why not addlock + removelock: a pre-existing user lock on the same name is destroyed"
zypper -n -q addlock su-dummy-a >/dev/null # the 'user' lock on su-dummy-a
zypper -n -q removelock su-dummy-a >/dev/null
check "NAIVE removelock destroyed the user's own lock on su-dummy-a (why we snapshot)" test "$(grep -c 'solvable_name: su-dummy-a$' /etc/zypp/locks)" -eq 0
zypper -n -q addlock su-dummy-a >/dev/null; B3=$(sum)
su_zypper_excluding_snapshot su-dummy-a -- "$(su_zypper_verb)" --dry-run >/dev/null 2>&1
eq "snapshot recipe keeps pre-existing lock on su-dummy-a" "$(sum)" "$B3"
echo "--- file absent before => absent after (removelock would leave a 0-byte file)"
rm -f /etc/zypp/locks
su_zypper_excluding_snapshot su-dummy-a -- "$(su_zypper_verb)" --dry-run >/dev/null 2>&1
eq "locks file absent after" "$(sum)" absent
echo "--- SIGTERM in the middle of the run => trap restores"
zypper -n -q addlock -m "user lock" su-dummy-d >/dev/null; B4=$(sum)
zypper() { if [ "$3" = "$(su_zypper_verb)" ] || [ "$2" = "$(su_zypper_verb)" ]; then kill -TERM $BASHPID; sleep 5; else command zypper "$@"; fi; }
su_zypper_excluding_snapshot su-dummy-a su-dummy-b -- "$(su_zypper_verb)" > /dev/null 2>&1; rc=$?
unset -f zypper
eq "killed run exit code (143 = 128+SIGTERM)" "$rc" 143
eq "locks restored after SIGTERM" "$(sum)" "$B4"
fi
TOTAL_MS=$(( ($(now)-T_START)/1000 ))
printf '\n== timings: fixture=%d ms refresh=%d ms list=%d ms total=%d ms\n' "$FIXTURE_MS" "$REFRESH_MS" "$LIST_MS" "$TOTAL_MS"
printf '== RESULT: %d failure(s)\n' "$FAILS"
exit "$FAILS"