03-openwrt-yocto/
├── setup-env.sh              # Linux 环境初始化脚本
├── setup-env-macos.sh        # macOS Docker 编译环境脚本
├── Dockerfile                # Yocto 编译容器镜像定义
├── poky/                     # Yocto 核心框架 (BitBake + OE-Core)
│   ├── bitbake/              #   BitBake 构建引擎
│   ├── meta/                 #   OpenEmbedded-Core 基础层
│   ├── meta-poky/            #   Poky 参考发行版
│   ├── meta-yocto-bsp/       #   Yocto BSP 参考层
│   ├── scripts/              #   辅助脚本
│   └── oe-init-build-env     #   编译环境初始化脚本
├── meta-openembedded/        # OpenEmbedded 社区补充层
│   ├── meta-oe/              #   通用扩展包
│   ├── meta-python/          #   Python 支持
│   └── meta-networking/      #   网络工具
└── meta-openwrt/             # OpenWrt 定制层 (本项目核心)
    ├── classes/              #   BitBake 类文件
    ├── conf/                 #   层配置 (layer.conf)
    ├── recipes-core/         #   核心系统组件
    ├── recipes-extended/     #   扩展软件包与 GUI 镜像
    ├── recipes-kernel/       #   内核定制
    ├── recipes-networking/   #   网络工具
    ├── recipes-support/      #   支撑库
    └── recipes-tweaks/       #   系统微调 (bbappend)

快速开始

1. 初始化编译环境

cd ~/03-openwrt-yocto
source ./setup-env.sh

setup-env.sh 会自动完成以下操作：

步骤	说明
初始化	调用 `oe-init-build-env` 设置 BitBake 环境
添加层	`meta-oe`、`meta-python`、`meta-networking`、`meta-openwrt`
配置	追加 `INHERIT += "openwrt-distro-defaults"` 和 `IMAGE_FSTYPES = "iso"`

所有操作均为幂等：重复执行不会产生重复配置。

2. 构建镜像 (Linux)

# 最小化 CLI 系统（无 Web 界面）
bitbake openwrt-image-minimal

# 基础系统（含 LuCI Web 管理界面）
bitbake openwrt-image-base

# 完整系统（含 GPS、USB 模式切换、中继等）
bitbake openwrt-image-full

# JUCI 替代 Web 界面系统
bitbake openwrt-image-juci

3. 构建结果

构建产物位于 build-x86-openwrt/tmp/deploy/images/qemux86-64/，默认为 ISO 镜像格式。

可用镜像说明

镜像	Web 界面	适用场景
`openwrt-image-minimal`	无	最小化路由器/嵌入式设备
`openwrt-image-base`	LuCI	标准 OpenWrt 路由器
`openwrt-image-full`	LuCI	功能完整的网关设备
`openwrt-image-juci`	JUCI	追求现代 UI 的设备

OpenWrt 定制层 (meta-openwrt) 关键组件

BitBake 类 (`classes/`)

类文件	功能
`openwrt-distro-defaults.bbclass`	发行版默认配置，替换 sysvinit/systemd 为 `procd`
`openwrt.bbclass`	基础类，移除 SOLIBSDEV，继承 Lua 和虚拟运行时
`openwrt-kmods.bbclass`	内核模块管理
`openwrt-services.bbclass`	服务管理
`openwrt-virtual-runtimes.bbclass`	虚拟运行时定义
`openwrt-lua.bbclass`	Lua 脚本支持
`openwrt-base-files.bbclass`	基础文件系统管理

核心组件 (`recipes-core/`)

组件	说明
`procd`	OpenWrt 进程管理器 (替代 systemd/sysvinit)
`ubus`	进程间通信总线
`uci`	统一配置接口
`netifd`	网络接口管理守护进程
`firewall3`	防火墙管理 (基于 iptables)
`libubox`	基础工具库
`xtables-addons`	iptables 扩展模块 (含 LUA 脚本支持)

软件包组层级

packagegroup-openwrt-minimal
  ├── packagegroup-openwrt-minimal-base   (rpcd, ubus, uci, ubus, procd...)
  └── packagegroup-openwrt-minimal-network (dnsmasq, firewall3, iptables...)

packagegroup-openwrt-base (继承 minimal)
  ├── packagegroup-openwrt-base-network   (dnsmasq, umdnsd, odhcpd...)
  └── packagegroup-openwrt-base-luci      (lua, luci, uhttpd)

packagegroup-openwrt-full (继承 base)
  └── packagegroup-openwrt-full-network   (relayd, tcpdump, umbim, uqmi...)

依赖说明

层	必要性	说明
`poky/meta` (OE-Core)	必须	Yocto 核心基础层
`meta-openembedded/meta-oe`	必须	OpenWrt 组件所需通用包
`meta-openembedded/meta-python`	必须	Python 运行时支持
`meta-openembedded/meta-networking`	必须	网络相关依赖
`poky/meta-poky`	自动引入	Poky 发行版定义

关键配置

构建系统使用以下默认配置：

C 库: musl (TCLIBC = "musl")
输出格式: ISO (IMAGE_FSTYPES = "iso")
架构: qemux86-64 (MACHINE = "qemux86-64")
初始化系统: procd (INHERIT += "openwrt-distro-defaults")

可通过编辑 build-x86-openwrt/conf/local.conf 自定义上述配置。

兼容性

Yocto 版本: Scarthgap (5.0) / Nanbield (4.3)
已验证目标: qemux86-64
Linux 内核: 6.6 (yocto-standard)
macOS: 通过 Docker 容器支持（详见下方 macOS 编译章节）

macOS 编译 (Docker)

Yocto Project 不支持在 macOS 上原生编译。 官方推荐的跨平台方案是通过 Docker 容器运行 Linux 编译环境。

前置条件

安装 Docker Desktop for Mac
```
brew install --cask docker
```
启动 Docker Desktop 并确保 Docker 守护进程在运行。
确保至少有 50GB 可用磁盘空间。

初始化 macOS 编译环境

cd ~/03-openwrt-yocto

# 首次运行：构建 Docker 镜像（约需数分钟）
./setup-env-macos.sh

# 进入编译容器
./setup-env-macos.sh shell

进入容器后，在容器内初始化 Yocto 环境并编译：

# 在 Docker 容器内执行：
source ./setup-env.sh                 # 初始化 BitBake 环境
bitbake openwrt-image-base           # 编译镜像

一键编译

也可以直接从 macOS 宿主机发起编译：

./setup-env-macos.sh build openwrt-image-base

可用命令

命令	说明
`./setup-env-macos.sh`	构建 Docker 镜像（首次必需）
`./setup-env-macos.sh shell`	进入交互式编译容器
`./setup-env-macos.sh build <target>`	在容器中执行 bitbake 编译
`./setup-env-macos.sh clean`	清理 Docker 镜像和容器
`./setup-env-macos.sh help`	查看帮助

技术说明

Docker 镜像基于 Ubuntu 24.04（Yocto Scarthgap 官方支持的发行版）
编译产物位于宿主机的 build-x86-openwrt/tmp/deploy/images/ 目录
容器与宿主机共享项目目录，修改即时生效
容器内的用户 UID/GID 与宿主机用户一致，避免文件权限问题

README.md Unescape Escape

OpenWrt-Yocto Build System

目录架构