【Android笔记】记一次 CMake 构建 Filament Android 库的完整排错过程（安卓交叉编译、CMake、Ninja）

news2025/6/1 6:23:35

写在前面的话，为了保持Sceneform-EQR始终是采用最新的filament，每隔一段时间我都会编译filament，并根据新增内容完善Sceneform-EQR。

现由于更换电脑，环境需重新配置。简单记录下编译出错和解决方式。

Sceneform-EQR 是EQ对谷歌“sceneform-android-sdk”的扩展，适用于图形和视频，以及增强现实（AR）和虚拟现实（VR）相关领域。它目前集成了 ARCore、AREngine 和 ORB-SLAM，提供多种场景选项，包括 AR 场景、VR 场景和自定义背景场景，以满足不同的原生三维开发需求。

filament官方PBR效果演示图

文章目录

从坑中走出：一次 CMake 构建 Filament Android 库的完整排错过程
- 一、项目背景与目标
- 二、构建命令初稿
- 三、连续踩坑全过程
- - 1. 混用生成器导致缓存冲突
  - 2. source directory 错误
  - 3. 找不到 Ninja 和编译器
  - 4. toolchain 文件语法错误
  - 5. CMAKE\_TOOLCHAIN\_FILE 未生效
  - 6. 成功配置但路径错乱
- 四、构建成功后的目录结构
- 五、总结与建议
- 六、参考文档

从坑中走出：一次 CMake 构建 Filament Android 库的完整排错过程

本文将详细记录我在构建 Google Filament Android 库的过程中，遇到的各种 CMake 报错与环境配置问题，以及逐一解决的思路与方法，希望对使用 CMake 构建跨平台 C++ 工程的你有所帮助。

一、项目背景与目标

Filament 是 Google 开源的跨平台实时渲染引擎，广泛用于安卓、高性能图形渲染、AR/VR 等领域。

我的目标是：

编译出适用于 Android 平台的 aarch64 架构的 Filament 动态链接库（如 libfilament.so）；
使用官方提供的 CMake toolchain 文件进行交叉编译；
最终产出可用于 Android 应用集成的 .so 动态库及头文件。

二、构建命令初稿

初始的构建命令如下（位于 filament-1.53.4/out/cmake-android-release-aarch64 目录）：

cmake ^
  -G Ninja ^
  -DCMAKE_BUILD_TYPE=Release ^
  -DCMAKE_INSTALL_PREFIX=..\android-release\filament ^
  -DCMAKE_TOOLCHAIN_FILE=..\..\build\toolchain-aarch64-linux-android.cmake ^
  ..\..

期望：

通过这个命令使用 Ninja 生成 Android 用的 Makefile 构建配置，并交叉编译出适用于 ARM64 的 Android 库。

三、连续踩坑全过程

1. 混用生成器导致缓存冲突

错误信息：

CMake Error: Error: generator : NMake Makefiles
Does not match the generator used previously: Visual Studio 17 2022

原因分析：此前使用过 Visual Studio 构建，并在相同的输出目录下（如 out/cmake-release）使用了不同的构建生成器。

解决方法：

删除缓存：

rd /s /q CMakeCache.txt CMakeFiles

mkdir out/cmake-android-release-aarch64
cd out/cmake-android-release-aarch64

2. source directory 错误

错误信息：

CMake Error: The source directory "/" does not appear to contain CMakeLists.txt.

原因分析：
命令行中没有指定有效的源码目录，或者路径拼接出现问题导致 ..\.. 被误解释为 /。

解决方法：
确保当前目录是 filament/out/cmake-android-release-aarch64，并用相对路径指向 filament 根目录：

cmake ..\..  # 即指向 filament 根目录

3. 找不到 Ninja 和编译器

错误信息：

CMake was unable to find a build program corresponding to "Ninja"
CMAKE_C_COMPILER not set, after EnableLanguage

原因分析：

本机未正确安装 Ninja；
或者 PATH 中未包含 Ninja 可执行路径；
Toolchain 设置未正确配置 NDK 和交叉编译工具。

解决方法：

下载 Ninja 并加入环境变量（推荐使用官方预编译）；
确保你的 NDK 路径设置正确，并传递给 toolchain 文件；
也可以使用 ANDROID_NDK、ANDROID_TOOLCHAIN 显式指定编译工具。

4. toolchain 文件语法错误

错误信息：

file FILE([TO_CMAKE_PATH|TO_NATIVE_PATH] path result) must be called with exactly three arguments
list GET given empty list
get_filename_component called with incorrect number of arguments

原因分析：
说明你传入的 NDK 路径、TOOLCHAIN 或系统路径变量未被正确设置，导致 CMake 脚本中的变量为空。

解决方法：
检查 toolchain-aarch64-linux-android.cmake 中前几行，是否读取了环境变量如：

file(TO_CMAKE_PATH "$ENV{ANDROID_NDK}" ANDROID_NDK)

此处 $ENV{ANDROID_NDK} 为空，后续 list/get_filename_component 就会失败。

建议：

设置环境变量：

set ANDROID_NDK=C:\Android\sdk\ndk\25.1.8937393

或者手动替换 toolchain 中的相关行，直接写死路径调试。

5. CMAKE_TOOLCHAIN_FILE 未生效

现象描述：

Manually-specified variables were not used by the project:
  CMAKE_TOOLCHAIN_FILE

原因分析：
你可能在已有的 CMake 缓存目录中重新执行构建命令，但 CMake 不会重新读取 CMAKE_TOOLCHAIN_FILE，因为该值只在第一次 configure 时生效。

解决方法：
删除缓存后重新 configure：

rd /s /q CMakeCache.txt CMakeFiles

6. 成功配置但路径错乱

构建路径：

D:\filament-1.53.4\out\cmake-release\out\cmake-android-release-aarch64

原因分析：
你在 out/cmake-release 中再次 cd out/cmake-android-release-aarch64，导致路径变成 out/cmake-release/out/cmake-android-release-aarch64，路径层级错误。

建议：
统一使用清晰路径：

D:\filament-1.53.4\out\cmake-android-release-aarch64

四、构建成功后的目录结构

配置成功后，会看到类似如下结构：

out/
├── cmake-android-release-aarch64/
│   ├── CMakeFiles/
│   ├── build.ninja
│   ├── lib/
│   │   ├── libfilament.so
│   │   └── ...
│   └── ...
└── android-release/
    └── filament/
        ├── include/
        └── lib/

执行构建命令：

ninja
ninja install

五、总结与建议

问题类型	关键点	建议
生成器冲突	混用了 NMake / Ninja / Visual Studio	每次构建新平台前清理缓存
Ninja 未安装	构建器不可用	下载并配置环境变量
NDK 未配置	toolchain 报错	设置 `ANDROID_NDK` 环境变量或写死路径
toolchain 变量为空	list/get_filename 错误	打印调试变量确认路径是否为空
CMAKE_TOOLCHAIN_FILE 未生效	被缓存忽略	删除 `CMakeCache.txt` 重新生成
路径错乱	输出路径嵌套混乱	使用绝对路径或统一的输出目录结构