meta-starry

StarryOS Yocto 构建层 - 使用 BitBake 构建 StarryOS 裸机内核和完整发行版

---

项目简介

meta-starry 是 StarryOS 的 Yocto Project 构建层，提供：

• StarryOS 裸机内核构建
• 多架构支持（aarch64、riscv64、loongarch64、x86_64）
• 完整的测试发行版（内核 + rootfs + 工具链）

---

快速开始

环境要求

• 操作系统: Ubuntu 24.04 或兼容系统
• 构建主机: x86_64 或 aarch64
• 磁盘空间: 至少 100GB

系统配置

有的Ubuntu 24.04 需要调整内核参数：

# 一键配置（复制整段执行）
cat << 'EOF' | sudo tee /etc/sysctl.d/99-yocto.conf
kernel.apparmor_restrict_unprivileged_userns = 0
fs.inotify.max_user_watches = 524288
fs.inotify.max_user_instances = 512
fs.inotify.max_queued_events = 32768
EOF

sudo sysctl -p /etc/sysctl.d/99-yocto.conf

1. 克隆项目

见 Starryos readme

3. 初始化构建环境

cd ~/starry-workspace
source poky/oe-init-build-env build

注意：

• 首次运行会自动生成配置文件
• 每次打开新终端都需要重新运行此命令
• 成功后当前目录会切换到 build/

4. 构建

方式 A：仅构建内核

bitbake starry

产物：tmp-baremetal/deploy/images/aarch64-qemu-virt/starry-*.bin

方式 B：构建完整发行版

# 测试发行版（包含完整工具链）
bitbake starry-test-image

# 或最小发行版（快速测试）
bitbake starry-minimal-image

产物：tmp-baremetal/deploy/images/aarch64-qemu-virt/starry-test-image-*.ext4

5. 启动测试

# 启动发行版
runqemu starry-test-image nographic

# 登录（用户名：root，无密码）
root@starryos:~# uname -a
root@starryos:~# cat /etc/starry-release

---

常用命令

构建相关

# 查看所有可构建的目标
bitbake -s

# 构建指定配方
bitbake starry

# 仅执行特定任务
bitbake starry -c compile      # 仅编译
bitbake starry -c install      # 仅安装
bitbake starry -c deploy       # 仅部署
# 请注意这些都是按顺序的，指定后面的会强行自动构建前面的

# 强制重新执行任务
bitbake starry -c compile -f   # 强制重新编译
bitbake starry -c fetch -f     # 强制重新下载

# 查看配方的所有任务
bitbake starry -c listtasks

# 查看任务依赖关系
bitbake starry -c build -g
dot -Tpng pn-depends.dot -o depends.png

清理相关

# 清理单个配方（推荐）
bitbake starry -c cleansstate

# 清理所有构建产物（慎用）
bitbake starry -c cleanall

# 只清理工作目录（不清理 sstate）
bitbake starry -c clean

# 清理整个 tmp 目录（慎用）
rm -rf tmp-baremetal/

调试相关

# 查看配方的所有变量
bitbake starry -e

# 查看特定变量的值
bitbake starry -e | grep ^CARGO_FEATURES=
bitbake starry -e | grep ^ARCEOS_SMP=

# 查看构建日志
bitbake starry -c compile
less tmp-baremetal/work/*/starry/*/temp/log.do_compile

# 进入开发 Shell（调试编译问题）
bitbake starry -c devshell
# 进入源码目录，环境变量已配置好
# 可以手动运行 cargo build 等命令

# 进入 Python Shell（调试 BitBake 逻辑）
bitbake starry -c devpyshell

信息查询

# 查看层列表
bitbake-layers show-layers

# 查看配方所在的层
bitbake-layers show-recipes starry

# 查看配方的依赖
bitbake starry -g
cat pn-depends.dot

# 查看配方的文件
bitbake-layers show-appends starry

# 查看变量的来源
bitbake-getvar ARCEOS_SMP -r starry

镜像相关

# 列出所有可构建的镜像
ls meta-starry/recipes-core/images/

# 构建镜像并运行测试
bitbake starry-test-image -c testimage

# 查看镜像内容
ls tmp-baremetal/work/*/starry-test-image/*/rootfs/

# 解压 rootfs 查看
cd /tmp
tar xf ~/starry-workspace/build/tmp-baremetal/deploy/images/*/starry-test-image-*.tar.gz
ls -lh

---

测试指南

集成了基于 Yocto OEQA 的完整测试套件，包含 CI 功能测试、LTP 系统调用测试和 stress-ng 压力测试。

1. 自动化全量测试（推荐）

使用 BitBake 的 testimage 任务自动完成构建、启动和测试流程：

bitbake starry-test-image -c testimage

此过程会自动：

• 启动 QEMU (使用 slirp 网络)
• 通过 vsock 建立测试控制通道
• 执行 ptest (CI/Stress/Daily)
• 执行 LTP 系统调用测试
• 执行 stress-ng 压力测试 (CPU/Memory/IO)
• 生成测试报告

2. 手动运行测试

进入系统后手动执行测试命令：

# 1. 启动测试镜像
runqemu starry-test-image nographic slirp

# 2. 在 StarryOS 终端中运行测试：

# 运行 ptest 套件 (CI/Stress/Daily)
ptest-runner

# 运行 LTP 系统调用测试
/opt/ltp/runltp -f syscalls -s syscall_basic -q

# 运行 CPU 压力测试
stress-ng --cpu 2 --timeout 10s --metrics-brief

---

切换架构

方法 1：修改配置文件

编辑 build/conf/local.conf：

# ARM64（默认）
MACHINE ?= "aarch64-qemu-virt"

# RISC-V 64
MACHINE = "riscv64-qemu-virt"

# LoongArch 64
MACHINE = "loongarch64-qemu-virt"

# x86_64
MACHINE = "x86_64-qemu-q35"

方法 2：命令行指定

# 临时切换架构（不修改配置）
MACHINE=riscv64-qemu-virt bitbake starry

# 查看当前 MACHINE
bitbake-getvar MACHINE

---

自定义构建

在 build/conf/local.conf 中添加：

# CPU 核心数（默认 4）
ARCEOS_SMP = "8"

# 日志级别
ARCEOS_LOG = "debug"

# 内存大小
ARCEOS_MEM = "2G"

# 调试符号
ARCEOS_DWARF = "y"

# 并行构建（根据主机 CPU 核心数调整）
BB_NUMBER_THREADS = "16"
PARALLEL_MAKE = "-j 16"

# 共享下载目录（团队协作）
DL_DIR = "/mnt/shared/yocto-downloads"

# 共享 sstate 缓存（10-20 倍加速）
SSTATE_DIR = "/mnt/shared/sstate-cache-${BUILD_ARCH}"

---

本地开发模式

自动检测（repo 工作区）

repo 工作区会自动使用本地代码，无需配置：

cd ~/starryos-workspace
repo sync
source poky/oe-init-build-env build
bitbake starry  

手动配置

在 build/conf/local.conf 中设置：

# 只配置需要修改的仓库
STARRY_LOCAL_PATH = "/path/to/your/StarryOS"
ARCEOS_LOCAL_PATH = "/path/to/your/arceos"

支持的变量：STARRY_LOCAL_PATH、ARCEOS_LOCAL_PATH、AXDRIVER_LOCAL_PATH、AXPLAT_LOCAL_PATH、ARMGIC_LOCAL_PATH、FDTREE_LOCAL_PATH、CROSVM_PLAT_LOCAL_PATH、PAGE_TABLE_LOCAL_PATH、AXCPU_LOCAL_PATH、KERNEL_GUARD_LOCAL_PATH

添加新仓库

修改 meta-starry/recipes-kernel/starryos/starry_git.bb：

1. 添加 SRC_URI（第 55-65 行）：

git://${STARRY_GITHUB}/new-repo.git;...;name=newrepo
SRCREV_newrepo = "commit-hash"

2. 添加本地路径变量（第 84-93 行）：

NEW_REPO_LOCAL_PATH ?= ""

3. 添加到自动检测（第 105-113 行）：

'NEW_REPO_LOCAL_PATH': 'new-repo',

4. 添加符号链接（第 202-225 行，可选）：

if [ -n "${NEW_REPO_LOCAL_PATH}" ] && [ -d "${NEW_REPO_LOCAL_PATH}" ]; then
    ln -sf ${NEW_REPO_LOCAL_PATH} ${S}/local_crates/new-repo
fi

5. 更新示例（meta-starry/conf/local.conf.sample）：

#NEW_REPO_LOCAL_PATH = "/custom/path/to/new-repo"

---

文档索引

使用

• 接口说明 - Classes、变量、配置文件详解
• 团队协作 - 缓存共享、构建加速

---

贡献指南

cd ~/starry-workspace/meta-starry
git add .
git commit -m "feat: add new feature"
git push

代码规范：

• 赋值运算符两侧有空格：VARIABLE = "value"
• 使用新语法：:append 而不是 _append
• 路径使用标准变量：${D}${bindir} 而不是 /usr/bin

---

许可证

Apache License 2.0

---

维护者

• @kylin-x-kernel
• @yeanwang666
• @guoweikang
• @sunhaosheng

最后更新：2026-01-09