pacman-debian 7.3.11 → 7.3.14

package/docs/en/yay-aur.md

@@ -0,0 +1,65 @@
+# libalpm & yay / AUR
+
+## libalpm C Library (libpac4deb)
+
+A C library at `lib/pac4deb/` that implements the libalpm ABI (`alpm.h`),
+allowing Go-based AUR helpers like `yay` to work on Debian without
+modification. It reads:
+
+- Local database (`/var/lib/pacman-debian/local/`) — packages installed by
+  pacman-debian
+- dpkg status (`/var/lib/dpkg/status`) — system packages from apt/dpkg
+- Sync databases (`/var/cache/pacman-debian/packages/*/` — JSONL chunks)
+
+Over 200 stubs are provided for rarely-used functions.
+
+### Key Implementation Details
+
+- **packages.idx binary search (C)**: `alpm_db_get_pkg` and
+  `alpm_find_dbs_satisfier` use binary search on the sorted index, then read
+  a single JSONL line by byte offset — no full JSONL loading.
+- **Auto-register sync DBs**: `ensure_syncdbs` scans
+  `/var/cache/pacman-debian/packages/` on first `alpm_get_syncdbs`,
+  registering all available repos lazily.
+- **Package DB pointer**: `pkg_internal.db` field tracks owning database;
+  `alpm_pkg_get_db` returns it, preventing `DB().Name()` nil dereference.
+- **idx-based search**: `alpm_db_search` scans index lines for pattern
+  matching instead of loading all packages. ~1.5s for -Ss with 6 repos / 15k
+  packages.
+- **dpkg Provides parsing**: `load_dpkg_status` reads the `Provides:` field
+  from dpkg status, so Debian packages that declare virtual names
+  (e.g. `7zip` → `p7zip`) are discoverable by yay via
+  `alpm_pkg_has_provide`.
+- **Local DB fallback**: `alpm_find_dbs_satisfier` searches the local
+  database after sync DBs, matching both package names and provides.
+- **find_in_idx provides scan**: After binary search by package name fails,
+  scans the `provides` column of `packages.idx` for sync DB provides.
+- **dpkg -S fallback**: For `lib*.so` SONAMEs not found anywhere, forks
+  `dpkg -S` to locate the owning Debian package at runtime.
+- **Debian alternatives**: Checks `/etc/alternatives/` for `sh`, `awk`, `vi`,
+  `editor` etc. and adds virtual provides to the owning package.
+
+### Build
+
+```bash
+make -C lib/pac4deb
+sudo make -C lib/pac4deb install
+```
+
+## yay / AUR Support
+
+`yay` works with `pacman-debian` through the bundled libalpm:
+
+```bash
+# Install yay (Go required)
+sudo apt install golang-go
+git clone https://aur.archlinux.org/yay.git /tmp/yay
+cd /tmp/yay && go build -o /usr/local/bin/yay
+
+# Use with pacman-debian (PACMAN env var detected automatically)
+yay -Ss ponysay
+sudo -E yay -S ponysay
+```
+
+Note: AUR packages that depend on `python` (not `python3`) are resolved
+automatically via paclink's `python → python3` mapping, created during setup.

package/docs/zh-CN/architecture.md

@@ -0,0 +1,171 @@
+# 架构
+
+## 源文件结构
+
+```
+src/
+├── cli/
+│   ├── pacman.ts            # CLI 参数解析和分发
+│   ├── paclink.ts           # 虚拟包链接管理
+│   ├── update-ca-trust.ts   # Arch 兼容 CA 证书更新器
+│   ├── archlinux-java.ts    # Arch 兼容 Java 环境管理器
+│   └── fix_default.ts       # Arch 兼容默认 JDK 助手
+├── core/                    # 包格式解析器、依赖引擎
+│   ├── ar.ts                # ar 归档解析器
+│   ├── tar.ts               # tar 提取器
+│   ├── deb.ts               # .deb 包解析器
+│   ├── pkgfile.ts           # .pkg.tar.zst 解析器
+│   ├── compress.ts          # gz/xz 解压缩
+│   ├── control.ts           # Debian control 文件解析器
+│   └── deps.ts              # 依赖解析引擎
+├── db/
+│   ├── localdb.ts           # 目录式本地包数据库
+│   ├── database.ts          # 带事务的 DB 封装
+│   └── dpkg-compat.ts       # dpkg 状态文件读写
+├── ops/
+│   ├── install.ts           # 包安装
+│   ├── remove.ts            # 包删除
+│   ├── query.ts             # 所有 -Q 查询
+│   └── upgrade.ts           # 同步 + 升级流程
+├── repo/
+│   ├── repository.ts        # 仓库同步、下载、JSONL 缓存
+│   └── config.ts            # pacman.conf 解析器（支持 Include）
+├── scripts/
+│   └── setup.ts             # 交互式安装脚本
+├── makepkg/
+│   ├── index.ts             # makepkg 主入口
+│   ├── pkgbuild.ts          # PKGBUILD 解析器
+│   ├── source.ts            # 源码下载/解压
+│   ├── build.ts             # build()/package() 执行
+│   └── printsrcinfo.ts      # .SRCINFO 生成
+├── ui/                      # 用户界面（提示、格式化）
+└── index.ts                 # 入口
+```
+
+```
+lib/pac4deb/                 # libalpm C 库
+├── Makefile                 # 用 gcc 构建，目标 libalpm.so
+├── include/
+│   ├── alpm.h               # 公共 libalpm API 头文件
+│   └── alpm_list.h          # 链表头文件
+└── src/
+    ├── libalpm.c            # 核心实现（handle、db、pkg、JSON 解析器）
+    ├── stubs_manual.c       # ~200 个不常用函数的桩实现
+    └── alpm_list.c          # 链表实现
+```
+
+## 数据库
+
+### 本地数据库：`/var/lib/pacman-debian/local/`
+
+采用与 Arch Linux 本地 DB 一致的目录-包格式：
+
+```
+/var/lib/pacman-debian/local/
+├── index.json       # 包名 → 目录映射（base64 编码路径）
+├── by-name/
+│   ├── fastfetch -> ../fastfetch-2.64.2-2/
+│   └── ...
+├── fastfetch-2.64.2-2/
+│   ├── desc          # JSON 元数据（名称、版本、依赖、大小等）
+│   └── files         # 文件清单
+└── ...
+```
+
+### dpkg 兼容
+
+通过 `dpkg` 或 `apt` 安装的包在查询时直接从 `/var/lib/dpkg/status` 读取
+（按 mtime 缓存）。`pacman-debian` 安装包时会同时写入 dpkg 兼容的条目。
+
+### 仓库缓存：`/var/cache/pacman-debian/packages/`
+
+每个仓库以 JSON Lines 块形式缓存（每个 `.jsonl` 文件 5000 个包）。
+同步时还会生成全局排序的 `packages.idx` 索引。
+
+```
+/var/cache/pacman-debian/packages/
+├── bookworm/
+│   ├── 00000.jsonl   # JSON Lines, ~5000 包/块
+│   ├── ...
+│   └── packages.idx  # 全局排序索引 (~200KB)
+└── ...
+```
+
+#### 内存索引缓存
+
+`packages.idx` 在首次读取后驻留内存，按仓库名 + mtime 缓存：
+
+```
+_idxCache = new Map<string, IdxEntry>();
+IdxEntry { lines: string[], mtime: number, providesIndex: Map<string, Array<{chunkFile, offset}>> }
+```
+
+- 后续操作直接读内存，不重复读盘
+- `providesIndex` 是倒排索引，O(1) 查找
+- `pacman -Syy` 清空缓存
+- 增量同步后自动重新加载
+
+### 查找路径
+
+| 操作 | 方法 | 说明 |
+|------|------|------|
+| `-S <pkg>` / `-Qo` | 二分搜索 `packages.idx` → seek JSONL | O(log N) |
+| `-Ss` | 逐行扫索引（包名+描述）→ seek JSONL | 不解析 JSON |
+| `-Sl` | 扫索引 → seek 每个包 | 懒加载 |
+| 依赖 provides | 扫索引 provides 字段 | 仅索引 |
+| `-Qi` / `-Ql` | dpkg 状态或本地数据库 | 不涉及缓存 |
+
+## 依赖引擎
+
+依赖解析器（`src/core/deps.ts`）支持：
+
+- 带版本约束的包名解析（`>=`、`<=`、`=`）
+- OR 依赖（`|`）
+- 架构限定符（如 `:arm64`）
+- Debian（逗号分隔）和 Arch（空格分隔）两种格式
+- BFS 解析，带预加载 DB 状态
+- 冲突检测
+- 系统包保护（glibc、libc6 等）
+
+### 性能优化
+
+| 技术 | 说明 |
+|------|------|
+| **idx 内存缓存** | 二分搜索直接在内存中进行 |
+| **provides 倒排索引** | `Map.get()` O(1) 查找 |
+| **顺序 BFS + 指针游标** | 避免数组塌缩 |
+| **keep-alive HTTP** | 复用 TCP/TLS 连接 |
+| **异步解压 .gz** | 不阻塞事件循环 |
+| **304 条件请求** | 跳过未变更仓库 |
+
+### 删除时的依赖处理
+
+| 操作 | 逻辑 |
+|------|------|
+| `-R` | 仅删除指定包 |
+| `-Rs` | 删除包 + 递归查找孤儿，逆拓扑序 |
+| `-Rc` | 级联：找出所有依赖目标包的包 |
+| `-Rsc` | 递归 + 级联组合 |
+| `-Rn` | 备份 conffiles 后删除 |
+
+## 仓库支持
+
+- **Debian/Ubuntu**：读取 `Packages.gz` / `Packages.xz`
+- **Arch Linux**：读取 `db.tar.gz`，下载 `.pkg.tar.zst` 解包安装
+- **Arch ARM**：需要 glibc 2.38+（Debian 12 自带 2.36），请用 `makepkg` 本地编译
+
+## 项目状态
+
+主要功能：
+
+- **性能**：`packages.idx` 索引实现亚秒级查找
+- **并行同步**：多仓库并发下载
+- **多语言**：中英文完整本地化
+- **颜色输出**：匹配官方 pacman 配色
+- **权限分离**：查询无需 root
+- **链接系统**（`paclink`）：Debian→Arch 虚拟包名映射
+
+主要限制：
+
+- **Arch ARM 二进制仓库需要 glibc 2.38+** — Debian 12 自带 2.36
+- **yay/AUR**：复杂 AUR 依赖链可能因包名差异失败

package/docs/zh-CN/configuration.md

@@ -0,0 +1,80 @@
+# 配置
+
+配置文件：`/etc/pacman-debian/pacman.conf`
+
+使用纯 Arch Linux pacman 语法，支持 `Include` 指令。仓库特有键
+（`Type`、`Dist`、`Components` 等）放在 `/etc/pacman.d/` 的包含文件中。
+
+## 示例
+
+```ini
+[options]
+Architecture = auto
+
+[bookworm]
+Include = /etc/pacman.d/debian-bookworm
+
+[extra]
+Include = /etc/pacman.d/arch-extra
+```
+
+包含文件 `/etc/pacman.d/debian-bookworm`：
+
+```
+Server = https://mirrors.tuna.tsinghua.edu.cn/debian
+Type = debian
+Dist = bookworm
+Components = main contrib non-free non-free-firmware
+```
+
+Arch 仓库包含文件 `/etc/pacman.d/arch-extra`：
+
+```
+Server = http://mirror.archlinuxarm.org/$arch/$repo
+Type = arch
+Architecture = auto
+```
+
+## 仓库类型
+
+### Debian
+
+| 键 | 必需 | 说明 |
+|-----|------|------|
+| `Server` | 是 | 镜像 URL（支持 `$repo`、`$arch` 变量替换） |
+| `Type` | 是 | 必须为 `debian` |
+| `Dist` | 是 | 发行版代号（如 `bookworm`、`trixie`） |
+| `Components` | 是 | 空格分隔的组件列表（`main contrib non-free`） |
+
+### Arch
+
+| 键 | 必需 | 说明 |
+|-----|------|------|
+| `Server` | 是 | 镜像 URL（支持 `$repo`、`$arch` 变量替换） |
+| `Type` | 是 | 必须为 `arch` |
+| `Architecture` | 否 | 设为 `auto` 以匹配系统架构 |
+
+## 符号链接
+
+安装时会创建 `/etc/pacman.conf` → `/etc/pacman-debian/pacman.conf` 符号链接，
+方便硬编码该路径的工具（如 yay）使用。
+
+## 查看解析后的配置
+
+```bash
+$ pacman-conf
+# pacman-debian configuration
+[options]
+Architecture = auto
+
+[bookworm]
+Server = https://mirrors.tuna.tsinghua.edu.cn/debian
+Type = debian
+Dist = bookworm
+Components = main contrib non-free non-free-firmware
+
+[extra]
+Server = http://mirror.archlinuxarm.org/$arch/$repo
+Type = arch
+Architecture = auto
+```

package/docs/zh-CN/installation.md

@@ -0,0 +1,65 @@
+# 安装说明
+
+## 环境要求
+
+- Node.js 18+
+- Debian 系发行版（Debian、Ubuntu、Armbian、Linux Mint 等）
+- 写操作需要 root 权限
+- 编译工具：`gcc`、`make`、`ldconfig`（可选，用于 libalpm C 库）
+
+## npm 安装（推荐）
+
+```bash
+npm install -g pacman-debian@latest
+sudo $(which pacman-debian-setup)
+```
+
+> [!WARNING]
+> `npm install -g` **必须**在 `sudo` 或 `root` 用户下运行。
+> 如果使用普通用户安装，Node.js 会将包安装到用户家目录（`~/.npm-global/` 等），
+> 存在被其他用户或脚本篡改、植入恶意内容的风险。请始终使用 `sudo npm install -g`。
+
+### Setup 做了什么
+
+1. 创建默认配置 `/etc/pacman-debian/pacman.conf`
+2. 创建 `/etc/pacman.conf` → `/etc/pacman-debian/pacman.conf` 符号链接
+3. 创建 CLI 符号链接（`pacman`、`makepkg`、`pacman-conf`、`paclink`、`update-ca-trust`、`archlinux-java`、`fix_default`）
+4. 创建 `/var/lib/pacman` → `/var/lib/pacman-debian` 符号链接（fastfetch 检测用）
+5. 安装 Arch 兼容工具（`update-ca-trust`、`archlinux-java`、`fix_default`）
+6. 安装 Arch 兼容 shell 函数（`/etc/profile.d/append_path.sh`）
+7. 注册虚拟 `pacman` 包到 dpkg 状态
+8. 创建默认 paclink 映射（sh → bash、python → python3 等）
+
+## 开发安装
+
+```bash
+git clone https://github.com/xbodwf/pacman-debian.git
+cd pacman-debian
+pnpm install
+pnpm build                # tsc + C 库
+sudo node dist/scripts/setup.js
+```
+
+或手动设置：
+
+```bash
+sudo ln -sf "$PWD/dist/cli/pacman.js" /usr/local/bin/pacman
+sudo ln -sf "$PWD/dist/cli/paclink.js" /usr/local/bin/paclink
+sudo ln -sf "$PWD/dist/scripts/pacman-conf.js" /usr/local/bin/pacman-conf
+sudo ln -sf "$PWD/dist/makepkg/index.js" /usr/local/bin/makepkg
+```
+
+## 首次使用
+
+```bash
+# 同步仓库
+sudo pacman -Sy
+
+# 搜索
+pacman -Ss neofetch
+
+# 安装
+sudo pacman -S neofetch
+```
+
+完整命令参考见[使用文档](usage.md)。

package/docs/zh-CN/makepkg.md

@@ -0,0 +1,32 @@
+# makepkg
+
+独立的 `makepkg` 实现，无需 `base-devel` 或任何 Arch 工具即可从 PKGBUILD
+构建 Arch Linux 包。
+
+```bash
+# 从 PKGBUILD 构建包
+cd /path/to/PKGBUILD/dir
+makepkg --syncdeps --install
+```
+
+## 功能
+
+- 通过 bash sourcing 解析 PKGBUILD
+- 下载并验证源文件
+- 解压归档：`.tar.gz`、`.tar.xz`、`.tar.bz2`、`.tar.zst`、`.zip`
+- 运行 `prepare()`、`build()`、`check()`、`package()`
+- 创建 `.pkg.tar.zst` 归档
+- 通过 `--syncdeps` 安装缺失依赖
+
+## 参数
+
+| 参数 | 说明 |
+|------|------|
+| `-s, --syncdeps` | 通过 pacman 安装缺失依赖 |
+| `-i, --install` | 安装构建好的包 |
+| `-c, --clean` | 打包后清理构建文件 |
+| `-r, --rmdeps` | 构建后删除已安装的依赖 |
+| `-f, --force` | 覆盖已有的包文件 |
+| `-o, --nobuild` | 仅下载和解压源码 |
+| `--nocolor` | 禁用彩色输出 |
+| `--printsrcinfo` | 打印 `.SRCINFO` 并退出 |

package/docs/zh-CN/paclink.md

@@ -0,0 +1,70 @@
+# paclink（包链接管理）
+
+管理持久化的 Debian→Arch 虚拟包名映射。链接存储在本地数据库中，
+仅对 pacman/libalpm 可见，dpkg 不可见。
+
+## 命令
+
+| 命令 | 说明 |
+|------|------|
+| `paclink -Ln <deb> <virt>` | 创建链接：Debian 包 `<deb>` 提供 Arch 虚拟名 `<virt>` |
+| `paclink -L` | 列出所有链接 |
+| `paclink -Ls <关键词>` | 搜索链接 |
+| `paclink -Li <虚拟名>` | 显示链接详情 |
+| `paclink -R <虚拟名>` | 删除链接（不影响 Debian 包） |
+
+## 示例
+
+```bash
+# 映射 dash 提供 sh
+sudo paclink -Ln dash sh
+
+# 映射 python3 提供 python
+sudo paclink -Ln python3 python
+
+# 列出所有映射
+paclink -L
+
+# 搜索含 python 的链接
+paclink -Ls python
+```
+
+## 行为
+
+- 链接以 `repoType: link` 存储在本地 DB
+- 当仓库中存在与链接同名的真包时，真包优先，安装时自动移除链接
+- 链接仅对 pacman 和 libalpm 可见
+
+## 默认链接
+
+Setup 创建的默认映射：
+
+| 虚拟名 | Debian 包 |
+|--------|-----------|
+| sh | bash（或 dash） |
+| python | python3 |
+| zlib | zlib1g |
+| bzip2 | libbz2-1.0 |
+| xz | liblzma5 |
+| zstd | libzstd1 |
+| openssl | libssl-dev |
+| libssl | libssl3t64 |
+| libcrypt | libcrypt1 |
+| libffi | libffi8 |
+| libpcre | libpcre3 |
+| libpcre2 | libpcre2-8-0 |
+| libpng | libpng16-16t64 |
+| libjpeg-turbo | libjpeg62-turbo |
+| freetype2 | libfreetype6 |
+| ncurses | libncursesw6 |
+| readline | libreadline8t64 |
+| sqlite | libsqlite3-0 |
+| expat | libexpat1 |
+| libxml2 | libxml2 |
+| glibc | libc6 |
+| gcc-libs | libgcc-s1 |
+| libstdc++ | libstdc++6 |
+| systemd-libs | libsystemd0 |
+| gnutls | libgnutls30t64 |
+| libcurl | libcurl4t64 |
+| ca-certificates-utils | ca-certificates |

package/docs/zh-CN/usage.md

@@ -0,0 +1,90 @@
+# 使用文档
+
+## 同步（-S）
+
+| 命令 | 说明 |
+|------|------|
+| `pacman -S <pkg>` | 从仓库安装包 |
+| `pacman -Sy` | 刷新包数据库（mtime 检查，24 小时） |
+| `pacman -Syy` | 强制刷新包数据库（清除内存 idx 缓存） |
+| `pacman -Su` | 升级所有已安装的包 |
+| `pacman -Syu` | 刷新数据库并升级 |
+| `pacman -Ss <keyword>` | 搜索仓库 |
+| `pacman -Si <pkg>` | 显示远程包信息 |
+| `pacman -Sl` | 列出仓库中所有包 |
+| `pacman -Sw <pkg>` | 下载包到缓存目录，不安装 |
+| `pacman -Sc` | 删除缓存目录中的包文件，保留仓库元数据 |
+| `pacman -Scc` | 清空整个缓存目录（含仓库 jsonl/idx） |
+| `pacman -Sp <pkg>` | 打印下载 URL（不会安装） |
+
+## 删除（-R）
+
+| 命令 | 说明 |
+|------|------|
+| `pacman -R <pkg>` | 删除包 |
+| `pacman -Rs <pkg>` | 删除包及未使用的依赖 |
+| `pacman -Rn <pkg>` | 删除包及其配置文件 |
+| `pacman -Rns <pkg>` | 删除包、依赖和配置文件 |
+| `pacman -Rc <pkg>` | 级联删除：删除依赖该包的所有包 |
+| `pacman -Rdd <pkg>` | 跳过依赖检查强制删除 |
+| `pacman -Rp <pkg>` | 显示将要删除的内容（干运行） |
+
+支持多目标（`pacman -R a b`）：所有目标合并显示后统一确认。
+
+## 查询（-Q）
+
+| 命令 | 说明 |
+|------|------|
+| `pacman -Q` | 列出所有已安装的包 |
+| `pacman -Qe` | 列出显式安装的包 |
+| `pacman -Qd` | 列出作为依赖安装的包 |
+| `pacman -Qdt` | 列出孤儿包（未使用的依赖） |
+| `pacman -Qi <pkg>` | 显示详细包信息 |
+| `pacman -Ql <pkg>` | 列出包拥有的文件 |
+| `pacman -Qo <file>` | 查询文件属于哪个包 |
+| `pacman -Qs <keyword>` | 搜索已安装的包 |
+| `pacman -Qk [pkg]` | 验证包文件完整性 |
+| `pacman -Qq` | 静默模式：仅输出包名 |
+
+## 其他
+
+| 命令 | 说明 |
+|------|------|
+| `pacman -U <file>` | 安装本地包文件（.deb/.pkg.tar.zst） |
+| `pacman -D --asdeps <pkg>` | 将包标记为依赖 |
+| `pacman -D --asexplicit <pkg>` | 将包标记为显式安装 |
+| `pacman -T <pkg>` | 检查依赖是否满足 |
+| `pacman -F <file>` | 搜索提供该文件的包 |
+| `pacman -V` | 显示版本号 |
+
+## 内置工具
+
+| 命令 | 说明 |
+|------|------|
+| `pacman-conf` | 打印解析后的配置 |
+| `makepkg` | 从 PKGBUILD 构建 Arch 包（见 [makepkg](makepkg.md)） |
+| `pacman-debian-setup` | 交互式安装脚本 |
+| `paclink` | 管理 Debian→Arch 虚拟包名映射（见 [paclink](paclink.md)） |
+| `update-ca-trust` | CA 证书更新器（Arch 兼容，包装 `update-ca-certificates`） |
+| `archlinux-java` | Java 环境管理器：`status`、`get`、`set`、`unset`、`fix` |
+| `fix_default` | 打印当前默认 JDK 短名（Arch Java 包安装脚本使用） |
+
+## 全局参数
+
+| 参数 | 说明 |
+|------|------|
+| `--noconfirm` | 跳过确认提示 |
+| `--confirm` | 始终询问确认（默认） |
+| `--needed` | 不重新安装已是最新的包 |
+| `--noscriptlet` | 不执行安装脚本 |
+| `--print` | 干运行 |
+
+## 配置选项（`pacman.conf [options]`）
+
+| 选项 | 说明 |
+|------|------|
+| `Color` | 启用彩色输出 |
+| `Architecture` | 设置目标架构（默认 `auto`） |
+| `IgnorePkg` | 跳过指定包的升级 |
+
+详见[配置文档](configuration.md)。

package/docs/zh-CN/yay-aur.md

@@ -0,0 +1,44 @@
+# libalpm & yay / AUR 支持
+
+## libalpm C 库（libpac4deb）
+
+位于 `lib/pac4deb/` 的 C 库，实现了 libalpm ABI（`alpm.h`），使基于 Go 的
+AUR 助手（如 yay）无需修改即可在 Debian 上运行。它读取：
+
+- 本地数据库（`/var/lib/pacman-debian/local/`）
+- dpkg 状态（`/var/lib/dpkg/status`）
+- 同步数据库（`/var/cache/pacman-debian/packages/*/`）
+
+提供了 200+ 个不常用函数的桩实现。
+
+### 关键实现细节
+
+- **二分查找**：对排序索引做二分查找，按字节偏移读单行 JSONL
+- **自动注册 sync DB**：首次调用时扫描缓存目录，懒加载注册
+- **dpkg Provides 解析**：读取 dpkg status 的 `Provides:` 字段
+- **本地 DB 后备搜索**：sync DB 搜索失败后搜索本地数据库
+- **dpkg -S 后备**：`lib*.so` SONAME 找不到时通过 `dpkg -S` 查归属
+- **Debian alternatives**：检测 `/etc/alternatives/` 自动添加虚拟 provides
+
+### 构建
+
+```bash
+make -C lib/pac4deb
+sudo make -C lib/pac4deb install
+```
+
+## yay / AUR 支持
+
+```bash
+# 安装 yay（需要 Go）
+sudo apt install golang-go
+git clone https://aur.archlinux.org/yay.git /tmp/yay
+cd /tmp/yay && go build -o /usr/local/bin/yay
+
+# 与 pacman-debian 配合使用（PACMAN 自动识别）
+yay -Ss ponysay
+sudo -E yay -S ponysay
+```
+
+注意：依赖 `python`（而非 `python3`）的 AUR 包可通过 setup 创建的 paclink
+映射 `python → python3` 自动解析。

package/lib/pac4deb/Makefile

@@ -0,0 +1,26 @@
+CC ?= gcc
+CFLAGS ?= -O2 -fPIC
+CFLAGS += -Iinclude -Wno-unused-parameter
+LDFLAGS += -shared -ldl
+
+SRC = $(wildcard src/*.c)
+OBJ = $(SRC:.c=.o)
+TARGET = libalpm.so
+
+.PHONY: all clean install
+
+all: $(TARGET)
+
+$(TARGET): $(OBJ)
+	$(CC) $(CFLAGS) -o $@ $^ $(LDFLAGS)
+
+%.o: %.c
+	$(CC) $(CFLAGS) -c -o $@ $<
+
+clean:
+	rm -f $(TARGET) src/*.o
+
+install: $(TARGET)
+	install -Dm755 $(TARGET) /usr/local/lib/$(TARGET)
+	ldconfig
+	@echo "Installed to /usr/local/lib/$(TARGET)"

package/lib/pac4deb/README.md

@@ -0,0 +1,47 @@
+# pac4deb-libalpm
+
+A drop-in replacement for Arch Linux's `libalpm.so`, reading from pacman-debian's database (`/var/lib/pacman-debian/`). Enables native AUR helpers like `yay`, `expac`, `pkgfile` to run on Debian without modification.
+
+## What is libalpm?
+
+Arch Linux's package management core library (C). `pacman`, `yay`, `expac` and other Arch tools link against it to query databases, resolve dependencies, and manage transactions — all at the C API level rather than through the `pacman` CLI binary.
+
+## How it works
+
+```
+yay ──────┐
+expac ────┤
+pkgfile ──┼─ libalpm.so (this project)
+          │     ├─ reads /var/lib/pacman-debian/status.json
+          │     ├─ reads /var/cache/pacman-debian/packages/*.json
+          │     └─ wraps pacman-debian for transactions
+          │
+          └─ (real libalpm reads /var/lib/pacman/local/*/desc)
+```
+
+Instead of reading Arch's file-based package database, this library reads pacman-debian's JSON database and exposes the same C API. AUR helpers and other libalpm-dependent tools become usable on Debian without porting.
+
+## Build
+
+```bash
+make
+sudo make install
+```
+
+## API Coverage
+
+Implements the most commonly used subset of libalpm's public API:
+
+| Group | Functions |
+|-------|-----------|
+| Handle | `alpm_initialize`, `alpm_release` |
+| Databases | `alpm_db_register_local`, `alpm_db_register_sync`, `alpm_db_unregister_all` |
+| Package access | `alpm_db_get_pkg`, `alpm_db_get_pkgcache` |
+| Package properties | `alpm_pkg_get_name`, `alpm_pkg_get_version`, `alpm_pkg_get_desc`, `alpm_pkg_get_url`, `alpm_pkg_get_arch`, `alpm_pkg_get_builddate`, `alpm_pkg_get_installdate`, `alpm_pkg_get_reason`, `alpm_pkg_get_base64_sig`, `alpm_pkg_free` |
+| Lists | `alpm_list_add`, `alpm_list_remove`, `alpm_list_free`, `alpm_list_count`, `alpm_list_nth`, etc. |
+| Options | `alpm_option_add_cachedir`, `alpm_option_set_dbpath`, `alpm_option_get_localdb`, `alpm_option_get_syncdbs` |
+| Logging | `alpm_logaction`, `alpm_option_set_logfile` |
+
+## License
+
+GNU General Public License v3.0