i.MX95 Yocto BSP 构建指南 · WSL2 Windows 篇
# i.MX95 Yocto BSP 构建指南 · WSL2 Windows 篇**版本**：LF6.18.2-1.0.0 | Yocto 5.3 Whinlatter
**目标平台**：imx95-15x15-lpddr4x-frdm
**宿主环境**：Windows 10/11 + WSL2 Ubuntu 22.04 LTS
---
◆
## 概述
本文档提供在 Windows WSL2 环境下构建 i.MX95 Yocto BSP 的完整工程路径。WSL2 并非原生 Linux，其存储模型（VHDX 虚拟磁盘）、文件系统桥接（9P 协议挂载 `<span leaf="">/mnt/*</span>`）及网络代理机制与裸机 Ubuntu 存在显著差异，需针对性处理。
**前置条件**：Windows 宿主机 D 盘（或同等非系统盘）剩余空间不低于 400 GB。空间不足将导致构建阶段出现 `<span leaf="">ENOSPC</span>` 错误。
---
◆
## 一、Windows 宿主机准备
### 1.1 启用 WSL2 与虚拟化平台
以管理员身份打开 PowerShell，执行以下命令：
```
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
```
执行完毕后重启 Windows。
重启后设置 WSL 默认版本：
```
wsl --set-default-version 2
```
---
◆
## 二、WSL2 实例部署至 D 盘
### 2.1 部署方式选择
通过 Microsoft Store 或 `<span leaf="">wsl --install</span>` 安装的发行版默认注册至 Windows 应用包目录（`<span leaf="">C:\Users\<用户名>\AppData\Local\Packages\...</span>`），无法在安装阶段指定盘符。推荐直接使用 `<span leaf="">wsl --import</span>` 从 Ubuntu 官方 rootfs 镜像在 D 盘创建实例，绕过 Store 机制，避免后续迁移操作。
### 2.2 下载 Ubuntu 22.04 rootfs
```
mkdir D:\WSL\Ubuntu-22.04
# 官方源
curl.exe -k -L -o D:\WSL\ubuntu-22.04-rootfs.tar.gz `
https://cloud-images.ubuntu.com/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz
# 国内网络建议使用清华大学镜像站：
# curl.exe -k -L -o D:\WSL\ubuntu-22.04-rootfs.tar.gz `
# https://mirrors.tuna.tsinghua.edu.cn/ubuntu-cloud-images/wsl/jammy/current/ubuntu-jammy-wsl-amd64-ubuntu22.04lts.rootfs.tar.gz
```
下载完成后确认文件大小（约 300\~350 MB）。
### 2.3 导入实例
```
wsl --import Ubuntu-22.04 D:\WSL\Ubuntu-22.04 D:\WSL\ubuntu-22.04-rootfs.tar.gz --version 2
Remove-Item D:\WSL\ubuntu-22.04-rootfs.tar.gz
```
`<span leaf="">wsl --import</span>` 在 `<span leaf="">D:\WSL\Ubuntu-22.04\</span>` 下生成 `<span leaf="">ext4.vhdx</span>` 虚拟磁盘，与 Store 安装的磁盘文件格式一致。
### 2.4 创建普通用户
`<span leaf="">wsl --import</span>` 创建的实例默认以 `<span leaf="">root</span>` 登录，需手动创建普通用户：
```
wsl -d Ubuntu-22.04
```
在 WSL2 内部执行：
```
useradd -m -s /bin/bash nxp
passwd nxp
usermod -aG sudo nxp
exit
```
### 2.5 设置默认登录用户
方式一（推荐）：
```
ubuntu2204 config --default-user nxp
```
方式二（部分 Windows 版本无 `<span leaf="">ubuntu2204.exe</span>` 时使用 `<span leaf="">wsl.conf</span>`）：
```
wsl -d Ubuntu-22.04 -u root
```
在 WSL2 内部：
```
echo -e "\ndefault = nxp" | sudo tee /etc/wsl.conf
exit
```
回到 PowerShell：
```
wsl --shutdown
wsl -d Ubuntu-22.04
```
### 2.6 验证
```
wsl --list --verbose
# 预期输出：Ubuntu-22.04 Running 2
```
---
◆
## 三、存储规划与 VHDX 管理
### 3.1 VHDX 容量说明
`<span leaf="">wsl --import</span>` 创建的 `<span leaf="">ext4.vhdx</span>` 默认虚拟上限为 1024 GB。该值为动态扩展磁盘声明的最大容量，并非实际占用。实际占用由 `<span leaf="">Physical size</span>` 反映，随 WSL2 内写入数据而增长。硬约束为 D 盘物理剩余空间（约 476 GB），无需关注 1024 GB 的虚拟上限。
### 3.2 构建目录布局
Yocto 官方文档明确：WSL2 下构建目录（`<span leaf="">TMPDIR</span>`）不可置于 `<span leaf="">/mnt/c/</span>`、`<span leaf="">/mnt/d/</span>` 等 Windows 挂载点。这些路径通过 9P 协议桥接，文件元数据映射不完整，将导致 BitBake 任务出现权限错误、符号链接失效及性能显著下降。
推荐布局：
| 目录 | 位置 | 说明 |
| --------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |
| `TMPDIR`（编译中间文件） | `/home//imx-yocto-bsp/build-*/tmp` | 必须位于 WSL2 原生 ext4 内 |
| `DL_DIR`（源码下载） | `/mnt/d/yocto-disk/downloads` | 可外置至 D 盘，节省 VHDX 空间 |
| `SSTATE_DIR`（共享缓存） | `/mnt/d/yocto-disk/sstate-cache` | 可外置至 D 盘，跨构建复用 |
| 最终镜像输出 | `tmp/deploy/images/...` | 原生 ext4 内，烧录前复制至`/mnt/d` |
在 `<span leaf="">local.conf</span>` 中显式声明：
```
DL_DIR = "/mnt/d/yocto-disk/downloads"
SSTATE_DIR = "/mnt/d/yocto-disk/sstate-cache"
# TMPDIR 默认位于 build-*/tmp，不建议将其指向 /mnt/d
```
### 3.3 VHDX 空间回收
Yocto 构建删除文件后，`<span leaf="">ext4.vhdx</span>` 不会自动收缩。建议每完成 2\~3 次完整构建后执行回收：
```
# WSL2 内清理构建残留
rm -rf ~/imx-yocto-bsp/build-*/tmp/work/*
exit
```
```
# Windows 侧压缩（需 Hyper-V，适用于 Pro/Enterprise）
wsl --shutdown
Optimize-VHD -Path "D:\WSL\Ubuntu-22.04\ext4.vhdx" -Mode Full
```
Windows Home 版无 Hyper-V，无法使用 `<span leaf="">Optimize-VHD</span>`。此时可通过 `<span leaf="">wsl --export</span>` + `<span leaf="">wsl --import</span>` 重新导出导入回收空间，或清理工作目录后接受 VHDX 膨胀。
---
◆
## 四、Ubuntu 环境配置
### 4.1 APT 镜像源
国内网络环境下，建议更换为清华大学开源软件镜像站：
```
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak
sudo tee /etc/apt/sources.list << 'EOF'
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-updates main restricted universe multiverse
deb https://mirrors.tuna.tsinghua.edu.cn/ubuntu/ jammy-backports main restricted universe multiverse
deb http://security.ubuntu.com/ubuntu/ jammy-security main restricted universe multiverse
EOF
sudo apt update && sudo apt upgrade -y
```
`<span leaf="">security.ubuntu.com</span>` 保留官方地址，因安全更新对时效性敏感，镜像站可能存在同步延迟。
### 4.2 基础依赖
```
sudo apt install -y \
build-essential chrpath cpio git python3 debianutils diffstat \
file gawk gcc iputils-ping libacl1 liblz4-tool locales \
python3-git python3-jinja2 python3-pexpect python3-pip \
python3-subunit socat texinfo unzip wget xz-utils zstd \
efitools g++-multilib gcc-multilib gdisk libusb-1.0-0-dev \
libncurses5-dev libncursesw5-dev bison flex libssl-dev \
u-boot-tools device-tree-compiler bc rsync
```
### 4.3 Locale 与文件描述符
```
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8
echo "ulimit -n 65536" >> ~/.bashrc
source ~/.bashrc
```
### 4.4 WSL2 专属优化
在 Windows 用户目录（`<span leaf="">C:\Users\<用户名>\</span>`）创建或编辑 `<span leaf="">.wslconfig</span>`：
```
memory=24GB
processors=8
localhostForwarding=true
nestedVirtualization=true
```
修改后执行 `<span leaf="">wsl --shutdown</span>` 重启生效。
**Windows Defender 排除**：
```
Add-MpPreference -ExclusionPath "\\wsl$\Ubuntu-22.04\home\"
Add-MpPreference -ExclusionPath "D:\WSL\"
```
---
◆
## 五、Repo 工具与代码同步
### 5.1 Repo 安装
Repo 工具官方源（Google）在国内访问受限，建议优先采用国内镜像站。以下提供三个安装源，根据网络条件选择：
**方案一：清华大学开源软件镜像站（国内网络推荐）**
```
mkdir -p ~/bin
export PATH=~/bin:$PATH
curl -o ~/bin/repo https://mirrors.tuna.tsinghua.edu.cn/git/git-repo
chmod a+x ~/bin/repo
repo --version # >= v2.52
```
**方案二：中国科学技术大学镜像站（国内网络备选）**
```
mkdir -p ~/bin
export PATH=~/bin:$PATH
curl -o ~/bin/repo https://mirrors.ustc.edu.cn/git/git-repo
chmod a+x ~/bin/repo
repo --version
```
**方案三：Google 官方源（海外网络或代理通畅时使用）**
```
mkdir -p ~/bin
export PATH=~/bin:$PATH
curl -o ~/bin/repo https://gerrit.googlesource.com/git-repo/repo
chmod a+x ~/bin/repo
repo --version
```
> 国内网络环境下，若直接访问 Google 源，大概率出现 `<span leaf="">Connection timed out</span>` 或 `<span leaf="">Could not resolve host</span>`。建议先测试 `<span leaf="">curl -I https://gerrit.googlesource.com</span>`，若返回正常再选用方案三。
### 5.2 仓库初始化与同步
工作目录必须位于 WSL2 原生 ext4，不可置于 `<span leaf="">/mnt/d</span>`。`<span leaf="">repo init</span>` 的 `<span leaf="">--repo-url</span>` 参数需与 5.1 节的 repo 安装源保持一致：
**国内网络（清华大学镜像）**
```
mkdir -p ~/imx-yocto-bsp && cd ~/imx-yocto-bsp
repo init \
--repo-url=https://mirrors.tuna.tsinghua.edu.cn/git/git-repo \
-u https://github.com/nxp-imx/imx-manifest \
-b imx-linux-whinlatter \
-m imx-6.18.2-1.0.0.xml
```
**国内网络（中科大镜像）**
```
mkdir -p ~/imx-yocto-bsp && cd ~/imx-yocto-bsp
repo init \
--repo-url=https://mirrors.ustc.edu.cn/git/git-repo \
-u https://github.com/nxp-imx/imx-manifest \
-b imx-linux-whinlatter \
-m imx-6.18.2-1.0.0.xml
```
**海外网络（Google 官方源）**
```
mkdir -p ~/imx-yocto-bsp && cd ~/imx-yocto-bsp
repo init \
--repo-url=https://gerrit.googlesource.com/git-repo \
-u https://github.com/nxp-imx/imx-manifest \
-b imx-linux-whinlatter \
-m imx-6.18.2-1.0.0.xml
```
参数说明：
* `<span leaf="">--repo-url</span>`：repo 工具本身的下载源，需与 5.1 节选用的安装源保持一致
* `<span leaf="">-u https://github.com/nxp-imx/imx-manifest</span>`：NXP i.MX 官方 manifest 仓库地址
* `<span leaf="">-b imx-linux-whinlatter</span>`：Yocto 5.3 Whinlatter 分支
* `<span leaf="">-m imx-6.18.2-1.0.0.xml</span>`：BSP LF6.18.2-1.0.0 版本 manifest 文件
执行代码同步：
```
repo sync -c -j$(nproc) # 网络不稳时降至 -j2
```
---
◆
## 六、构建环境初始化
`<span leaf="">repo sync</span>` 完成后，进入 BSP 根目录并执行 NXP 特有的环境初始化脚本 `<span leaf="">imx-setup-release.sh</span>`。该脚本将创建 `<span leaf="">build-*/</span>` 目录、生成 `<span leaf="">conf/local.conf</span>` 与 `<span leaf="">conf/bblayers.conf</span>`，并将当前 shell 切换为 BitBake 构建环境。
```
cd ~/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
```
参数说明：
* `<span leaf="">MACHINE=imx95-15x15-lpddr4x-frdm</span>`：目标硬件平台，对应 FRDM-IMX95 开发板
* `<span leaf="">DISTRO=fsl-imx-xwayland</span>`：发行版配置，启用 XWayland 图形栈
* `<span leaf="">-b build-imx95-xwayland-15x15-lpddr4x-frdm</span>`：指定构建输出目录名
执行后提示符显示 `<span leaf="">$</span>`，表示已进入 BitBake 构建环境。
**注意**：每次新开终端或重新进入 WSL2，均需重新执行上述 `<span leaf="">source</span>` 命令进入构建环境，否则 `<span leaf="">bitbake</span>` 命令不可用。
---
◆
## 七、代理环境配置
### 7.1 网络访问现状
Yocto 构建需访问的外部仓库及其国内可用性：
* `<span leaf="">github.com</span>`：大量软件包源码，国内访问受限
* `<span leaf="">android.googlesource.com</span>`：`<span leaf="">gfxstream</span>` 等组件依赖
* `<span leaf="">gitlab.freedesktop.org</span>`：`<span leaf="">shared-mime-info</span>` 等包
* `<span leaf="">crates.io</span>`：Rust 生态 crate 仓库，下载量大且速度慢
直接全局代理会导致 Yocto 官方镜像源（`<span leaf="">mirrors.edge.kernel.org</span>`、`<span leaf="">ftpmirror.gnu.org</span>`）SSL 握手异常。应采用**分流代理**：外部受限源走代理，官方镜像源直接连接。
### 7.2 代理工具
本地部署 Xray 作为代理入口，监听：
* HTTP 代理：`<span leaf="">127.0.0.1:7890</span>`
* SOCKS5 代理：`<span leaf="">127.0.0.1:1080</span>`
针对 Yocto 构建场景整理的开源配置（含 `<span leaf="">xray-config.json</span>`、`<span leaf="">proxy.sh</span>` 管理脚本及优化 `<span leaf="">no_proxy</span>` 绕过列表）：
**https://github.com/fafactx/vpn-for-yocto**
建议克隆至 `<span leaf="">/mnt/d/yocto-disk/vpn-for-yocto</span>`：
```
cd /mnt/d/yocto-disk
git clone https://github.com/fafactx/vpn-for-yocto.git
```
### 7.3 启动与验证
```
cd /mnt/d/yocto-disk/vpn-for-yocto
./proxy.sh start
./proxy.sh test
```
手动验证：
```
curl -I --connect-timeout 15 -x http://127.0.0.1:7890 https://github.com
curl -I --connect-timeout 15 -x http://127.0.0.1:7890 https://android.googlesource.com
```
确认返回 HTTP 200 后再进入构建阶段。
### 7.4 构建环境变量
进入 Yocto 构建环境后导出代理变量：
```
cd ~/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export no_proxy="localhost,127.0.0.1,.local,.internal,192.168.0.0/16,10.0.0.0/8,*.tuna.tsinghua.edu.cn,mirrors.edge.kernel.org,ftpmirror.gnu.org,*.yoctoproject.org"
export NO_PROXY="${no_proxy}"
```
`<span leaf="">no_proxy</span>` 必须包含 `<span leaf="">mirrors.edge.kernel.org</span>` 及 `<span leaf="">*.yoctoproject.org</span>`。遗漏将导致构建过程中出现 `<span leaf="">OpenSSL: error:0A000126:SSL routines::unexpected eof while reading</span>` 错误，该错误与网络代理相关，而非源码本身问题。
### 7.5 Fetch 工作流（分阶段迭代）
不建议直接执行 `<span leaf="">bitbake imx-image-full</span>` 启动完整构建。应先通过多轮迭代将全部源码包 fetch 至本地，确认无网络缺失后再进入编译阶段。
**第一轮：无代理摸底**
```
cd ~/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
bitbake imx-image-full --runall=fetch
```
约 70%\~80% 的包从官方镜像源成功下载，剩余因网络受限失败，典型报错为 `<span leaf="">exit code 128</span>`、`<span leaf="">Connection timed out</span>`。
**第二轮：定位失败包**
```
grep -r "Fetcher failure" tmp/log/cooker/*/console-latest.log | head -20
grep -r "exit code 128" tmp/work/*/temp/log.do_fetch | head -20
```
常见失败包：
| 源码仓库 | 典型失败包 |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `github.com` | `matter-idl-native`,`imx-gpu-sdk`,`meta-imx`组件 |
| `android.googlesource.com` | `gfxstream` |
| `gitlab.freedesktop.org` | `shared-mime-info` |
| `crates.io` | `python3-maturin-native`及 cargo 依赖 |
**第三轮：代理补包**
启动代理后，重新进入构建环境，仅对失败包设置代理并重新 fetch：
```
cd ~/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy="localhost,127.0.0.1,..."
bitbake matter-idl-native gfxstream shared-mime-info python3-maturin-native --runall=fetch
```
**第四轮：验证**
关闭代理，重新进入构建环境，再次执行全量 fetch：
```
cd ~/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
bitbake imx-image-full --runall=fetch
```
若仍有失败，重复第二轮至第三轮，直至连续两次无报错通过。
**第五轮：编译**
全部缓存至 `<span leaf="">DL_DIR</span>` 后，重新进入构建环境并编译：
```
cd ~/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
bitbake imx-image-full
```
WSL2 下构建耗时通常比裸机慢 10%\~20%，典型范围为 10\~14 小时（视 `<span leaf="">.wslconfig</span>` 分配的内存与核心数而定）。
编译期间建议保持代理可用，或在 `<span leaf="">local.conf</span>` 中设置 `<span leaf="">BB_NO_NETWORK = "1"</span>`（前提是 fetch 阶段已完全通过）。
---
◆
## 八、磁盘空间优化
D 盘可用空间约 476 GB，Yocto 默认构建峰值可达 500 GB+。以下配置应组合使用，整体追加至 `<span leaf="">build-*/conf/local.conf</span>`：
```
# ===== WSL2 最小化空间配置 =====
INHERIT += "rm_work"
IMAGE_FSTYPES = "wic"
PACKAGE_CLASSES = "package_ipk"
DL_DIR = "/mnt/d/yocto-disk/downloads"
SSTATE_DIR = "/mnt/d/yocto-disk/sstate-cache"
IMAGE_GEN_DEBUGFS = "0"
# =================================
```
* `<span leaf="">rm_work</span>`：编译完成后删除中间文件，节省 60%\~70% 空间
* `<span leaf="">wic</span>` 单格式：禁用体积较大的 tarball 输出
* `<span leaf="">ipk</span>`：包格式体积优于 deb/rpm
* `<span leaf="">DL_DIR</span>` / `<span leaf="">SSTATE_DIR</span>` 外置：VHDX 内仅保留编译中间态
启用后峰值约 150\~200 GB（VHDX 内），配合外置缓存，总空间需求约 250\~300 GB。
如需保留特定包用于调试：
```
INHERIT += "rm_work"
RM_WORK_EXCLUDE += "linux-imx u-boot-imx"
```
---
◆
## 九、镜像构建与输出
### 9.1 执行构建
```
cd ~/imx-yocto-bsp
MACHINE=imx95-15x15-lpddr4x-frdm DISTRO=fsl-imx-xwayland \
source imx-setup-release.sh -b build-imx95-xwayland-15x15-lpddr4x-frdm
bitbake imx-image-full
```
### 9.2 构建产物
构建成功后，关键输出位于：
```
~/imx-yocto-bsp/build-imx95-xwayland-15x15-lpddr4x-frdm/tmp/deploy/images/imx95-15x15-lpddr4x-frdm/
```
| 文件 | 说明 |
| --------------------------------------------------------- | -------------------------- |
| `imx-image-full-*.wic` | 完整磁盘镜像，可直接烧录 |
| `imx-boot-*-sd.bin-flash` | SD 卡启动引导程序 |
| `Image` | Linux 内核镜像 |
| `imx95-15x15-lpddr4x-frdm.dtb` | 设备树二进制 |
### 9.3 镜像转移至 Windows 侧烧录
将 WIC 镜像复制至 Windows 侧：
```
cp ~/imx-yocto-bsp/build-*/tmp/deploy/images/imx95-15x15-lpddr4x-frdm/imx-image-full-*.wic \
/mnt/d/yocto-disk/output/
```
WSL2 不原生支持 USB 设备直通。SD 卡烧录建议在 Windows 侧使用 Rufus 或 balenaEtcher，加载 `<span leaf="">D:\yocto-disk\output\</span>` 下的 WIC 文件。
---
◆
## 十、常见问题与解决
**Q1：nxp-wlan 编译报错，找不到 `<span leaf="">/lib/modules/.../build</span>`**
WSL2 内核由 Microsoft 提供，默认未包含内核头文件与构建工具，导致 out-of-tree 内核模块无法编译。需手动补装对应版本内核源码：
```
uname -r # 记录版本号，如 5.15.167.4-microsoft-standard-WSL2
cd ~
wget https://github.com/microsoft/WSL2-Linux-Kernel/archive/$(uname -r).tar.gz
tar xf $(uname -r).tar.gz
cd WSL2-Linux-Kernel-$(uname -r)/
make defconfig
sudo make modules_prepare
sudo mkdir -p /lib/modules/$(uname -r)/build
sudo ln -s $(pwd) /lib/modules/$(uname -r)/build
```
完成后重新触发 `<span leaf="">bitbake imx-image-full</span>` 中失败的 nxp-wlan 任务。
**Q2：构建中报 `<span leaf="">No space left on device</span>`**
1. WSL2 内执行 `<span leaf="">df -h /</span>`，确认根分区使用率。若接近 100%，说明 VHDX 物理空间已耗尽。
2. Windows 侧检查 D 盘物理剩余空间。
3. WSL2 内执行 `<span leaf="">rm -rf build-*/tmp/work/*</span>`，然后按 3.3 节压缩 VHDX 或重新导出导入。
**Q3：`<span leaf="">Timeout while waiting for a reply from the bitbake server</span>`**
通常由 WSL2 内存或交换空间不足导致 BitBake 进程被 OOM Killer 终止。处理：
```
sudo fallocate -l 16G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
```
同时检查 `<span leaf="">.wslconfig</span>` 中的 `<span leaf="">memory</span>` 分配是否过低。
**Q4：`<span leaf="">ln: failed to create symbolic link: Operation not permitted</span>`**
构建目录置于 `<span leaf="">/mnt/d/</span>` 等 Windows 挂载点所致。9P 协议不支持完整 Linux 文件语义。TMPDIR 必须位于 `<span leaf="">/home/<user>/</span>` 下的 WSL2 原生 ext4 路径。
---
◆
## 附录
### A. 代理环境变量
```
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export no_proxy="localhost,127.0.0.1,.local,.internal,192.168.0.0/16,10.0.0.0/8,*.tuna.tsinghua.edu.cn,mirrors.edge.kernel.org,ftpmirror.gnu.org,*.yoctoproject.org"
export NO_PROXY="${no_proxy}"
```
### B. WSL2 磁盘管理
| 操作 | 命令 |
| ----------- | ------------------------------------------------------------------------------------------ |
| 关闭 WSL2 | `wsl --shutdown` |
| 压缩 VHDX | `Optimize-VHD -Path "D:\WSL\Ubuntu-22.04\ext4.vhdx" -Mode Full` |
| 查看内存| `free -h` |
### C. 构建参数汇总
| 参数 | 值 |
| ------------- | -------------------------- |
| BSP 版本 | LF6.18.2-1.0.0 |
| Yocto 版本| 5.3 (Whinlatter) |
| Machine | imx95-15x15-lpddr4x-frdm |
| Distro | fsl-imx-xwayland |
| WSL2 发行版 | Ubuntu 22.04 LTS |
### D. 相关资源
* Yocto 代理配置仓库：https://github.com/fafactx/vpn-for-yocto
* NXP i.MX95 官方 BSP 文档
* Yocto Project 官方文档
### E. BitBake 常用命令速查
#### 基础编译
| 命令 | 作用 |
| --------------------------------------------- | ------------------------------------------------------------------- |
| `bitbake ` | 编译指定配方（执行默认 build 任务） |
| `bitbake `| 编译指定镜像，如`bitbake imx-image-full` |
#### 任务控制（`<span leaf="">-c</span>` / `<span leaf="">--runall</span>` / `<span leaf="">--runonly</span>`）
| 命令 | 作用 | 说明 |
| ------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------- |
| `bitbake-c fetch` | 仅执行 fetch 任务（下载源码） | 对应`do_fetch` |
| `bitbake-c compile` | 仅执行 compile 任务 | 对应`do_compile` |
| `bitbake-c cleansstate`| 清理 sstate 缓存并重新编译 | 删除 sstate 后执行默认任务 |
| `bitbake-c cleanall` | 完全清理配方 | 删除 work 目录、下载缓存及 sstate |
| `bitbake-c devshell` | 进入配方的开发 Shell | 用于源码调试 |
| `bitbake-c menuconfig` | 打开内核/组件菜单配置 | 仅适用于含 menuconfig 的配方 |
| `bitbake-c listtasks` | 列出该配方所有可用任务 | 由 metadata 提供 |
| `bitbake--runall=fetch`| 对目标及其依赖图中所有配方执行 fetch | 全量下载 |
| `bitbake--runonly=fetch` | 仅对目标配方执行 fetch（不处理依赖） | 仅单包 |
| `bitbake-C compile` | 清除 compile 任务的 stamp 后执行默认任务 | `-C`为大写 |
#### 执行控制
| 命令 | 作用 | 说明 |
| ------------------------------------------------------------- | -------------------------------- | --------------------------------------------------- |
| `bitbake-f` | 强制重新运行（忽略已有 stamp） | `--force` |
| `bitbake-k` | 出错后继续构建 | `--continue`，尽量多编译 |
| `bitbake-n` | 干跑，不实际执行 | `--dry-run`，仅检查依赖|
| `bitbake-p` | 仅解析配方后退出 | `--parse-only` |
| `bitbake--no-setscene` | 忽略 sstate 缓存，全部重新构建 | 不执行 setscene 任务 |
| `bitbake--skip-setscene` | 跳过 setscene 任务 | 已恢复的 sstate 保留 |
| `bitbake--setscene-only` | 仅执行 setscene 任务 | 只恢复 sstate，不编译 |
#### 调试与查看
| 命令 | 作用 | 说明 |
| ------------------------------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------------- |
| `bitbake -s` | 显示所有配方的当前版本与首选版本 | `--show-versions` |
| `bitbake -e ` | 显示配方的完整环境变量 | 可配合`grep`过滤 |
| `bitbake -e\| grep ^PV=` | 查看配方版本变量 PV | 常用技巧 |
| `bitbake -g ` | 生成依赖关系图（.dot 格式） | `--graphviz` |
| `bitbake -D ` | 提高调试级别（可多次指定） | `-D`=级别1，`-DD`=级别2 |
| `bitbake -v ` | 启用 shell 任务跟踪（`set -x`） | `--verbose` |
| `bitbake -q ` | 减少终端日志输出 | `--quiet` |
#### 服务器管理
| 命令 | 作用 | 说明 |
| -------------------------------------------------- | ------------------------------- | ------------------------------------------ |
| `bitbake -m` | 终止后台运行的 bitbake server | `--kill-server` |
| `bitbake --status-only` | 检查远程 bitbake server 状态| 仅查看 |
| `bitbake --server-only` | 仅启动 server，不启动 UI | 后台服务模式 |
#### Layer 管理（`<span leaf="">bitbake-layers</span>` 子命令）
| 命令 | 作用 |
| -------------------------------------------------------------- | ------------------------------- |
| `bitbake-layers show-layers` | 列出当前启用的所有 meta-layer |
| `bitbake-layers show-recipes` | 列出所有可用配方 |
| `bitbake-layers show-appends` | 列出所有 bbappend 文件 |
| `bitbake-layers show-cross-depends` | 显示跨 layer 依赖关系 |
#### 并行任务控制说明
`<span leaf="">bitbake</span>` 命令行不提供 `<span leaf="">-j</span>` 参数。并行任务数通过以下方式控制：
* 环境变量：`<span leaf="">export BB_NUMBER_THREADS=4</span>`
* `<span leaf="">local.conf</span>`：`<span leaf="">BB_NUMBER_THREADS = "4"</span>`
* 宿主机 CPU 数：默认自动检测 `<span leaf="">$(nproc)</span>`
页:
[1]