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

***

## 构建期间 CPU 使用率过高导致系统过载

**发生场景**：BitBake 会并行调度任务，并以多个作业调用 `make`
以加快构建速度。在 CPU 核心数量有限的主机上，或者当构建与其他
工作负载同时运行时，这可能会使 CPU 使用率非常高，导致系统无响应。

**解决方案**：通过设置 `BB_NUMBER_THREADS` 和
`PARALLEL_MAKE` 变量来限制构建的并行度，如 Yocto Project [Limiting the Host Resources
Usage](https://docs.yoctoproject.org/dev-manual/limiting-resources.html) 指南中所述。请将这些
变量添加到 `meta-qcom/ci/base.yml` 中的 `local_conf_header` 下：

```yaml meta-qcom/ci/base.yml theme={null}
local_conf_header:
  limit-parallelism: |
    BB_NUMBER_THREADS = "4"
    PARALLEL_MAKE = "-j 4"
```

根据您希望构建使用的 CPU 核心数量调整这些值，然后重新运行
`kas build` 命令。