# OpenWrt-Yocto Build System

基于 Yocto Project 构建的 OpenWrt 系统，将 OpenWrt 的轻量级网络特性与 Yocto 的灵活构建框架相结合。

## 目录架构

```
03-openwrt-yocto/
├── setup-env.sh              # 一键初始化脚本
├── 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. 构建镜像

```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)