# 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 与宿主机用户一致，避免文件权限问题