Skip to content

Translation pending. This page is currently available in Chinese.

快速上手(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 桌面终端后:

apk update
apk search tree
apk add tree
tree --version
apk del tree

上述更新、安装、执行、删除和触发脚本已在 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 的"发布准备"一节。

下一步