shenmo
631436e200
新增 APM addons 层功能，允许在 base 环境上叠加额外环境层 添加 amber-pm-addons-maker 工具用于创建 addons 包 修改 amber-pm-convert 支持 --addons 参数 更新相关文档说明 addons 层功能
APM 软件包打包流程
本文档为开发者准备，若您只是想从 deb 软件包打包 APM 软件包，您可以通过 amber-pm-convert 指令进行全自动一键转换。
通过 apm search amber-pm- 即可搜索到所有可用的 base 列表。
APM 软件包结构规范
在阅读前，请确保您对 OverlayFS 有了基本的了解。
OverlayFS 原理解析： https://www.cnblogs.com/arnoldlu/p/13055501.html
OverlayFS 层叠顺序说明
APM 使用 OverlayFS 来管理软件包的文件系统层级，从上到下的层叠顺序为：
-
Upperdir 当前包的可写层：
files/core/ -
Info Layer Override 由
info_layer_override指定的覆盖层，位于所有依赖层之上 -
依赖层 由
info文件递归解析出的所有依赖包 -
Addons 层 由
info_layer_addons和info_layer_addons.d注册的 addons 包，位于对应 base 之上 -
底层 Runtime 最基础的运行时环境（如
amber-pm-bookworm）
这种层叠结构允许上层文件覆盖下层文件，实现灵活、高效的依赖管理与环境定制。
APM 软件包目录结构示例
一个典型的 APM 应用或中层依赖包应当包含以下内容：
├── DEBIAN
│ ├── control
│ └── postinst
└── var
└── lib
└── apm
└── eom
├── entries
│ ├── applications
│ ├── doc
│ ├── glib-2.0
│ └── man
├── files
│ ├── core
│ └── work
├── info
├── info_layer_override # 可选
└── info_env # 可选（高级功能）
DEBIAN 目录说明
包含软件包的基本信息和依赖环境声明。
control 文件示例
Package: eom
Version: 1.26.0-2-apm
Architecture: amd64
Maintainer: APM Converter <apm-convert@spark-app.store>
Depends: amber-pm-bookworm
Installed-Size: 45228
Description: APM converted package from eom
This package was automatically converted from the original deb package.
Based on: amber-pm-bookworm
字段说明：
-
Package 包名，应当唯一。使用转换器时默认与原 deb 包名一致
-
Version 软件包版本号，转换器会自动追加
-apm -
Architecture 架构信息，遵循 dpkg 规范
-
Depends 直接依赖的 base 包名
-
Installed-Size 安装后大小，转换器自动计算
-
Description 软件包描述信息
postinst 文件
#!/bin/bash
PACKAGE_NAME="$DPKG_MAINTSCRIPT_PACKAGE"
if [ "$1" = "remove" ] || [ "$1" = "purge" ]; then
echo "清理卸载残留"
rm -rf "/var/lib/apm/$PACKAGE_NAME"
for username in $(ls /home); do
if [ -d "/home/$username/.apm/$PACKAGE_NAME" ]; then
rm -rf "/home/$username/.apm/$PACKAGE_NAME"
fi
done
else
echo "非卸载，跳过清理"
fi
若无特殊需求，保持该内容即可，用于卸载时清理残留环境。
/var/lib/apm 目录结构说明
该目录包含 APM 软件包的运行环境与元数据。
必须目录
-
files/
core/：upperdir，可写层work/：OverlayFS 工作目录
-
info
- 声明直接依赖的 base 包
- 支持多层递归解析
可选目录 / 文件
-
entries/
applications/：.desktop文件doc/：文档glib-2.0/：GLib 相关文件man/：手册页
⚠
.desktop文件中 必须 添加：X-APM-APPID=包名以允许软件管理器正确识别和管理应用。
info 文件说明（依赖解析）
info 文件用于声明当前包直接依赖的 base 包，每行一个包名：
amber-pm-bookworm-spark-wine10
APM 会递归解析该 base 的 info 文件，直到找到最底层 runtime（如 amber-pm-bookworm）。
使用多层依赖并非强制，但合理拆分 base 能显著减小包体积。 可用的 base 列表可通过：
apm search amber-pm-查看。
info_layer_override 文件（覆盖层）
info_layer_override 是一个可选文件，用于在所有依赖层之上插入额外覆盖层。
使用场景
- 覆盖依赖中的特定库版本（如 mesa）
- 覆盖默认配置文件
- 提供特殊运行环境
规则说明
-
语法与
info完全一致 -
每行一个包名
-
层级位置：
upperdir ↑ info_layer_override ↑ info 递归依赖
示例
info：
amber-pm-bookworm
info_layer_override：
amber-pm-bookworm-mesa
最终 lowerdir 顺序：
amber-pm-bookworm-mesa:amber-pm-bookworm
info_layer_addons / info_layer_addons.d（Addons 层）
info_layer_addons 和 info_layer_addons.d 是 1.3.0+ 引入的标准，用于在 base 之上叠加 addons 层，使所有运行在该 base 上的应用自动继承 addons 环境。
使用场景
- 为所有基于同一 base 的应用统一注入 NVIDIA 驱动
- 为所有基于同一 base 的应用统一更新 Mesa / Vulkan
- 为所有基于同一 base 的应用统一提供 Git、Java、Python 等运行时环境
- 无需修改 base 本身，即可同步变更环境
规则说明
info_layer_addons— 位于 base 包目录下的可选文件，每行一个 addons 包名info_layer_addons.d/— 位于 base 包目录下的可选目录，包含文件名格式为优先级-addons包名的文件- 数字越小优先级越高（排序靠前）
.d目录中的 addons 优先级高于info_layer_addons文件中的 addons- 即使 base 没有
info文件，也可以有info_layer_addons（最底层 base 也可以有 addons） - APM 在运行时自动读取并挂载这些 addons
Addons 包结构
Addons 包是一种特殊的 APM 包，不需要 info 文件和 entries/ 目录：
/var/lib/apm/<base>-<描述>-addons/
├── files
│ ├── core/ # upperdir（addons 的文件内容）
│ └── work/ # OverlayFS 工作目录
Addons 包命名规范
建议格式：<base>-<描述>-addons
示例：
amber-pm-bookworm-nvidia-addonsamber-pm-trixie-mesa-addonsamber-pm-bookworm-java-addons
创建 Addons 包
推荐使用 amber-pm-addons-maker 工具：
# 手动模式（交互式 shell 安装软件后打包）
amber-pm-addons-maker --base amber-pm-bookworm --manual --pkgname amber-pm-bookworm-nvidia-addons
# 自动模式（直接安装 deb 后打包）
amber-pm-addons-maker --base amber-pm-bookworm /path/to/nvidia-driver.deb --pkgname amber-pm-bookworm-nvidia-addons
安装 addons 包后，它会在对应 base 的 info_layer_addons.d/ 目录中自动注册，所有依赖该 base 的应用下次启动时即可自动加载该 addons。
示例
假设 amber-pm-bookworm-nvidia-addons 已安装并注册到 amber-pm-bookworm：
amber-pm-bookworm/info_layer_addons.d/50-amber-pm-bookworm-nvidia-addons：
amber-pm-bookworm-nvidia-addons
应用包 eom 的 info：
amber-pm-bookworm
最终 lowerdir 顺序：
amber-pm-bookworm-nvidia-addons:amber-pm-bookworm
所有运行 apm run eom 的实例都会自动加载 NVIDIA addons。
info_env（环境变量层 · 高级功能）
info_env 是一个 可选的高级特性，用于为 APM 容器运行时提供分层的环境变量配置能力。
功能概述
- 为软件包及其依赖提供环境变量
- 支持 多层叠加
- 上层自动覆盖下层
- 与 OverlayFS 层级顺序完全一致
- 不执行 shell 代码，仅解析键值对，安全可靠
info_env 文件位置
/var/lib/apm/<包名>/info_env
info_env 应用顺序（重要）
环境变量的加载顺序为：
- 底层 runtime 的
info_env - 中间依赖包的
info_env - 当前包的
info_env info_layer_override中包的info_env（最高优先级）
后加载的变量会覆盖之前的同名变量。
info_env 文件格式
每行一条环境变量定义：
KEY=VALUE
示例：
QT_QPA_PLATFORM=dxcb;xcb
LANG=zh_CN.UTF-8
XMODIFIERS="@im=fcitx"
PATH="/custom/bin:$PATH"
规则说明
- 支持分号
; - 支持带引号的值
- 支持引用已有环境变量（如
$PATH） - 支持注释行（
#） - 不允许执行任何 shell 语句
❌ 以下内容将被忽略：
export A=1
rm -rf /
$(whoami)
使用场景示例
- 指定 Qt / GTK 平台插件
- 设置输入法变量
- 调整运行时 PATH / LD_LIBRARY_PATH
- 为特定应用注入兼容性环境变量
APM upperdir 制作流程（手动）
-
安装 APM 并安装所需 base：
sudo apm install amber-pm-xxx -
创建目录结构：
mkdir -p core work ace-env -
挂载 OverlayFS：
sudo mount -t overlay overlay \ -o lowerdir='/var/lib/apm/apm/files/ace-env/var/lib/apm/amber-pm-xxx/files/ace-env',upperdir=core/,workdir=work/ \ ./ace-env -
chroot 进入
ace-env进行安装 -
卸载并打包
APM 软件包测试
fuse-overlayfs -o lowerdir='...',upperdir=core/,workdir=work/ ./ace-env
或直接使用：
apm run 包名
APM 会自动完成：
- 解析
info/info_layer_override - 应用
info_env - 构建 OverlayFS
- 进入容器并运行应用
APM 软件包打包
dpkg-deb --build 软件包目录 输出目录
APM 底层 Base Runtime 构建
详见： https://gitee.com/amber-ce/amber-pm-common
备注
APM 的打包工具与转换器会自动处理绝大多数复杂操作。
手动打包与 info_env 主要用于 特殊运行环境、深度定制或调试用途。