From 2f504c5963dc2e7e6fcb49c426c4f822f84d0203 Mon Sep 17 00:00:00 2001 From: shenmo Date: Thu, 18 Dec 2025 15:27:12 +0800 Subject: [PATCH] update doc --- Packaging-demo/README.md | 368 +++++++++++++++++++++++++++++---------- 1 file changed, 273 insertions(+), 95 deletions(-) diff --git a/Packaging-demo/README.md b/Packaging-demo/README.md index 6d2fd04..63bd45f 100644 --- a/Packaging-demo/README.md +++ b/Packaging-demo/README.md @@ -1,16 +1,19 @@ + + # APM 软件包打包流程 -本文档为开发者准备，若您只是想从 deb 软件包打包 APM 软件包，您可以通过 `amber-pm-convert`指令进行全自动一键转换 +本文档为开发者准备，若您只是想从 deb 软件包打包 APM 软件包，您可以通过 `amber-pm-convert` 指令进行全自动一键转换。 -通过 `apm search amber-pm- ` 即可搜索到所有可用的 base 列表 +通过 `apm search amber-pm-` 即可搜索到所有可用的 base 列表。 --- ## APM 软件包结构规范 -在阅读前，请确保您对overlayfs有了基本的了解 +在阅读前，请确保您对 OverlayFS 有了基本的了解。 -overlayfs 原理解析：https://www.cnblogs.com/arnoldlu/p/13055501.html +OverlayFS 原理解析： +[https://www.cnblogs.com/arnoldlu/p/13055501.html](https://www.cnblogs.com/arnoldlu/p/13055501.html) --- @@ -18,16 +21,25 @@ overlayfs 原理解析：https://www.cnblogs.com/arnoldlu/p/13055501.html APM 使用 OverlayFS 来管理软件包的文件系统层级，从上到下的层叠顺序为： -1. **Upperdir** - 当前包的可写层 `files/core/` -2. **Info Layer Override** - 覆盖层指定的目录（位于所有依赖层之上） -3. **依赖层** - 从 `info` 文件递归解析出的所有依赖包 -3. **底层** - 最基础的运行时环境 +1. **Upperdir** + 当前包的可写层：`files/core/` -这种层叠结构允许上层文件覆盖下层文件，实现依赖管理和自定义覆盖。 +2. **Info Layer Override** + 由 `info_layer_override` 指定的覆盖层，位于所有依赖层之上 + +3. **依赖层** + 由 `info` 文件递归解析出的所有依赖包 + +4. **底层 Runtime** + 最基础的运行时环境（如 `amber-pm-bookworm`） + +这种层叠结构允许上层文件覆盖下层文件，实现灵活、高效的依赖管理与环境定制。 --- -一个典型的 APM 软件/中层依赖包应当包含以下内容 +## APM 软件包目录结构示例 + +一个典型的 APM 应用或中层依赖包应当包含以下内容： ``` ├── DEBIAN @@ -41,20 +53,23 @@ APM 使用 OverlayFS 来管理软件包的文件系统层级，从上到下的 │ ├── applications │ ├── doc │ ├── glib-2.0 -│ │ └── man -│ ├── files -│ │ ├── core -│ │ └── work + │ └── man + ├── files + │ ├── core + │ └── work ├── info - └── info_layer_override # 可选，用于自定义覆盖层 - + ├── info_layer_override # 可选 + └── info_env # 可选（高级功能） ``` -### DEBIAN 目录 +--- -包含软件包的基本信息和依赖的环境信息 +## DEBIAN 目录说明 + +包含软件包的基本信息和依赖环境声明。 + +### control 文件示例 -**control 文件示例：** ``` Package: eom Version: 1.26.0-2-apm @@ -63,18 +78,34 @@ Maintainer: APM Converter 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 + This package was automatically converted from the original deb package. + Based on: amber-pm-bookworm ``` -- **Package**: 包名，应当唯一。若使用转换器进行转换，默认和原包名一致 -- **Version**: 版本号。若使用转换器进行转换，默认在原版本号后加 `-apm` -- **Architecture**: 软件包架构，同 dpkg 规范填写 -- **Depends**: 直接依赖的 base 包名 -- **Installed-Size**: 安装后的大小，转换器会自动计算 -- **Description**: 包描述，转换器会自动填写 +字段说明： + +* **Package** + 包名，应当唯一。使用转换器时默认与原 deb 包名一致 + +* **Version** + 软件包版本号，转换器会自动追加 `-apm` + +* **Architecture** + 架构信息，遵循 dpkg 规范 + +* **Depends** + 直接依赖的 base 包名 + +* **Installed-Size** + 安装后大小，转换器自动计算 + +* **Description** + 软件包描述信息 + +--- + +### postinst 文件 -**postinst 文件内容：** ``` #!/bin/bash PACKAGE_NAME="$DPKG_MAINTSCRIPT_PACKAGE" @@ -82,121 +113,268 @@ 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 - echo /home/$username - if [ -d "/home/$username/.apm/$PACKAGE_NAME" ] - then - rm -fr "/home/$username/.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 + done else echo "非卸载，跳过清理" fi ``` -若无特殊需求，内容保持一致即可，用于在卸载软件包后清理环境。 +若无特殊需求，保持该内容即可，用于卸载时清理残留环境。 -### /var/lib/apm 目录结构 +--- -包含 APM 软件容器的文件和信息： +## /var/lib/apm 目录结构说明 -- **entries** (可选)：包含需要放置到 `/usr/share/` 的文件，如 desktop、icon 等 -- **files** (必须)：包含软件包的 upperdir 和 workdir -- **info** (必须)：包含直接依赖的 base 信息。若应用使用了多层的依赖，会一层一层寻找 info 信息，直到找到底层依赖。如填写 amber-pm-bookworm-spark-wine10 会自动解析出 amber-pm-bookworm -- **info_layer_override** (可选)：用于指定自定义覆盖层的目录 +该目录包含 APM 软件包的运行环境与元数据。 -> 关于 Info: 使用多层的依赖并不是必须的，即使不使用也可以正常打包，但恰当地使用多层依赖可大大降低包体积。 可用的多层依赖见 `apm search amber-pm-[base名称]- ` 。若有必要，可申请新增 base +### 必须目录 +* **files/** -**entries 目录说明：** -- `entries/applications`：存放 `.desktop` 文件 -- `entries/doc`：存放文档 -- `entries/glib-2.0`：存放 GLib 相关文件 -- `entries/man`：存放帮助文档 + * `core/`：upperdir，可写层 + * `work/`：OverlayFS 工作目录 -> **重要提示**：`.desktop` 文件应当添加一行 `X-APM-APPID=包名` 来允许软件管理器管理应用 +* **info** -### info_layer_override 文件 + * 声明直接依赖的 base 包 + * 支持多层递归解析 -`info_layer_override` 是一个可选文件，用于在当前包的依赖层之上插入额外的覆盖层。这个功能在以下场景特别有用： +### 可选目录 / 文件 -1. **自定义库版本**：覆盖依赖包中的特定库文件，如你想要用更新版本的 mesa 覆盖 debian 默认提供的版本作为运行环境 -2. **配置文件自定义**：使用自定义配置覆盖默认配置 -- **语法**：与 `info` 文件一致，每行一个包名 -- **层叠位置**：位于所有依赖层之上、当前包的 upperdir 之下 -- **文件位置**：`${PATH_PREFIX}/var/lib/apm/${coredir}/info_layer_override` +* **entries/** -**示例：** -假设您想用自定义的 `override-layer` 包来覆盖 `base-package` 中的某些文件： + * `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`： -`my-package/info` 内容： ``` amber-pm-bookworm ``` -`my-package/info_layer_override` 内容： +`info_layer_override`： + ``` amber-pm-bookworm-mesa ``` -最终的挂载 lowerdir 为：`amber-pm-bookworm-mesa:amber-pm-bookworm` +最终 lowerdir 顺序： -这样，`override-layer` 中的文件会覆盖 `base-package` 中的同名文件（除非当前包的 upperdir 中也有该文件）。 - -## APM upperdir 制作流程 - -以下为手动制作 upperdir 的流程： - -1. **安装依赖**：首先安装 apm 并使用 `sudo apm install` 安装所需的 base - -2. **创建目录结构**： -```bash -mkdir -p core work ace-env +``` +amber-pm-bookworm-mesa:amber-pm-bookworm ``` -3. **挂载 overlay**： -```bash -sudo mount -t overlay overlay \ - -o lowerdir='/var/lib/apm/apm/files/ace-env/var/lib/apm/base包的包名（如amber-pm-trixie）/files/ace-env',upperdir=core/,workdir=work/ ./ace-env +--- + +## info_env（环境变量层 · 高级功能） + +`info_env` 是一个 **可选的高级特性**，用于为 APM 容器运行时提供**分层的环境变量配置能力**。 + +### 功能概述 + +* 为软件包及其依赖提供环境变量 +* 支持 **多层叠加** +* **上层自动覆盖下层** +* 与 OverlayFS 层级顺序完全一致 +* 不执行 shell 代码，仅解析键值对，安全可靠 + +--- + +### info_env 文件位置 + +``` +/var/lib/apm/<包名>/info_env ``` -4. **chroot 安装**：chroot 进入 `./ace-env` 进行安装操作，可以使用 `apt install` 或其他方式 +--- -5. **卸载并打包**：完成后解除挂载 `./ace-env` +### info_env 应用顺序（重要） -您将得到： -- **core**：保存新增文件 -- **work**：保存变更信息 +环境变量的加载顺序为： -将这两个目录权限设置为 755 后放入对应的目录进行 apm 打包。 +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='/var/lib/apm/apm/files/ace-env/var/lib/apm/base包的包名（如amber-pm-trixie）/files/ace-env',upperdir=core/,workdir=work/ ./ace-env +fuse-overlayfs -o lowerdir='...',upperdir=core/,workdir=work/ ./ace-env ``` -即可只读挂载。`apm run 包名` 会自动完成： -- 寻找 `/var/lib/apm/包名/` 是否存在 -- 根据 `info` 文件（和可选的 `info_layer_override`）合成 fuse-overlayfs 参数进行挂载 -- 使用 ACE 工具 chroot 进入并启动应用 +或直接使用： -使用 `./ace-run` 即可进入容器环境，测试您安装的应用。 +```bash +apm run 包名 +``` -## APM 打包 +APM 会自动完成： + +* 解析 `info` / `info_layer_override` +* 应用 `info_env` +* 构建 OverlayFS +* 进入容器并运行应用 + +--- + +## APM 软件包打包 -使用以下命令进行打包： ```bash dpkg-deb --build 软件包目录 输出目录 ``` -## APM 底层 Base Runtime 的构建 +--- -详见 https://gitee.com/amber-ce/amber-pm-common +## APM 底层 Base Runtime 构建 + +详见： +[https://gitee.com/amber-ce/amber-pm-common](https://gitee.com/amber-ce/amber-pm-common) --- -**备注**：APM 打包工具和转换器会为您自动处理大部分复杂操作，手动打包主要用于特殊情况或自定义需求。 \ No newline at end of file +### 备注 + +APM 的打包工具与转换器会自动处理绝大多数复杂操作。 +手动打包与 `info_env` 主要用于 **特殊运行环境、深度定制或调试用途**。 +