Document Linux build toolchain versions

README.md

@@ -58,6 +58,92 @@ chengnan/
 
 > 注意：如果 OpenCV 没有适配当前 Linux 发行版的官方二进制包，不应退回源码编译安装。应改为寻找可信的预编译包、容器化二进制 SDK、发行版无污染解包方案，或更换依赖来源。
 
+## 编译工具链与版本声明
+
+本项目当前已验证的 Linux 二进制工具链如下，全部位于项目目录内的 `tools/linux-build-env/`，不依赖全局安装的 Qt / OpenCV / CMake / Ninja，也不使用 Windows 编译工具链。
+
+| 工具 / 依赖 | 当前版本 | 项目内路径 | 说明 |
+| --- | --- | --- | --- |
+| micromamba | 2.6.2 | `tools/micromamba/bin/micromamba` | 仅用于在项目目录内获取二进制包 |
+| CMake | 4.3.3 | `tools/linux-build-env/bin/cmake` | CMake 最低要求 3.21，当前验证版本 4.3.3 |
+| Ninja | 1.13.2 | `tools/linux-build-env/bin/ninja` | CMake 使用 `-G Ninja` 生成构建系统 |
+| Clang / Clang++ | 22.1.6 | `tools/linux-build-env/bin/clang++` | 本项目指定使用项目内 Clang，不使用系统 GCC / G++ |
+| Qt | 5.15.15 | `tools/linux-build-env/`、`third_party/qt-linux` | 使用 Qt Widgets / Qt Concurrent；CMake 也兼容 Qt6 |
+| OpenCV | 4.13.0 | `tools/linux-build-env/`、`third_party/opencv-linux` | 使用 `core`、`imgproc`、`imgcodecs` 组件 |
+| C++ 标准 | C++17 | `CMakeLists.txt` | `CMAKE_CXX_STANDARD 17` |
+
+> 说明：`third_party/qt-linux` 和 `third_party/opencv-linux` 是指向 `tools/linux-build-env` 的项目内软链接，方便保持 README 中的依赖目录语义；真正的二进制依赖仍统一存放在 `tools/linux-build-env/`。
+
+## 如何构建
+
+### 一键构建
+
+在 Linux 中进入项目目录执行：
+
+```bash
+cd /root/chengnan
+./scripts/build-linux-binary.sh
+```
+
+脚本会自动完成：
+
+1. 检查项目内 Linux 二进制构建环境是否存在
+2. 如不存在，则下载项目内 `micromamba` 二进制工具
+3. 在 `tools/linux-build-env/` 内安装 CMake、Ninja、Clang、Qt、OpenCV 等二进制依赖
+4. 使用项目内 Clang / CMake / Ninja 配置并构建项目
+5. 输出 Linux 可执行文件：
+
+```text
+build-linux/chengnan
+```
+
+### 分步构建
+
+如果希望先准备依赖，再单独构建：
+
+```bash
+cd /root/chengnan
+./scripts/setup-linux-binary-deps.sh
+./scripts/build-linux-binary.sh
+```
+
+### 手动等价构建命令
+
+以下命令等价于脚本中的核心构建逻辑，适合调试 CMake 参数：
+
+```bash
+cd /root/chengnan
+
+export PATH="$PWD/tools/linux-build-env/bin:$PATH"
+export CMAKE_PREFIX_PATH="$PWD/tools/linux-build-env"
+export PKG_CONFIG_PATH="$PWD/tools/linux-build-env/lib/pkgconfig:$PWD/tools/linux-build-env/share/pkgconfig:${PKG_CONFIG_PATH:-}"
+export LD_LIBRARY_PATH="$PWD/tools/linux-build-env/lib:${LD_LIBRARY_PATH:-}"
+export CC="$PWD/tools/linux-build-env/bin/clang"
+export CXX="$PWD/tools/linux-build-env/bin/clang++"
+
+cmake -S . -B build-linux \
+  -G Ninja \
+  -DCMAKE_BUILD_TYPE=Release \
+  -DCMAKE_PREFIX_PATH="$CMAKE_PREFIX_PATH" \
+  -DCMAKE_C_COMPILER="$CC" \
+  -DCMAKE_CXX_COMPILER="$CXX" \
+  -DCMAKE_INSTALL_PREFIX="$PWD/dist-linux"
+
+cmake --build build-linux --parallel "$(nproc)"
+```
+
+### 运行程序
+
+构建完成后运行：
+
+```bash
+cd /root/chengnan
+export LD_LIBRARY_PATH="$PWD/tools/linux-build-env/lib:${LD_LIBRARY_PATH:-}"
+./build-linux/chengnan
+```
+
+如果在无桌面环境或 SSH 终端中运行，Qt 图形界面可能无法显示，需要在有 X11 / Wayland 图形会话的 Linux 桌面环境中运行。
+
 ## 已清理的历史依赖
 
 之前为了尝试构建曾产生过源码编译或非目标平台相关内容，目前已删除：