211 lines
6.9 KiB
Markdown
211 lines
6.9 KiB
Markdown
# OpenWrt-Yocto Build System
|
||
|
||
基于 Yocto Project 构建的 OpenWrt 系统，将 OpenWrt 的轻量级网络特性与 Yocto 的灵活构建框架相结合。
|
||
|
||
## 目录架构
|
||
|
||
```
|
||
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. 初始化编译环境
|
||
|
||
```bash
|
||
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)
|
||
|
||
```bash
|
||
# 最小化 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 编译环境。
|
||
|
||
#### 前置条件
|
||
|
||
1. 安装 [Docker Desktop for Mac](https://docs.docker.com/desktop/setup/mac/)
|
||
|
||
```bash
|
||
brew install --cask docker
|
||
```
|
||
|
||
2. 启动 Docker Desktop 并确保 Docker 守护进程在运行。
|
||
|
||
3. 确保至少有 **50GB** 可用磁盘空间。
|
||
|
||
#### 初始化 macOS 编译环境
|
||
|
||
```bash
|
||
cd ~/03-openwrt-yocto
|
||
|
||
# 首次运行：构建 Docker 镜像（约需数分钟）
|
||
./setup-env-macos.sh
|
||
|
||
# 进入编译容器
|
||
./setup-env-macos.sh shell
|
||
```
|
||
|
||
进入容器后，在容器内初始化 Yocto 环境并编译：
|
||
|
||
```bash
|
||
# 在 Docker 容器内执行：
|
||
source ./setup-env.sh # 初始化 BitBake 环境
|
||
bitbake openwrt-image-base # 编译镜像
|
||
```
|
||
|
||
#### 一键编译
|
||
|
||
也可以直接从 macOS 宿主机发起编译：
|
||
|
||
```bash
|
||
./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 与宿主机用户一致，避免文件权限问题
|