快速上手(Quickstart)¶
所有命令在项目根目录执行。首次使用只需记得三个入口:make pkgs(打包)→ make pkg-repo(建仓库)→ make image-world(组镜像),而 image-world 会自动带上前两者,所以最常用的就是最后一条。
一分钟跑通¶
# 1. 构建内核 + 用户态(和往常一样)
make ARCH=riscv64 dev-build
# 2. 打包 + 建本地仓库 + 按 base 清单组镜像
make ARCH=riscv64 image-world PKG_WORLD=base PKG_ALPINE=0
# 产物:
# build/packages/riscv64/*.apk 三个包:a20-base / a20-drivers / a20-kernel
# build/repo/riscv64/APKINDEX.tar.gz 本地仓库索引(已用 dev 密钥签名)
# build/images/base-riscv64.img ext4 rootfs 镜像
首次运行会自动生成本地开发签名密钥 build/keys/a20os-dev.rsa(在 .gitignore 覆盖的 build/ 下,不会被提交)。
常用命令¶
| 目的 | 命令 |
|---|---|
| 只打包(不建库) | make ARCH=riscv64 pkgs |
| 只打包指定包 | make pkgs PKG_RECIPES="a20-base a20-drivers" |
| 校验 recipe 不写包 | make pkgs-check |
| 组真机最小镜像(出厂用,1.38 MiB) | make ARCH=riscv64 image-world PKG_WORLD=min |
| 组 devel 镜像(含 Alpine 上游 vim/git) | make ARCH=riscv64 image-world PKG_WORLD=devel PKG_SIZE_MB=1024 |
| 组镜像但不碰网络 | make image-world PKG_ALPINE=0 |
| 手工组装(更细控制) | tools/packaging/mkrootfs.py --arch riscv64 --world packages/world/base.world --repo build/repo --keys-dir build/keys --no-alpine |
| 检查包内容 | tar -tzf build/packages/riscv64/a20-base-*.apk(或用 apk.static 解包) |
加一个用户软件(vim/git 等)¶
绝大多数用户软件不需要写 recipe:Alpine 上游已经有 apk 包,在 world 清单里加一行包名即可。user/extra.mk 与源码构建的 extra 路径已删除,extra-user-apps / extra-img / run-*-extra 只会报错并告诉你替代命令。
$EDITOR packages/world/devel.world # 追加一行,例如 vim / git / gcc
make ARCH=riscv64 image-world PKG_WORLD=devel # 重新组镜像
make ARCH=riscv64 run-world PKG_WORLD=devel # 组镜像并在 QEMU 验证
仍然从源码构建的用户程序只有两个:新增的 user/cmds/ 程序,和必须进 FAT32 根的 fastfetch。详见 distro/source-software-porting.md。
在桌面内使用 apk¶
新的 xfce 镜像包含 apk、Alpine 公钥和仓库配置。进入 A20OS 桌面终端后:
上述更新、安装、执行、删除和触发脚本已在 x86_64 A20OS 内实测。包安装成功并不表示包内所有程序都兼容 A20OS;新增软件仍需验证其系统调用、图形和音频依赖。当前未验证完整系统 apk upgrade。
旧镜像不会因为源码 world 改动而自动获得 apk 或新应用,需要重新组装。新增桌面软件与架构差异见 测试记录。
在容器里构建(与 CI 完全相同的环境)¶
docker build -t a20os-buildenv tools/ci
docker run --rm -v "$PWD:/src" -w /src a20os-buildenv \
make ARCH=riscv64 dev-build
宿主机非 Debian 13 时强烈建议用容器;CI 用的正是这个镜像。
发布一个版本¶
git tag v0.3.0 && git push --tags
# → release workflow 自动构建四架构镜像、签名包仓库、
# 创建 GitHub Release、把仓库部署到 GitHub Pages
一次性设置见 ci.md 的"发布准备"一节。
下一步¶
- 想给自己的程序做包 → packages.md
- 想定义新的镜像组合 → images.md
- 想搞清签名/信任 → repository.md