修改文档

2025-12-16 02:12:03 +08:00 · 2025-10-28 16:23:34 +08:00
parent 910216a457
commit 128944d7d4
8 changed files with 197 additions and 37 deletions
--- a/Packaging-demo/README.md
+++ b/Packaging-demo/README.md
@@ -0,0 +1,135 @@
+# APM 软件包打包流程
+
+本文档为开发者准备，若您只是想从 deb 软件包打包 APM 软件包，您可以通过 `amber-pm-convert`指令进行全自动一键转换
+
+通过 `apm search amber-pm- ` 即可搜索到所有可用的 base 列表
+
+---
+
+## APM 软件包结构规范
+
+在阅读前，请确保您对overlayfs有了基本的了解
+
+overlayfs 原理解析：https://www.cnblogs.com/arnoldlu/p/13055501.html
+
+
+---
+
+
+一个典型的 APM 软件/中层依赖包应当包含以下内容
+
+```
+├── DEBIAN
+│   ├── control
+│   └── postinst
+└── var
+    └── lib
+        └── apm
+            └── eom
+                ├── entries
+                │   ├── applications
+                │   ├── doc
+                │   ├── glib-2.0
+                │   └── man
+                ├── files
+                │   ├── core
+                │   └── work
+                ├── info
+                └── info_debug
+
+
+
+```
+
+* DEBIAN目录包含了软件包的基本信息和依赖的环境信息
+
+1. 以下是 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: 包名。应当唯一。若使用转换器进行转换，默认和原包名一致
+Version: 版本号。若使用转换器进行转换，默认在原版本号后加`-apm`
+Architecture: 软件包架构。同 dpkg 进行填写即可。若使用转换器进行转换，默认和原包架构一致
+Depends: 依赖包。填写直接依赖的base即可
+Installed-Size: 安装后的大小。若使用转换器进行转换，会自动填写
+Description: 包描述。若使用转换器进行转换，会自动填写
+
+
+2. 以下是 postinst 文件内容
+
+```
+#!/bin/bash
+PACKAGE_NAME="$DPKG_MAINTSCRIPT_PACKAGE"
+
+if [ "$1" = "remove" ] || [ "$1" = "purge" ]; then
+    echo "清理卸载残留"
+    rm -rf "/var/lib/apm/$PACKAGE_NAME"
+else
+    echo "非卸载，跳过清理"
+fi
+
+
+```
+若无特殊需求，内容保持一致即可，用于在卸载软件包后清理环境
+
+* /var/lib/apm 包含了APM 软件容器的文件和信息
+
+
+
+软件应当被放置在 /var/lib/apm/软件包名/ 处
+此处有两个目录，两个文件
+
+entries 可选，包含了软件包需要被放到 /usr/share/ 的文件，如 desktop icon 等
+files 必须，包含了软件包的 upperdir 和 workdir 
+info 必须，包含了直接依赖的base信息。若应用使用了多层的依赖，会一层一层寻找info信息，直到找到底层依赖
+info_debug 可选，包含了打包时解析的依赖信息
+
+entries下的内容同软件需要放置到 /usr/share/ 下的内容
+
+files的内容请见下一节
+
+## APM upperdir 制作流程
+
+以下为手动制作 upperdir 的流程
+
+首先，安装 apm 并使用`sudo apm install` 安装你所需要的 base  
+
+随后，新建三个文件夹，core，work 和 ace-env ,执行
+
+`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`
+
+随后chroot进入进行安装操作，直接进行 apt install 或者其他都可以，完成后解除挂载 ./ace-env
+
+你便得到了：
+
+* core: 保存新增文件
+* work: 保存变更信息
+
+
+需把这两个目录重新拥有并权限换成755后放入对应的目录进行 apm 打包
+
+你也可以测试一下刚刚打包的软件
+
+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
+
+即可只读挂载。这一步 apm run 包名 会帮你做好。
+
+> apm run 包名： 寻找 /var/lib/apm/包名/是否存在。若存在，根据info文件合成 fuser-overlayfs 参数进行挂载，随后用ACE工具chroot进入进行启动
+
+./ace-run 即可进入，可以尝试启动一下刚刚安装的应用
+
+## APM 打包
+
+使用 `dpkg-deb --build 软件包目录 输出目录` 即可进行打包
--- a/Packaging-demo/ace-run
+++ b/Packaging-demo/ace-run
--- a/Packaging-demo/core/.keep
+++ b/Packaging-demo/core/.keep
--- a/Packaging-demo/merge.sh
+++ b/Packaging-demo/merge.sh
--- a/Packaging-demo/work/.keep
+++ b/Packaging-demo/work/.keep
--- a/README.md
+++ b/README.md
@@ -1,50 +1,73 @@
-# APM 
+# APM 琥珀软件包管理器



-APM 是一款基于 fuse-overlayfs ， dpkg ， ACE 的容器软件包管理系统
+APM 是一款基于 fuse-overlayfs ， dpkg ， AmberCE 容器的软件包管理系统，支持在debian, fedora, arch等发行版上运行

-源码在 src
+APM 目前提供 debian 12/13 和 deepin 25 基础环境，支持把适配以上环境中的应用转换成 APM 应用

-原理：https://www.cnblogs.com/arnoldlu/p/13055501.html
+APM 会自动从主机获取 Nvidia 驱动文件，因此无需担心 N 卡无法加速问题

-## 体验demo: 查看 https://gitee.com/amber-ce/amber-pm/releases
+您可在 [src](src/) 目录找到 apm 的源代码
+
+overlayfs 原理解析：https://www.cnblogs.com/arnoldlu/p/13055501.html
+
+## 使用方法
+```
+APM - Amber Package Manager 1.0.10
+
+Usage:
+  apm [COMMAND] [OPTIONS] [PACKAGES...]
+
+Commands:
+  install      安装软件包
+  remove       卸载软件包
+  update       更新软件包信息
+  list         查看可用软件包信息
+  search       搜索软件包
+  download     下载包
+  clean        清除缓存软件包
+  autoremove   自动移除不需要的包
+  full-upgrade 完全升级软件包
+  run <package> 运行指定软件包的可执行文件
+  ssaudit <path> 使用 ssaudit 进行本地软件安装，详情见 spark-store
+  debug        显示调试系统信息并进入调试环境
+  amber      彩蛋功能
+  xmp360     彩蛋功能
+  bronya     彩蛋功能
+
+  -h, --help   显示此帮助信息
+
+```



-制作apm包upperdir的流程

-先安装 apm （从release）
+## APM deb 包全自动转换器使用方法

-sudo apm install base包后，在 
+```
+用法: amber-pm-convert --base <basename> [--base <basename> ...] <deb文件路径> [--pkgname <包名>] [--version <版本号>]

-sudo mount -t overlay  overlay   -o lowerdir='/var/lib/apm/apm/files/ace-env/var/lib/apm/amber-pm-trixie/files/ace-env',upperdir=core/,workdir=work/ ./ace-env
+参数说明:
+  --basename   必填参数，指定基础环境名称，可多次使用指定多个基础环境
+  deb文件路径  必填参数，要转换的DEB文件路径
+  --pkgname    可选参数，指定新包的包名（默认使用原DEB包名）
+  --version    可选参数，指定新包的版本号（默认在原版本后追加'-apm'）

-随后chroot进入进行安装操作，直接进行 apt install 或者其他都可以，完成后
-
-core: 保存新增文件
-work: 保存变更信息
-需把这两个目录重新拥有并权限换成755
+示例:
+  amber-pm-convert --base amber-pm-trixie /path/to/package.deb
+  amber-pm-convert --base amber-pm-bookworm-spark-wine /path/to/package.deb --pkgname new-pkg --version 1.0.0
+最下层的base在最后面，从上到下写base


-fuse-overlayfs -o lowerdir='/var/lib/apm/apm/files/ace-env/var/lib/apm/amber-pm-trixie/files/ace-env',upperdir=core/,workdir=work/ ./ace-env
+```

-即可只读挂载。这一步 apm run 包名 会帮你做好。
+> 注意：因为 apm 软件包为特殊的 deb 软件包，若您在使用 Debian 或其他使用 dpkg 管理软件包的发行版，您可使用apt直接把 apm 软件包安装到系统中，同样可使用。对于这种情况，请使用系统自带的 apt 进行软件包管理。

-> apm run 包名： 寻找 /var/lib/apm/包名/是否存在。若存在，根据info文件合成 fuser-overlayfs 参数进行挂载，随后用ACE工具chroot进入进行启动
+## APM 的原理和软件包的介绍

-./ace-run 即可进入，可以尝试启动一下刚刚安装的应用
+详见 [Packaging-demo](Packaging-demo)

-spec（对于APM内的包）：
-对于base
-/var/lib/apm/包名/files/ace-env 是 lowerdir
+## APM 构建 Tips

-对于core
-/var/lib/apm/包名/files/core是upperdir
-/var/lib/apm/包名/files/work是upperdir的work
-/var/lib/apm/包名/files/ace-env是chroot进的目录（需要在打包好的包内加上允许读写这个目录——或者后续换成tmp的挂载点）
-/var/lib/apm/包名/info是配置信息，目前只写了依赖的base，后续可以定义默认启动指令等
-/var/lib/apm/包名/entries是desktop位置，后续会加到自动展示中
-
-
-core的依赖需要写base
+APM 使用了特殊的精简版 AmberCE 兼容环境。相关的 Tips 见 [Tips](tips.md)
--- a/src/usr/bin/apm
+++ b/src/usr/bin/apm
@@ -17,23 +17,24 @@ APM - Amber Package Manager ${VERSION}
 Usage:
  $SCRIPT_NAME [COMMAND] [OPTIONS] [PACKAGES...]

+
 Commands:
  install      安装软件包
  remove       卸载软件包
  update       更新软件包信息
+  list         查看可用软件包信息
+  search       搜索软件包
  download     下载包
  clean        清除缓存软件包
  autoremove   自动移除不需要的包
  full-upgrade 完全升级软件包
  run <package> 运行指定软件包的可执行文件
-  ssaudit <path> 使用 ssaudit 进行软件安装，详情见 spark-store
+  ssaudit <path> 使用 ssaudit 进行本地软件安装，详情见 spark-store
  debug        显示调试系统信息并进入调试环境
  amber      彩蛋功能
  xmp360     彩蛋功能
  bronya     彩蛋功能

-  -h, --help   显示此帮助信息
-

 EOF
 }
--- a/tips.md
+++ b/tips.md
@@ -4,7 +4,7 @@

 2. apm 添加了一个钩子（debian only)，在安装到 /var/lib/apm 下的应用存在ace-env时，进行configure nvidia操作；若存在entries,则进行链接到/usr/share/applications操作

-3. apm 内置 ubuntu rootfs的修改如下
+3. apm 内置 rootfs的修改如下


 * 安装xz-utils
@@ -26,8 +26,7 @@



-* 重要：如何在APM内更新内容——如何覆盖？
-* deb全自动转apm
+
 * apm版融合商店
 * 类似 Wine 运行器的方式全图形化傻瓜式打包
 * 自动融合 APM 应用到系统主机，并实现右键卸载
@@ -42,4 +41,6 @@
 * 添加 gxde fixer 确保在GXDE下可以正常展示应用（即进行一次host integration类操作)
 * 完成amd64软件源配置
 * 修改aptss以兼容APM源加速
-* apm环境变量添加 IS_APM_ENV=1 GTK_USE_PORTAL=1
+* apm环境变量添加 IS_APM_ENV=1 GTK_USE_PORTAL=1
+* 重要：如何在APM内更新内容——如何覆盖？
+* deb全自动转apm