From 610dd57b2dea509eb74d2e4fd318bc64e291d679 Mon Sep 17 00:00:00 2001
From: Tang ZZ <tangzz@radxa.com>
Date: Mon, 6 Apr 2026 01:55:31 +0800
Subject: [PATCH] fix(build-system): address issues from GitHub Discussion 1553

- Fix liblz4-tool package name for Debian 13 compatibility
- Add repo tool installation instructions
- Add Weston build error fix for missing PAM feature

Closes: #1553
---
 docs/common/yocto/_build-system.mdx | 70 ++++++++++++++++++++++++++++-
 1 file changed, 68 insertions(+), 2 deletions(-)

diff --git a/docs/common/yocto/_build-system.mdx b/docs/common/yocto/_build-system.mdx
index 781f5f14f..d543f39c0 100644
--- a/docs/common/yocto/_build-system.mdx
+++ b/docs/common/yocto/_build-system.mdx
@@ -21,9 +21,28 @@ Yocto 项目支持的 Linux 发行版：[参考链接](https://docs.yoctoproject
 sudo apt-get update
 sudo apt-get install \
     build-essential chrpath cpio debianutils diffstat file gawk gcc git \
-    iputils-ping libacl1 liblz4-tool locales python3 python3-git \
+    iputils-ping libacl1 locales python3 python3-git \
     python3-jinja2 python3-pexpect python3-pip python3-subunit socat \
-    texinfo unzip wget xz-utils zstd repo -y
+    texinfo unzip wget xz-utils zstd -y
+
+# 安装 liblz4 相关工具（不同发行版包名可能不同）
+# Ubuntu/Debian: liblz4-tool 或 liblz4-dev
+# Fedora/RHEL: lz4 lz4-devel
+# Arch Linux: lz4
+if command -v apt &> /dev/null; then
+    sudo apt-get install liblz4-tool -y || sudo apt-get install liblz4-dev -y
+elif command -v dnf &> /dev/null; then
+    sudo dnf install lz4 lz4-devel -y
+elif command -v pacman &> /dev/null; then
+    sudo pacman -S lz4 --noconfirm
+fi
+
+# 安装 repo 工具
+mkdir -p ~/bin
+curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
+chmod a+x ~/bin/repo
+echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
 ```
 
 </NewCodeBlock>
@@ -120,3 +139,50 @@ PARALLEL_MAKE = "-j 8"
 ```
 
 </NewCodeBlock>
+
+### Weston 构建错误（缺少 PAM 特性）
+
+在构建 Weston 时可能会遇到以下错误：
+```
+ERROR: weston-10.0.4-r0 do_configure: Function failed: do_configure
+ERROR: Logfile of failure stored in: .../weston-10.0.4-r0/temp/log.do_configure.xxxx
+ERROR: Task (.../recipes-graphics/wayland/weston_10.0.4.bb:do_configure) failed with exit code '1'
+```
+
+这通常是因为缺少 PAM（Pluggable Authentication Modules）支持。解决方法：
+
+1. **安装 PAM 开发包**：
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+```bash
+# Ubuntu/Debian
+sudo apt-get install libpam0g-dev -y
+
+# Fedora/RHEL
+sudo dnf install pam-devel -y
+
+# Arch Linux
+sudo pacman -S pam --noconfirm
+```
+
+</NewCodeBlock>
+
+2. **在 local.conf 中添加配置**：
+在 `local.conf` 文件中添加以下配置以启用 PAM 支持：
+<NewCodeBlock tip="Ubuntu" type="host">
+```bash
+# 启用 PAM 支持
+DISTRO_FEATURES:append = " pam"
+```
+
+</NewCodeBlock>
+
+3. **清理并重新构建**：
+<NewCodeBlock tip={`radxa@${props?.board ?? 'device'}$`} type="device">
+```bash
+cd ~/yocto-rockchip-sdk
+source ./oe-init-build-env
+bitbake -c cleansstate weston
+bitbake core-image-minimal
+```
+
+</NewCodeBlock>