> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Yocto 构建故障排除

本页面记录了在 Qualcomm Linux 上进行 Yocto 构建时遇到的常见错误
及其解决方案。

## 缺少 `en_US.UTF-8` 区域设置

**发生场景**：此问题在最小化的 Ubuntu 安装（包括
基础 WSL2 镜像 (Ubuntu 22.04)）上很常见，这些安装默认只提供 `C.UTF-8` 区域设置。
BitBake 需要 `en_US.UTF-8` 区域设置，如果不存在则会
在启动时立即失败。

**错误消息**：

```
Please make sure locale 'en_US.UTF-8' is available on your system
```

**解决方案**：在运行任何 `kas` 或 `bitbake` 命令之前，
生成并启用 `en_US.UTF-8` 区域设置。

```bash theme={null}
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8
```

运行这些命令后，打开一个新的 shell 会话，使更新后的
区域设置生效，然后重试构建。

***

## 严格的 `umask` 导致构建失败

**发生场景**：如果您的 shell 会话配置了严格的 `umask`
（例如 `0027` 或 `0077`），OE-core 的完整性检查器会在构建开始前
拒绝该配置。

**错误消息**：

```
ERROR:  OE-core's config sanity checker detected a potential misconfiguration.
    Either fix the cause of this error or at your own risk disable the checker (see sanity.conf).
    Following is the list of potential problems / advisories:

    Please use a umask which allows a+rx and u+rwx
```

**解决方案**：在开始构建之前，在您的 shell 中设置 `umask 022`。这样可以确保
Yocto 创建的文件对所有用户可读，这是构建系统正常
运行所必需的。

```bash theme={null}
umask 022
```

要使此设置在您的构建会话中持久生效，请将其添加到您的 shell 启动文件中：

```bash theme={null}
echo 'umask 022' >> ~/.bashrc
source ~/.bashrc
```