# opiz3-scripts

**Repository Path**: yangdonggit/opiz3-scripts

## Basic Information

- **Project Name**: opiz3-scripts
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-22
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Orange Pi Zero 3 (H618) Yocto 工程 — opiz3

纯 OpenEmbedded-Core 自建工程：**Yocto LTS 6.0 "Wrynose"**，不使用 meta-poky，自建 DISTRO；主线内核 / U-Boot；init 为 sysvinit（busybox）。板卡：Orange Pi Zero 3（Allwinner H618）。工程现以 **Google repo** 统一管理各层仓库（manifest：gitee `yocto_manifest`）。

代码拉取共有两种方式：**§2 repo manifest（当前推荐，工程现用）**、**§3 git submodule（旧，已弃用，仅供参考）**。

## 1. 快速开始

### 1.1 系统依赖（Ubuntu 24.04 noble）

```bash
sudo apt update && sudo apt install -y gawk wget git-core diffstat unzip texinfo gcc-multilib \
  build-essential chrpath socat cpio python3 python3-pip python3-pexpect xz-utils debianutils \
  iputils-ping python3-git python3-jinja2 zstd liblz4-tool file locales bison flex \
  libsdl1.2-dev libegl1 xterm python3-subunit mesa-common-dev pylint
sudo locale-gen en_US.UTF-8
```

> 注意：Ubuntu 22.04 的 `libegl1-mesa`、`pylint3` 在 24.04 已分别改名为 `libegl1`、`pylint`（build.sh `--deps` 已同步修正）。

### 1.2 Ubuntu 24.04 需关闭 unprivileged userns（BitBake fakeroot 必需）

Ubuntu 24.04 默认 `kernel.apparmor_restrict_unprivileged_userns=1`，BitBake 直接报 `ERROR: User namespaces are not usable by BitBake`：

```bash
echo 'kernel.apparmor_restrict_unprivileged_userns = 0' | sudo tee /etc/sysctl.d/90-unprivileged-userns.conf
sudo sysctl --system
```

### 1.3 构建

```bash
cd <工程根>          # 已按 §2（或 §3）拉取完成
./build.sh opiz3-mini      # 或 ./build.sh opiz3（core-image-base）
# 后台长构建（日志固定 repo_sync.log，防 SSH 断开中断）：
setsid bash -c './build.sh opiz3-mini > /home/yd/work/repo_sync.log 2>&1' < /dev/null &
```

产物：`build_distro/opiz3-mini/tmp/deploy/images/orange-pi-zero3/core-image-minimal-*.wic.gz`（约 19 MB，含 openssh-sftp-server）。

> **共享/低配构建机建议**：将 `build_distro/*/conf/local.conf` 中 `BB_NUMBER_THREADS` / `PARALLEL_MAKE` 调低（如 8），避免并行过载导致 gcc/gnutls 等大包 make 竞态失败；构建中断恢复后若出现 `undefined reference` 类链接错误（中断残留的增量构建），对该包执行 `bitbake -c cleanall <pkg>` 后重编即可。

## 2. 代码拉取方式一：repo manifest（当前推荐，工程现用）

工程源码由 6 个 meta 层 + 1 个脚本仓库组成，由 gitee **yocto_manifest** 仓库统一声明各项目与 commit，`repo` 工具一次拉取全部（含根目录 `build.sh` / `README.md`）。

### 2.1 安装 repo 工具（清华镜像）

repo 是 Google 的 Python 工具（本体为 git-repo 仓库中的 `repo` 脚本），需先下载并配置。国内网络直接用清华 TUNA 镜像：

```bash
# 下载 repo 脚本（清华镜像）
mkdir -p ~/bin
curl -sS https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/repo > ~/bin/repo
chmod a+x ~/bin/repo
export PATH=$HOME/bin:$PATH
repo --version        # 验证：正常打印 repo 版本（依赖 python3，见 §1.1）

# 配置 REPO_URL：让 repo init 默认从清华镜像拉取 repo 自身源码（建议写入 ~/.bashrc 持久化）
echo 'export REPO_URL="https://mirrors.tuna.tsinghua.edu.cn/git/git-repo"' >> ~/.bashrc
source ~/.bashrc
```

> 说明：
> - 也可 `git clone https://mirrors.tuna.tsinghua.edu.cn/git/git-repo.git` 后使用其中的 `repo` 脚本；
> - 配置 `REPO_URL` 后，§2.2 中 `repo init` 的 `--repo-url` 参数可省略（默认走清华源）；本 README 保留显式写法以自解释；
> - repo 首次运行还会在 `~/.repo/repo/` 下自举拉取自身源码，同样由 `REPO_URL`/`--repo-url` 决定源。

### 2.2 首次拉取

```bash
mkdir -p <工程根> && cd <工程根>
# 默认 manifest：default.xml（= opiz3-mini.xml）
repo init --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo \
          -u https://gitee.com/yangdonggit/yocto_manifest.git
# 构建 opiz3（标准镜像）时改用 opiz3.xml：
#   repo init --repo-url=... -u ... -m opiz3.xml
# 拉取全部项目（长任务用 setsid 脱离 SSH 会话）：
setsid bash -c 'repo sync --no-clone-bundle -j4 > repo_sync.log 2>&1' < /dev/null &
```

### 2.3 日常增量更新（已 init 过的仓库）
```bash
cd <工程根>
repo sync --no-clone-bundle -j4
# 切换 manifest 后需重新 sync：
repo init -u https://gitee.com/yangdonggit/yocto_manifest.git -m opiz3.xml
repo sync --no-clone-bundle -j4
```

### 2.4 说明
- `--repo-url` 必须指向清华镜像（repo 自身源码默认从 gerrit.googlesource.com 拉取会被拒）；
- manifest 仓库内维护两个 xml：`default.xml`（链接到 opiz3-mini.xml）与 `opiz3.xml`，默认拉取 mini 配置；
- 各层在 `sources/<name>/` 下是独立 git 仓库，commit 由 manifest 固定（不要手动改层内 commit，否则下次 sync 会被重置；自建层 meta-opiz3 的改动请提交推送 gitee）；
- 根目录 `build.sh` / `README.md` 来自 opiz3-scripts 仓库（manifest 中 path 为工程根）；
- 拉取完成后目录：`sources/{openembedded-core, bitbake, meta-openembedded, meta-arm, meta-sunxi, meta-opiz3}` + 根目录 `build.sh` / `README.md`。

### 2.5 repo 常用命令

**查询状态**
```bash
repo status                        # 各项目工作区改动（M=修改, A=新增, D=删除）
repo diff                          # 查看各项目具体改动内容
repo info                          # 各项目 git 仓库地址 / 当前 commit / manifest 固定 commit
repo list                          # 列出 manifest 管理的所有项目
```

**提交代码**（仅自建层/脚本仓库需要，上游层勿提交）
```bash
# 1) 先建分支（repo commit 要求项目处于分支上，不能是 detached HEAD）
repo start <分支名>                 # 例：repo start partuuid-change
# 2) 确认改动
repo status
# 3) 提交（对每个有改动的项目分别生成一个 commit）
repo commit -a -m "提交说明"
# 4) 推送到 gitee（gitee 无 gerrit 评审，故不用 repo upload，改用 forall 逐仓 push）
repo forall -c 'git push origin HEAD:refs/heads/<分支名>'
#    只推送自建层时：
cd sources/meta-opiz3 && git push origin <分支名>
```

> 说明：
> - 上游层（openembedded-core、meta-openembedded 等）的 commit 由 manifest 固定，本地改动会在下次 `repo sync` 被重置；需长期保留的定制一律放进自建层 meta-opiz3（bbappend / 内核 fragment）。
> - 自建层推送后如需其他机器同步到新 commit：更新 gitee `yocto_manifest` 仓库对应 xml 的 `revision`，再在其他机器执行 §2.3 的 `repo sync`。

**回退**
```bash
repo abandon <分支名>               # 丢弃分支上的全部 commit，回到 manifest 固定状态
repo forall -c 'git checkout -- .'  # 丢弃各项目未提交的工作区改动（慎用，不可恢复）
repo sync -d                        # 强制各项目 checkout 到 manifest 固定 commit（丢弃本地漂移）
repo checkout master                # 各项目切回主分支
```

**初始化 / 同步（快捷引用，详见 §2.2 / §2.3）**
```bash
repo init --repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo           -u https://gitee.com/yangdonggit/yocto_manifest.git          # 默认 default.xml(=opiz3-mini)
repo init -u https://gitee.com/yangdonggit/yocto_manifest.git -m opiz3.xml  # 切换 manifest
repo sync --no-clone-bundle -j4     # 同步全部项目
```

**其他**
```bash
repo prune                          # 删除各项目已合并/废弃分支
repo forall -c 'git log --oneline -3'   # 对所有项目执行任意 git 命令
```


## 3. 代码拉取方式二：git submodule（旧方式，已弃用，仅供参考）

工程早期用 5 个上游层作 submodule 固定 commit，现已被 repo 方式（§2）取代，不再维护 `.gitmodules`：

```bash
# 方式 A：克隆时自动拉取全部 submodule（旧推荐）
git clone --recursive https://gitee.com/yangdonggit/opiz3.git && cd opiz3

# 方式 B：已克隆但未带 --recursive，补拉 submodule
cd opiz3
git submodule update --init --recursive

# 检查 submodule 状态：前缀为空格=正常；'-'=未初始化（补拉）；'+'=commit 漂移（勿改内部代码）
git submodule status
```

> 旧方式注意：meta-arm 走 `git.yoctoproject.org`（github 镜像 401 不可用），需可访问该域名。**新工程请一律使用 §2 方式一。**

## 4. 工程结构

```
<工程根>/                    # repo 工作区（.repo/ 由 repo 管理，不入库）
├── build_distro/             # ★ 统一输出目录（不入库，首次构建自动创建）
│   ├── opiz3/                #   opiz3（core-image-base，本机尚未构建）
│   │   └── tmp/deploy/images/orange-pi-zero3/   # 镜像产物
│   └── opiz3-mini/           #   opiz3-mini（core-image-minimal）
│       └── tmp/deploy/images/orange-pi-zero3/   # 镜像 + Image.gz + SDK
├── sources/                  # repo 管理的 6 个 git 仓库（各自独立 .git）
│   ├── openembedded-core/    # wrynose（基础层，含 bitbake 类）
│   ├── bitbake/              # bitbake 2.19.1
│   ├── meta-openembedded/    # wrynose（meta-oe + meta-python）
│   ├── meta-arm/             # wrynose（TFA 2.14.1；meta-arm + meta-arm-toolchain）
│   ├── meta-sunxi/           # master（机器定义/主线内核/固件）
│   └── meta-opiz3/           # ★ 自建层（priority 15，gitee 仓库，随 repo 同步）
│       ├── conf/layer.conf
│       ├── conf/distro/opiz3.conf         # 自建发行版（sysvinit）
│       ├── conf/distro/opiz3-mini.conf    # mini 最简发行版（继承+裁剪）
│       ├── conf/distro/opiz3/             # 公共配置 opiz3-common.inc（含 SDK 裁剪）
│       ├── recipes-kernel/linux/
│       │   ├── linux-mainline_%.bbappend  # 内核 fragment 合并
│       │   └── files/opiz3.cfg            # dwmac/PHY/TRNG/裁剪配置
│       ├── recipes-bsp/u-boot/
│       │   └── u-boot_%.bbappend          # TFA 依赖 + USB 裁剪 + boot.scr 定制
│       └── recipes-core/
│           ├── dropbear/                  # key 预生成 + 后台生成
│           ├── init-ifupdown/             # eth0 关闭 udhcpc（-b 后台，快速启动）
│           └── images/                    # core-image-minimal.bbappend（sftp-server 等）
├── build.sh                  # ★ 统一构建入口（多 distro 交互选择，并行度 16）
├── deploy_sftp_server.sh     # 免重刷部署 sftp-server 到目标板
├── .gitignore
└── README.md
```

## 5. 版本信息

| 组件 | 版本 | 来源（repo manifest 固定 commit） |
|---|---|---|
| openembedded-core | wrynose (LTS 6.0, 2026-05) `883075157987` | github.com/openembedded/openembedded-core |
| bitbake | 2.19.1 `046a90b0e9b7` | github.com/openembedded/bitbake |
| meta-openembedded | wrynose `47d7dbdd1089` | github.com/openembedded/meta-openembedded |
| meta-arm | wrynose（TFA 2.14.1）`9dab8bdd4991` | **git.yoctoproject.org/meta-arm**（github 镜像 401） |
| meta-sunxi | master `fa1f75af1697` | github.com/linux-sunxi/meta-sunxi |
| 内核 | linux-mainline **6.18.40**（=y 内建，Image.gz） | kernel.org / meta-sunxi |
| U-Boot | **2026.01**（主线 + sunxi） | oe-core / meta-sunxi |
| Trusted Firmware-A | **2.14.1**（BL31） | meta-arm |

## 6. 编译命令（统一入口 build.sh）

```bash
./build.sh -h                 # 列出支持的 distro
./build.sh                    # 列出 distro 并等待选择后构建
./build.sh opiz3              # 直接构建 opiz3（core-image-base）
./build.sh opiz3-mini         # 直接构建 opiz3-mini（core-image-minimal）
./build.sh opiz3 -c cleanall  # 追加 bitbake 参数
./build.sh --deps             # 仅安装 Ubuntu/Debian 构建依赖（需 sudo）
```

自动完成：校验 `sources/meta-opiz3` 层存在 → 首次自动生成 `build_distro/<distro>/conf`（相对路径）→ 加载 oe-init-build-env → bitbake。输出统一到 `build_distro/<distro>/`，仓库内任意位置可用。

底层等价：
```bash
cd build_distro/opiz3
export PATH=$PWD/../../sources/bitbake/bin:$PWD/../../sources/openembedded-core/scripts:$PATH
source ../../sources/openembedded-core/oe-init-build-env .
bitbake core-image-base
```

## 7. 层依赖关系

```
meta-opiz3（priority 15，最后解析，LAYERDEPENDS=sunxi）
    ▲
meta-sunxi（priority 10，LAYERDEPENDS=core/meta-python/meta-arm）
    ▲
meta-arm / meta-arm-toolchain / meta-python / meta-oe（priority 5）
    ▲
openembedded-core/meta（priority 5，最先解析）
```

**为什么 meta-opiz3 最后**：优先级最高（15>10>5），bbappend 覆盖优先生效；`LAYERDEPENDS=sunxi` 保证上游先加载。**bitbake 解析顺序**：machine → distro/opiz3.conf → defaultsetup.conf（故 `INIT_MANAGER="sysvinit"` 不被 `??= systemd` 覆盖）。

## 8. 内核配置（opiz3.cfg，全部 =y 内建）

### 8.1 必要功能（=y 内建，不可裁剪）

```ini
CONFIG_STMMAC_ETH=y        # DWMAC_SUN8I 依赖核心（否则驱动被降级 =m）
CONFIG_STMMAC_PLATFORM=y
CONFIG_DWMAC_SUN8I=y       # dwmac-sun8i 编译进内核（5020000.ethernet）
CONFIG_PHY_MOTORCOMM=y     # 板载 PHY YT8531C
CONFIG_MOTORCOMM_PHY=y
CONFIG_CRYPTO_DEV_SUN8I_CE=y        # H616 硬件 TRNG（crng 快速初始化）
CONFIG_CRYPTO_DEV_SUN8I_CE_TRNG=y
CONFIG_MMC=y / MMC_SUNXI=y / MMC_SDHCI=y   # SD/eMMC（rootfs 挂载）
```

### 8.2 已裁剪（`is not set`，按功能点）

| 功能 | 配置 | 原因 |
|---|---|---|
| 虚拟化/KVM | VIRTUALIZATION / KVM | 无虚拟机场景 |
| NFC | NFC | 无 NFC 硬件 |
| 蓝牙 | BT（连带 ecdh/ecc 自动关闭） | 已裁剪 |
| 射频/无线 | RFKILL / CFG80211 / WLAN | 已裁剪（无 WiFi 模组） |
| IPv6 | IPV6 | 纯 IPv4 环境 |
| USB 子系统 | USB_SUPPORT | 无 USB 设备需求 |
| ALSA 声卡 | SOUND / SND | 无音频 |
| 9p/virtio | 9P_FS / VIRTIO 全系 | 无虚拟化 |
| 显示 | DRM / FB | 无 HDMI/LCD |
| **NFS** | **NFS_FS / NFS_V2..V4_2 / ROOT_NFS / IP_PNP(+DHCP/BOOTP/RARP)** | **已移除，不再挂载 NFS** |

> 曾尝试第二轮深度裁剪（SPI / x86 网卡 E1000/E1000E/IGB/SKY2/THUNDER / VFIO / TUN / LOOP / SQUASHFS / EDAC / SCSI / ATA / 非 sunxi MMC），因在目标板出现启动异常已**整体回退**，保持主线默认（详见 §11.9）。

## 9. mini 最简配置（opiz3-mini）

`require conf/distro/opiz3.conf` 继承，在 distro conf 中裁剪：

- `DISTRO_FEATURES:remove = "bluetooth wifi nfc 3g zeroconf pci alsa pulseaudio keyboard ldconfig"`
- `MACHINE_FEATURES:remove = "keyboard"`（去掉 kbd/loadkeys/keymap，~1MB）
- `VIRTUAL-RUNTIME_dev_manager = "busybox-mdev"`（udev→mdev，省 ~1.2MB + 启动更快）
- `IMAGE_INSTALL:remove = "udev kmod modutils-initscripts"`（kmod 连带 libcrypto 5.6MB 消失）
- `IMAGE_OVERHEAD_FACTOR = "1.0"` + `IMAGE_ROOTFS_EXTRA_SPACE = "0"`（wic 紧凑化）
- `KERNEL_IMAGETYPE = "Image.gz"`（压缩内核镜像）
- 镜像 `core-image-minimal`，输出 `build_distro/opiz3-mini/`

| 维度 | opiz3 | opiz3-mini |
|---|---|---|
| 镜像 | core-image-base | core-image-minimal |
| 打包数量 | 123（旧构建机记录） | 32 |
| wic.gz | —（本机尚未构建） | **19 MB**（rootfs-20260924080504，含 sftp-server） |
| Image.gz | — | **13 MB**（6.18.40） |
| init | sysvinit/busybox | sysvinit/busybox |

## 10. 构建产物

```
build_distro/opiz3-mini/tmp/deploy/images/orange-pi-zero3/
├── core-image-minimal-orange-pi-zero3.rootfs-*.wic.gz   # 19 MB，烧 SD 卡
├── Image.gz--6.18.40-r0-orange-pi-zero3-*.bin           # 13 MB（压缩内核）
├── u-boot-sunxi-with-spl.bin-orange-pi-zero3-2026.01-r0
├── sun50i-h618-orangepi-zero3.dtb / boot.scr
└── trusted-firmware-a/bl31.bin

# SDK（独立可安装交叉工具链，见 §14.10）
build_distro/opiz3-mini/tmp/deploy/sdk/
└── oecore-meta-toolchain-x86_64-cortexa53-crypto-orange-pi-zero3-toolchain-nodistro.0.sh   # 99 MB
```

## 11. 关键排障记录

1. **meta-arm master 与 wrynose 不兼容**（1009 LICENSE 解析错误）→ 切 `wrynose` 分支。
2. **u-boot 缺 BL31**：meta-sunxi 的 task-flag 在 bitbake 2.19 失效 → meta-opiz3 补 `do_compile[depends] += "trusted-firmware-a:do_deploy"`。
3. **`DWMAC_SUN8I=y` 被降级 =m**：依赖 `STMMAC_ETH=m` → 同时置 `STMMAC_ETH=y` + `STMMAC_PLATFORM=y`。
4. **`debug-tweaks` 是 poky 专属** → 改用 oe-core 特性组合。
5. **fragment 路径**：kernel-yocto 解包到 `${WORKDIR}/sources/`，merge 指向 `sources/opiz3.cfg`（经 bbappend `SRC_URI:append = " file://opiz3.cfg"` 引用，勿直接 cat 覆盖 bbappend）。
6. **root 空密码失败（wrynose 特性改名）**：`empty-root-password` 控制 root 置空与串口自动登录（`allow-empty-password` 只管 SSH）→ 已固化到 distro：`IMAGE_FEATURES:append = " empty-root-password allow-empty-password allow-root-login serial-autologin-root"`。
7. **"Starting kernel" 后无任何输出（假卡死）**：boot.cmd 模板 `console=${console}` 依赖 U-Boot 环境变量但未定义 → bootargs 无 `console=`，内核无串口控制台。修复：bbappend 硬编码 `console=ttyS0,115200`。
8. **内核层强制清理须用 `cleanall`**：`cleansstate` 会残留损坏源码（Makefile 缺失 → kernel_version 显示 "."、dts patch 失败），`cleanall` 连同工作区清空重解包（下载源在共享 `downloads/`，无需重下）。
9. **第五阶段内核裁剪回退**：SPI/x86 网卡/SCSI/ATA 等一批裁剪在目标板出现启动异常（未最终定位到具体项），已整体回退到主线默认；NFS 移除保留。
10. **`PACKAGE_EXCLUDE kbd` 会冲突**：keymaps 硬依赖 kbd → 改 `MACHINE_FEATURES:remove = "keyboard"`（`.conf.append` 不被 bitbake 加载，须写 distro conf）。
11. **modutils.sh 归属**：来自 oe-core `modutils-initscripts`（recipes-kernel 目录），经 `IMAGE_INSTALL:remove` 移除；若仍有残留属间接依赖链，可改用 `PACKAGE_EXCLUDE`。
12. **Ubuntu 24.04 构建环境**：
    - `libegl1-mesa`/`pylint3` 包已改名（→ `libegl1`/`pylint`），`--deps` 已适配；
    - 默认 `apparmor_restrict_unprivileged_userns=1` 使 BitBake fakeroot 报错，须按 §3.2 关闭；
    - 构建机重启导致 gcc/gnutls 等大包增量 make 链接失败（`undefined reference`）时，`bitbake -c cleanall <pkg>` 完整重建即可恢复。
13. **meta-toolchain 为什么下载 llvm**：SDK 主机包组 `nativesdk-packagegroup-sdk-host` 含 `nativesdk-qemu` → qemu 默认开 virglrenderer/epoxy（图形渲染）→ 拉 mesa；mesa 默认对 x86-64/native 追加 `gallium-llvm libclc` → 整棵 llvm/clang（约 142MB 下载）。**已裁剪**（meta-opiz3 `opiz3-common.inc`）：qemu-native/system/nativesdk-qemu 移除 `virglrenderer epoxy gtk+`，mesa/mesa-native/nativesdk-mesa 移除 `gallium-llvm libclc`——SDK 构建不再下载 llvm。
14. **SDK 体积裁剪（165M → 99M）**：① `nativesdk-packagegroup-sdk-host.bbappend` 移除 `nativesdk-qemu/qemu-helper/unfs3`（真板开发不需要 runqemu，连带 libsdl2/libslirp/libpixman 消失）；② `GLIBC_GENERATE_LOCALES:pn-nativesdk-glibc-locale = "en_US.UTF-8"`（host locale 152 包 → 1）；③ `SDKIMAGE_FEATURES:remove = "dbg-pkgs src-pkgs"`（保留 dev）。已知残留：target 侧 `libc6-dbg`（glibc 调试符号约 26MB，无显式依赖者，属 populate_sdk 对 glibc dbg 打包逻辑残留，不影响交叉编译）。
15. **bbappend 命名坑**：无版本号的 recipe（如 `nativesdk-packagegroup-sdk-host.bb`）的 bbappend 必须命名 `xxx.bbappend`，`xxx_%.bbappend` 会报 `No recipes in default available for`。

## 12. Git 仓库（gitee）

- manifest 仓库：`https://gitee.com/yangdonggit/yocto_manifest`（repo 方式，default.xml → opiz3-mini.xml；opiz3.xml）
- 脚本仓库：`https://gitee.com/yangdonggit/opiz3-scripts`（build.sh / README.md / deploy_sftp_server.sh，repo sync 后位于工程根）
- 自建层：`https://gitee.com/yangdonggit/meta-opiz3`
- 上游 6 层：openembedded-core / bitbake / meta-openembedded / meta-arm / meta-sunxi / meta-opiz3（版本见 §5，经 manifest 固定）

## 13. 后续计划

- [ ] opiz3（标准镜像）在新构建机（192.168.65.128）完整构建一次并核验产物
- [ ] 若需继续压缩 SDK：激进档（裁 gdb-cross-canadian + 精简 python3 子包）可再省 30–50MB，代价是失去 PC 端交叉调试
- [ ] 若需恢复 WiFi-BT（UWE5622 / AW859A）：恢复 BT/RFKILL/CFG80211 内核 fragment 与 meta-sunxi 固件配置
- [ ] 内核第二轮深度裁剪项（SPI/x86 网卡/SCSI/ATA）待定位启动异常根因后选择性恢复

## 14. Yocto 常用命令速查

以下均在**当前工程根**执行（先进入对应构建目录 `build_distro/opiz3-mini` 或 `build_distro/opiz3`）。

### 14.1 手动设置环境变量（进入 bitbake 环境）

```bash
cd build_distro/opiz3-mini            # 或 build_distro/opiz3
export PATH=$PWD/../../sources/bitbake/bin:$PWD/../../sources/openembedded-core/scripts:$PATH
source ../../sources/openembedded-core/oe-init-build-env .     # ★ 必须带 "." 参数
# 日常构建推荐直接：
./build.sh opiz3-mini                 # 交互选择 distro 或带参数直接构建
```

### 14.2 编译全部

```bash
bitbake core-image-minimal            # opiz3-mini 完整镜像
bitbake core-image-base               # opiz3 完整镜像
```

### 14.3 编译某个包

```bash
bitbake hello-cmake                   # 编译 hello-cmake（自动解析依赖）
bitbake linux-mainline                # 只编译内核
bitbake -c compile hello-cmake        # 只执行 compile 任务（跳过 fetch/unpack/configure）
bitbake -f -c compile linux-mainline  # 强制重跑该任务（无视缓存）
```

### 14.4 查看有效的 layers

```bash
bitbake-layers show-layers            # 列出所有已加载层与优先级
bitbake-layers show-recipes | grep hello   # 在层中搜索配方
```

### 14.5 添加 / 删除 layer

```bash
bitbake-layers add-layer <工程根>/sources/meta-opiz3
bitbake-layers remove-layer meta-opiz3
```

### 14.6 编译输出日志

```bash
# 单包任务日志（temp 目录，按任务分文件）
ls tmp/work/cortexa53-crypto-opiz3-linux/hello-cmake/1.0/temp/
tail -f tmp/work/cortexa53-crypto-opiz3-linux/hello-cmake/1.0/temp/log.do_compile
# bitbake 实时详细输出
bitbake -v hello-cmake                # 显示实际执行的每条命令
bitbake -D hello-cmake                # 调试级输出
```

### 14.7 清除某个包

```bash
bitbake -c cleanall hello-cmake       # 最彻底：工作区+下载+sstate 全清
bitbake -c clean hello-cmake          # 仅删工作区
bitbake -c cleansstate hello-cmake    # 清 sstate 缓存（保留下载，重建较快）
```

### 14.8 输出编译过程

```bash
bitbake -v core-image-minimal         # 详细过程输出
bitbake -k core-image-minimal         # 出错继续执行（收集全部错误）
tail -f tmp/log/cooker.log            # 全局构建日志（bitbake 服务器端）
```

### 14.9 哪些包处于哪个阶段

```bash
bitbake -s | grep hello               # 列出包与版本（含所在层）
# 构建进行中实时查看任务进度（日志中的 NOTE 行）：
tail -f <构建日志> | grep 'Running task'   # 形如 "Running task 1234 of 3661 (.../xxx.bb:do_compile)"
bitbake -e hello-cmake | grep '^S='       # 查看某包关键变量（S/SRC_URI/DEPENDS 等）
bitbake -g core-image-minimal         # 生成依赖图 depends.dot / task-depends.dot
```

### 14.10 生成 SDK 工具链（meta-toolchain）

```bash
cd build_distro/opiz3-mini
export PATH=$PWD/../../sources/bitbake/bin:$PWD/../../sources/openembedded-core/scripts:$PATH
source ../../sources/openembedded-core/oe-init-build-env .     # ★ 带 "." 参数
bitbake meta-toolchain
# 产物：tmp/deploy/sdk/oecore-meta-toolchain-....sh（99 MB，已裁剪，见 §11.14）
```

**安装与使用 SDK**：
```bash
./oecore-meta-toolchain-...sh          # 自解压安装（默认 /usr/local/oecore-x86_64/，可改路径）
source /usr/local/oecore-x86_64/environment-setup-cortexa53-crypto-opiz3-linux
# 之后可直接交叉编译：
$CC hello.c -o hello
$CXX app.cpp -o app
cmake / make / autotools 工程也走 SDK 提供的 CC/CXX/SYSROOT 环境
```

> 说明：SDK 是独立可安装的交叉工具链（gcc-cross-canadian 15.3.0 / binutils 2.46.1 / gdb 17.2 / cmake 4.3.1 等），与构建机内已存在的编译器无关；已裁剪 qemu/locale/dbg（§11.13/§11.14），生成时**不再下载 llvm**。

## 15. devtool 开发工作流（U-Boot / 内核 / 内核模块 / 用户态）

devtool 基于 workspace 层做源码级开发：`devtool modify <recipe>` 把 recipe 源码解包到 `build_distro/<distro>/workspace/sources/<name>/`，修改后可增量构建、部署到目标板或重新打镜像；`devtool finish` 把改动收回到 meta 层。

### 15.1 准备

```bash
cd build_distro/opiz3-mini
source ../../sources/openembedded-core/oe-init-build-env .    # ★ 必须带 "." 参数
# 不带参数时 oe-init-build-env 默认在当前目录新建 build/ 子目录（BDIR="build"），
# 会得到无层配置的空环境（MACHINE=qemux86-64、DISTRO=nodistro），
# devtool 将解析到 oe-core 通用 recipe，而非本工程 meta-sunxi 的 u-boot / 内核。
# devtool 首次使用会自动创建 workspace 层并加入 bblayers.conf
devtool status    # 查看正在开发的 recipe
```

> **环境正确性自查**：source 后执行
> `bitbake -e 2>/dev/null | grep -E '^MACHINE=|^DISTRO='`，
> 正确输出应为 `MACHINE="orange-pi-zero3"`、`DISTRO="opiz3-mini"`；
> 若显示 `qemux86-64` / `nodistro`，说明进错了 build 目录（或误建了 build/ 子目录），
> 退出后按上方**带 "." 参数**的方式重新 source。

### 15.2 U-Boot 开发

```bash
devtool modify u-boot                                   # 解包 u-boot 源码到 workspace/sources/u-boot
# 修改源码（board/orange-pi-zero3、include/configs 等）
devtool build u-boot                                    # 增量编译
devtool deploy-target u-boot root@192.168.16.101        # 部署到目标板
# 或重新打镜像整体烧录：
devtool build-image core-image-minimal
# 收尾：改动提交到自建层
devtool finish u-boot meta-opiz3
```

### 15.3 内核代码开发

```bash
devtool modify linux-mainline                           # 解包内核源码（6.18.40）
# 修改 drivers/arch 等；meta-opiz3 的 fragment（opiz3.cfg）经 bbappend 合并仍生效
devtool build linux-mainline
# 内核不在 rootfs，推荐整体打镜像或手工部署内核+dtb：
devtool build-image core-image-minimal
# 手工取产物（Image.gz / dtb）：
ls build_distro/opiz3-mini/tmp/deploy/images/orange-pi-zero3/Image.gz*
# 收尾
devtool finish linux-mainline meta-opiz3
```

### 15.4 内核模块开发

```bash
# 方式 A：在已有模块 recipe 上开发
devtool modify <module-recipe>                          # 如 hello-mod
# 方式 B：从零新增模块（源码目录或外部 git）
devtool add mymodule /path/to/src                       # 自动生成 recipe 并纳入 workspace
# 构建并部署到目标板（ko 装入 /lib/modules/$(uname -r)/ 后 modprobe）
devtool build <module-name>
devtool deploy-target <module-name> root@192.168.16.101
# 或打进镜像
devtool build-image core-image-minimal
```

### 15.5 用户态（应用）开发

```bash
devtool modify <app-recipe>                             # 已有 recipe（如 yocto-version-test）
devtool add myapp /path/to/src                          # 新应用，自动生成 recipe
# 修改代码（CMake / Makefile / autotools 均可）
devtool build <app>                                     # 交叉编译
devtool build-image core-image-minimal                  # 打进 rootfs
# 或只部署二进制到目标板
devtool deploy-target <app> root@192.168.16.101
# 收尾
devtool finish <app> meta-opiz3
```

### 15.6 常用辅助命令

```bash
devtool status                         # 列出 workspace 中正在开发的 recipe
devtool build <recipe>                 # 构建（增量）
devtool build-image <image>            # 构建镜像（含 workspace 改动）
devtool deploy-target <r> <user@ip>    # 部署包到目标板
devtool undeploy-target <r> <user@ip>  # 撤销部署
devtool reset <recipe>                 # 丢弃 workspace 改动，恢复原状
devtool finish <recipe> <layer>        # 把改动提交到指定层并移出 workspace
devtool update-recipe <recipe>         # 把改动写回 recipe（保留在 workspace）
```

### 15.7 `devtool finish` 的行为（生成 patch 文件）

`devtool finish <recipe> <layer>` 收尾时，会把 workspace 中的源码改动**导出为 patch 文件并固化到目标层**，具体动作：

1. **生成 patch**：在目标层的 recipe 目录下创建 `<PN>/` 子目录，写入补丁文件
   （例：`<layer>/recipes-test/hello-auto/hello-auto/0001-<描述>.patch`）；
2. **改 recipe**：在对应 `.bb` 的 `SRC_URI` 追加 `file://0001-<描述>.patch`
   （patch 位于 `<PN>/` 子目录，bitbake 的 FILESPATH 默认搜索 recipe 目录与 `<PN>/` 子目录，可直接引用）；
3. **移出 workspace**：recipe 从 workspace 移除（等价 reset），后续 bitbake 直接使用打了 patch 的层内 recipe。

> 验证示例：`devtool finish hello-auto meta-opiz3` 后，
> `meta-opiz3/recipes-test/hello-auto/hello-auto_1.0.bb` 出现
> `SRC_URI = "... file://0001-test-devtool2.patch"`，patch 位于
> `recipes-test/hello-auto/hello-auto/0001-test-devtool2.patch`。
> 若 patch 内容不需要保留，可 `git checkout <bb>` 并删除 `<PN>/` 目录还原。

### 15.8 常用提示

> 提示：
> - 目标板访问：`root@192.168.16.101`（密码 111111，dropbear）。
> - **`deploy-target` 传输协议（重要，已解决）**：devtool 内部调用系统 `scp`，OpenSSH 9.x 默认走 **SFTP 子系统**；板端 dropbear 不自带 `sftp-server`，会报 `sh: /usr/libexec/sftp-server: not found` / `scp: Connection closed`（dropbear 只内置传统 SCP，手动 `scp -O` 可通）。
>   - **已固化（推荐）**：mini 镜像 `meta-opiz3/recipes-core/images/core-image-minimal.bbappend` 已增加 `openssh-sftp-server`，重建烧录后 SFTP 原生可用，无需任何 wrapper。mini 镜像体积约 19 MB（已含该子包）。
>   - **免重刷过渡**：当前已上电的板子可执行 `./deploy_sftp_server.sh`（构建 openssh 并拷贝 sftp-server 到板端 `/usr/libexec/`），无需重刷。
>   - **临时 wrapper 备选**（不便构建时）：`mkdir -p ~/bin; printf '#!/bin/bash\nexec /usr/bin/scp -O "$@"\n' > ~/bin/scp && chmod +x ~/bin/scp; export PATH=$HOME/bin:$PATH`
>   - 首次连接若提示指纹确认：`ssh-keyscan -H 192.168.16.101 >> ~/.ssh/known_hosts`。
> - 内核/U-Boot 改动影响启动流程，建议 `devtool build-image` 后整卡烧录验证，避免仅覆盖 boot 分区导致起不来。
> - devtool 改动只存在于 workspace（不入层）；`finish` 后才会写入 meta 层。内核 config 类改动建议直接改 meta-opiz3 的 `opiz3.cfg` + bbappend，而非走 devtool 工作区。