Translation pending. This page is currently available in Chinese.
镜像组装:world 清单与 mkrootfs¶
world 文件:镜像即清单¶
一个 world 文件定义一张镜像的内容,每行一个 apk 包名:
# packages/world/devel.world
a20-base
a20-drivers
# 以下是 Alpine 上游包(联网组装时从镜像站拉取)
musl
busybox
vim
git
语法规则:
#开头(或行内#之后)是注释;空行忽略;- 支持 apk 的版本约束语法:
vim=9.1.*、git>=2.4等; - 一行一个包;可加架构前缀,如
[x86_64,aarch64] libreoffice-writer,只在选定架构安装。前缀外仍不允许包名含空格。
组合镜像 = 编辑清单。这正是旧体系做不到的事:要一个"带 vim 的最小系统",复制 base.world、加一行 vim,组装即可,不需要改任何 Makefile。
内置 profile:
| world | 内容 | 网络需求 |
|---|---|---|
min |
a20-min + a20-drivers(**面向真机出厂**的最小用户态) | 无 |
base |
a20-base + a20-drivers(纯自有,对应旧 disk.img 的内容) | 无 |
devel |
base + Alpine 上游 musl/busybox/vim/git/curl 等 | 需要访问 Alpine 镜像站 |
xfce |
XFCE/labwc + Firefox、IBus/Rime、Geany、Evince、KeePassXC、GIMP;x86_64/AArch64 另含 LibreOffice Writer/Calc。提供 guest apk | 需要访问 Alpine 镜像站 |
server |
Alpine 上游 dropbear(SSH)/ chrony(NTP)/ busybox syslogd+crond,overlay init 拉起(实例 server-riscv64,SSH 转发 host:2222);声明层就绪,端到端验证待办 |
需要访问 Alpine 镜像站 |
cli |
Alpine 上游 zsh + GNU coreutils/findutils/grep/sed/gawk + git/vim/tmux/htop/curl/python3 等,overlay init 直接开出 zsh 登录 shell(实例 cli-<arch>,纯命令行工作站,171 个包 / 156 MiB) |
需要访问 Alpine 镜像站 |
min 与 base 怎么选¶
base 把 user/build/<arch> 下的程序平铺进根文件系统,包括开发诊断工具。min 用 recipe 的 include 正向列举启动、文件操作和诊断命令,排除压力测试。当前两者均用 BusyBox ash 和通用 applet;FAT 上的命令是调用同目录 BusyBox 的小型 POSIX 脚本,sh 为实际 ELF。过去基于 mksh/sbase 的大小数据不再适用于当前构建。
集合标准:能启动到 shell、做基本文件操作、提供 ls/cat/ps/grep/head/ tail/wc/date/uname 诊断链并正常关机。启动需 init、busybox 和 sh; RAMFS 用符号链接安装 applet,FAT 用脚本包装。最小包的可见命令清单刻意不含网络工具与编译器(BusyBox 二进制仍包含其配置启用的 applet)。
选择标准:要装到设备上就用 min,它才有希望放进 64 MiB NOR flash 或 128 MiB SD 卡;只在宿主机上做开发、调试和冒烟时用 base,工具齐全更省事。需要 Alpine 生态(vim/git/桌面)时用 devel / xfce,那些 world 不基于min。取舍理由写在 packages/recipes/a20-min.toml 的注释里。
XFCE 已使用 packages/world/xfce.world 与 packages/overlay/xfce/;软件实测范围见2026-10-23 桌面与 apk 验证。
组装:mkrootfs.py¶
tools/packaging/mkrootfs.py --arch riscv64 \
--world packages/world/devel.world \
--repo build/repo \ # 本地 A20OS 仓库(默认即此)
--output build/images/devel-riscv64.img \
--size-mb 1024
工作流程:
- 确保有静态
apk(自动下载apk-tools-static,缓存于build/cache/apk-tools/); - 用真正的 apk 解析器把 world 清单 + 依赖解析到 staging 目录(
apk --root <staging> --arch <arch> --initdb add ...); staging 固定落在仓库内build/tmp/(与输出镜像同一文件系统,避开塞满的/tmptmpfs;该目录随make clean一并删除,不会像/tmp那样留下清不掉的残留),且开始前先核对该文件系统的可用空间,不足则直接报错退出; - 应用
--overlay目录(可选,层层覆盖); - 写入
/etc/apk/repositories(仅远程仓库),并把--keys-dir下的*.rsa.pub公钥复制到/etc/apk/keys(不复制私钥)。xfce清单包含apk-tools与alpine-keys,启动后可直接使用apk;其他清单若要提供该命令,也需要显式加入apk-tools; mkfs.ext4 -d staging产出镜像。
权限与 --usermode¶
正确属主(root 拥有文件)需要 root 权限。脚本按此顺序处理:
- 已是 root(CI 容器)→ 直接做;
- 非 root → 默认对 apk/mkfs 步骤加
sudo(与旧 alpine 脚本一致); --usermode→ 完全不要 sudo:文件以调用者身份落盘,再用fakeroot+root_owner=0:0让**镜像内**文件属主仍为 root。开发期最省心。make image-world检测到非 root 会自动加此开关。
仓库来源与信任¶
--repo可多次给出;本地目录会自动拼接/<arch>/(注意:传给 apk 的是仓库根,apk 自己追加架构目录);URL 原样使用;- 默认追加 Alpine
main+community(--alpine-mirror换镜像站,默认 USTC;--no-alpine完全关闭); - 签名验证:
--keys-dir指向公钥目录(本地 dev 公钥在build/keys/); Alpine 官方公钥由脚本自动引导获取(缓存于build/cache/alpine-keys/); - 完全离线/不在意验证时可用
--allow-untrusted(日志会有告警)。
输出格式¶
--format ext4(默认):raw ext4 镜像,可直接作为 QEMU 的-drive ... format=raw或根盘。特性集与旧构建一致(^has_journal,extent,huge_file,flex_bg,uninit_bg,dir_index,与内核 ext4 实现验证过的集合相同);--format dir:不打包镜像,把 staging 目录搬到--output,适合调试内容或做进一步加工。
缓存¶
- apk 包缓存:
build/cache/apk/<arch>/(重复组装不同 world 时上游包不会重复下载); - 清掉缓存即可强制全新拉取。
通过 make 使用¶
make image-world ARCH=riscv64 PKG_WORLD=base # 打包+建库+组镜像
make run-world ARCH=riscv64 PKG_WORLD=base # 组镜像并直接在 QEMU 启动
run-world 把 world 镜像挂为第二块盘(内核枚举为 ext4 → 挂载到 /extra;若镜像内含 /etc/a20-distro 标记与 /sbin/init,则由 init 自动 chroot 接管进入 distro 模式,guest 直接落在 world rootfs 里,无需手动 chroot),根盘仍是常规 FAT32 开发镜像(→ /bin)。
组镜像时若存在 packages/overlay/<world 名>/ 目录,image-world 会自动将其作为 overlay 应用(覆盖同名文件,例如用自定义 /sbin/init 顶替 busybox 的符号链接)。devtools world 即以此方式提供 distro 直通:packages/overlay/devtools/ 内含 etc/a20-distro 标记与 stage-2 init 脚本,make run-world PKG_WORLD=devtools 启动后直接进入 Alpine shell。
| 变量 | 默认 | 含义 |
|---|---|---|
PKG_WORLD |
base |
world 清单名(packages/world/\<name>.world) |
PKG_SIZE_MB |
512 |
镜像大小 |
PKG_ALPINE |
1 |
是否引入 Alpine 仓库;纯本地组合设 0 |
PKG_REPO_DIR |
build/repo |
本地仓库位置 |
验证镜像内容(不起 QEMU)¶
debugfs -R "ls /lib/drivers" build/images/base-riscv64.img
debugfs -R "cat /etc/os-release" build/images/base-riscv64.img
启动组装出的镜像¶
它复用根 Makefile 的 QEMU 配置(不要手抄 QEMU 参数,各平台的-bios default、virtio 总线槽位等易错细节都在 Makefile/tools/mk/run-targets.mk里维护),把 world 镜像作为第二块盘启动。镜像是不含分区表的 raw ext4,也可以手工挂到任何现有 run-*/distro-run 命令的第二盘位。