mirror of
https://gitee.com/amber-ce/amber-pm
synced 2026-05-14 02:00:20 +08:00
shenmo
f55dcc023d
新增 APM addons 层功能，允许在 base 环境上叠加额外环境层 添加 amber-pm-addons-maker 工具用于创建 addons 包 修改 amber-pm-convert 支持 --addons 参数 更新相关文档说明 addons 层功能
464 lines
9.9 KiB
Markdown
464 lines
9.9 KiB
Markdown
|
||
|
||
# APM 软件包打包流程
|
||
|
||
本文档为开发者准备，若您只是想从 deb 软件包打包 APM 软件包，您可以通过 `amber-pm-convert` 指令进行全自动一键转换。
|
||
|
||
通过 `apm search amber-pm-` 即可搜索到所有可用的 base 列表。
|
||
|
||
---
|
||
|
||
## APM 软件包结构规范
|
||
|
||
在阅读前，请确保您对 OverlayFS 有了基本的了解。
|
||
|
||
OverlayFS 原理解析：
|
||
[https://www.cnblogs.com/arnoldlu/p/13055501.html](https://www.cnblogs.com/arnoldlu/p/13055501.html)
|
||
|
||
---
|
||
|
||
## OverlayFS 层叠顺序说明
|
||
|
||
APM 使用 OverlayFS 来管理软件包的文件系统层级，从上到下的层叠顺序为：
|
||
|
||
1. **Upperdir**
|
||
当前包的可写层：`files/core/`
|
||
|
||
2. **Info Layer Override**
|
||
由 `info_layer_override` 指定的覆盖层，位于所有依赖层之上
|
||
|
||
3. **依赖层**
|
||
由 `info` 文件递归解析出的所有依赖包
|
||
|
||
4. **Addons 层**
|
||
由 `info_layer_addons` 和 `info_layer_addons.d` 注册的 addons 包，位于对应 base 之上
|
||
|
||
5. **底层 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` 是一个可选文件，用于在**所有依赖层之上**插入额外覆盖层。
|
||
|
||
### 使用场景
|
||
|
||
1. 覆盖依赖中的特定库版本（如 mesa）
|
||
2. 覆盖默认配置文件
|
||
3. 提供特殊运行环境
|
||
|
||
### 规则说明
|
||
|
||
* 语法与 `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-addons`
|
||
- `amber-pm-trixie-mesa-addons`
|
||
- `amber-pm-bookworm-java-addons`
|
||
|
||
### 创建 Addons 包
|
||
|
||
推荐使用 `amber-pm-addons-maker` 工具：
|
||
|
||
```bash
|
||
# 手动模式（交互式 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 应用顺序（重要）
|
||
|
||
环境变量的加载顺序为：
|
||
|
||
1. 底层 runtime 的 `info_env`
|
||
2. 中间依赖包的 `info_env`
|
||
3. 当前包的 `info_env`
|
||
4. `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 制作流程（手动）
|
||
|
||
1. 安装 APM 并安装所需 base：
|
||
|
||
```bash
|
||
sudo apm install amber-pm-xxx
|
||
```
|
||
|
||
2. 创建目录结构：
|
||
|
||
```bash
|
||
mkdir -p core work ace-env
|
||
```
|
||
|
||
3. 挂载 OverlayFS：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
4. chroot 进入 `ace-env` 进行安装
|
||
|
||
5. 卸载并打包
|
||
|
||
---
|
||
|
||
## APM 软件包测试
|
||
|
||
```bash
|
||
fuse-overlayfs -o lowerdir='...',upperdir=core/,workdir=work/ ./ace-env
|
||
```
|
||
|
||
或直接使用：
|
||
|
||
```bash
|
||
apm run 包名
|
||
```
|
||
|
||
APM 会自动完成：
|
||
|
||
* 解析 `info` / `info_layer_override`
|
||
* 应用 `info_env`
|
||
* 构建 OverlayFS
|
||
* 进入容器并运行应用
|
||
|
||
---
|
||
|
||
## APM 软件包打包
|
||
|
||
```bash
|
||
dpkg-deb --build 软件包目录 输出目录
|
||
```
|
||
|
||
---
|
||
|
||
## APM 底层 Base Runtime 构建
|
||
|
||
详见：
|
||
[https://gitee.com/amber-ce/amber-pm-common](https://gitee.com/amber-ce/amber-pm-common)
|
||
|
||
---
|
||
|
||
### 备注
|
||
|
||
APM 的打包工具与转换器会自动处理绝大多数复杂操作。
|
||
手动打包与 `info_env` 主要用于 **特殊运行环境、深度定制或调试用途**。
|
||
|