戰(zhàn)：CMake配置與鏈接踩坑全記錄)
最早接到這個(gè)任務(wù)時(shí)我原本以為只是把桌面版的 VTK 用 CMake 交叉編譯到 Android 平臺(tái)照著官方文檔跑一遍就行。真正動(dòng)手之后才發(fā)現(xiàn)Ubuntu 24.04 配合 VTK 9.3.1 這套組合坑點(diǎn)比我想象的多得多光是解決鏈接期報(bào)錯(cuò)就花了我兩個(gè)晚上。這篇文章就是一次完整復(fù)盤從環(huán)境準(zhǔn)備、CMake 配置到鏈接階段連環(huán)炸、最終產(chǎn)物驗(yàn)證把我實(shí)測(cè)踩過的每一個(gè)坑、當(dāng)時(shí)的判斷依據(jù)、以及最終怎么繞過去的全部記錄下來。先說清楚我做的到底是什么。VTKVisualization Toolkit是一個(gè)開源的三維可視化庫桌面端常用在醫(yī)學(xué)影像、科學(xué)計(jì)算可視化、點(diǎn)云渲染這些場(chǎng)景。我這里的目標(biāo)是編譯出能在 Android 上運(yùn)行的 VTK 9.3.1 動(dòng)態(tài)庫后續(xù)要接進(jìn) Android Studio 的 JNI 工程里。編譯環(huán)境是 Ubuntu 24.04 LTSNDK 版本 r25cCMake 3.29JDK 17。如果你也準(zhǔn)備干同樣的事可以參考我這套流程但我不保證完全適用你的環(huán)境組合畢竟 NDK 和 CMake 的版本搭配足夠讓人折騰一陣子。1. 為什么非要在 Linux 上給安卓交叉編譯 VTK先回答一個(gè)很多人會(huì)問的問題VTK 官方不是有現(xiàn)成的 Android 構(gòu)建腳本嗎為什么不直接用VTK 倉庫里確實(shí)有CMakeLists.txt和官方的 Android 工具鏈支持但官方提供的只是“構(gòu)建入口”不是“現(xiàn)成產(chǎn)物”。官方 CI 會(huì)出一些預(yù)編譯包但版本更新滯后且不一定包含你需要的模塊組合。比如我需要的是帶Rendering、Filters、IO這幾個(gè)核心模塊同時(shí)要能用 OpenGLES 渲染的版本預(yù)編譯包要么缺模塊要么渲染后端對(duì)不上最后還是得自己編。另外一個(gè)現(xiàn)實(shí)問題是VTK 9.3.1 對(duì) CMake 的最低版本要求是 3.16但真正編譯 Android 版本時(shí)NDK 的android.toolchain.cmake和 VTK 的VTK_ANDROID_SUPPORT這套邏輯對(duì) CMake 版本很敏感。如果你直接用 Ubuntu 24.04 自帶的 CMake3.28去跑大概率會(huì)碰到“Policy CMP0148”或 NDK toolchain 相關(guān)的兼容性警告。我后面會(huì)細(xì)說怎么處理。再說個(gè)更實(shí)際的原因Windows 上裝 NDK 交叉編譯也不是不行但 VTK 的 Java/Android 包裝層、vtkJavaUtil、JNI 相關(guān)的符號(hào)生成在 Linux 環(huán)境下更順暢。而且后續(xù)如果你要跑測(cè)試用例、用ctest驗(yàn)證編譯結(jié)果Linux 下的腳本兼容性明顯更好。所以我個(gè)人建議是不要試圖在 Windows 上繞直接用 Linux 做交叉編譯省下的時(shí)間足夠你多踩兩個(gè)別的坑。還有一個(gè)隱藏動(dòng)機(jī)是——Android 端的 VTK 往往不只是渲染還需要做模型處理、坐標(biāo)變換、數(shù)據(jù) IO。這時(shí)候光用vtkAndroidRenderWindow不夠需要把整套 VTK 編進(jìn)去這就繞不開完整編譯。所以這個(gè)項(xiàng)目本質(zhì)上是“在 Linux 上制作一個(gè)給安卓用的 VTK SDK”你說它是交叉編譯其實(shí)更接近“定制化 SDK 構(gòu)建”。小結(jié)自己做編譯不是為了顯得專業(yè)而是為了拿到一個(gè)干凈、可裁剪、帶特定渲染后端和模塊集的產(chǎn)物。這決定了后面所有 CMake 參數(shù)怎么選。2. 環(huán)境準(zhǔn)備Ubuntu 24.04 上最容易翻車的三個(gè)環(huán)節(jié)2.1 CMake 版本Ubuntu 自帶的不一定夠用Ubuntu 24.04 的官方源里CMake 版本是 3.28.x。VTK 9.3.1 官方 CMakeLists 寫著最低 3.16理論上 3.28 夠用。但實(shí)際跑起來你會(huì)發(fā)現(xiàn)NDK r25c 里的android.toolchain.cmake在處理ANDROID_ABI和ANDROID_PLATFORM時(shí)有一些只在 CMake 3.21 才完善的行為比如對(duì)ANDROID_PLATFORM的字符串規(guī)范化。如果版本偏低可能會(huì)出現(xiàn)Invalid ANDROID_PLATFORM這類讓人摸不著頭腦的報(bào)錯(cuò)。我一開始用自帶 CMake報(bào)了一個(gè)非常詭異的錯(cuò)CMake Error: CMAKE_C_COMPILER not set, after EnableLanguage這個(gè)錯(cuò)表面看是編譯器沒找到但其實(shí)是 toolchain 文件解析出了問題。升級(jí)到 CMake 3.29從 Kitware 官方 apt 源裝之后同樣的配置一次通過。安裝方式不復(fù)雜無非是添加 Kitware 源或者直接下載官方 tar.gz。我用了 Kitware 官方倉庫sudo apt update sudo apt install -y software-properties-common lsb-release wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2/dev/null | \ gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg /dev/null echo deb [signed-by/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ noble main | sudo tee /etc/apt/sources.list.d/kitware.list sudo apt update sudo apt install cmake -y提示noble是 Ubuntu 24.04 的代號(hào)別復(fù)制成jammy否則會(huì)裝到舊版本。2.2 NDK 版本與 toolchain 文件路徑VTK 的 Android 編譯官方推薦 NDK r25 或 r26。我實(shí)測(cè) r25c 匹配良好r26b 也能編但部分老模塊的-Werror會(huì)報(bào)警告升級(jí)成錯(cuò)誤需要額外處理。建議直接用 r25c省心。下載之后解壓到一個(gè)沒有空格的路徑這點(diǎn)非常重要。比如我放到~/android-ndk-r25c而不是~/Program Files/Android/...?？崭駟栴}會(huì)在 CMake 生成階段引發(fā)各種No such file or directory但報(bào)錯(cuò)信息完全看不出來是路徑問題。NDK 裝好之后toolchain 文件位置是export ANDROID_NDK~/android-ndk-r25c $ANDROID_NDK/build/cmake/android.toolchain.cmake后面 CMake 配置時(shí)用-DCMAKE_TOOLCHAIN_FILE指向這個(gè)文件即可。但是VTK 有自己的一套 Android 支持邏輯不只靠 NDK 的 toolchain還需要開啟VTK_ANDROID_SUPPORT或使用它的CMake/vtkAndroid.cmake。這塊我在第三節(jié)詳細(xì)展開。2.3 JDK 版本與 Java 依賴如果你只是編 C 庫JDK 看似無關(guān)。但 VTK 的 Android 構(gòu)建里包含Wrapping/Java這一層它需要 JDK 和 Ant/Gradle 才能生成 Java 包裝類。我最初是純 C 需求沒裝 JDK結(jié)果 CMake 配置階段就中斷了Could NOT find Java。Ubuntu 24.04 默認(rèn)倉庫里有 OpenJDK 17安裝后記得設(shè)置JAVA_HOMEsudo apt install openjdk-17-jdk -y export JAVA_HOME/usr/lib/jvm/java-17-openjdk-amd64安裝完后CMake 能自動(dòng)檢測(cè)到 Java但如果你不需要 Java 包裝層其實(shí)可以在配置時(shí)直接關(guān)閉。我是因?yàn)楹罄m(xù)要自己寫 JNI 調(diào)用不需要 VTK 自動(dòng)生成的 Java 層所以選擇了關(guān)閉-DVTK_WRAP_JAVAOFF。這一步能省掉非常多麻煩尤其是少碰 ant 和 javac 版本不匹配的破事。注意就算你不開 Java 包裝VTK 的 Android 構(gòu)建仍然會(huì)檢查 Java所以 JDK 還是要裝。這是 VTK 源碼里CMake/vtkAndroid.cmake對(duì) Java 的隱式依賴?yán)@不過去。3. CMake 配置階段這些參數(shù)不調(diào)對(duì)后面全白干3.1 必須先了解 VTK 的模塊體系VTK 9.x 以 module 為組織單位默認(rèn)會(huì)編譯一大堆模塊包含vtkRenderingOpenGL2、vtkInteractionStyle、vtkIOMINC、vtkFiltersParallel等等。Android 平臺(tái)用不到桌面版的 OpenGL很多并行計(jì)算模塊也沒有意義。如果全編光編譯時(shí)間就夠睡兩覺還會(huì)因?yàn)槟K依賴關(guān)系在鏈接期瘋狂報(bào) undefined reference。所以我推薦的思路是基于模塊分組做裁剪。VTK 提供了VTK_GROUP_ENABLE_*這類開關(guān)可以批量控制組內(nèi)的模塊是否啟用。常用的組有組名默認(rèn)狀態(tài)Android 編譯建議VTK_GROUP_ENABLE_RenderingON需要但只開 OpenGL2 部分VTK_GROUP_ENABLE_ImagingON按需不開也行VTK_GROUP_ENABLE_ViewsON建議 OFFVTK_GROUP_ENABLE_WebON建議 OFFVTK_GROUP_ENABLE_QtON必須 OFFVTK_GROUP_ENABLE_MPION必須 OFFVTK_GROUP_ENABLE_StandAloneON建議 OFF我最終只保留了這些模塊組-DVTK_GROUP_ENABLE_RenderingON -DVTK_GROUP_ENABLE_ImagingOFF -DVTK_GROUP_ENABLE_ViewsOFF -DVTK_GROUP_ENABLE_WebOFF -DVTK_GROUP_ENABLE_QtOFF -DVTK_GROUP_ENABLE_MPIOFF -DVTK_GROUP_ENABLE_StandAloneOFF3.2 關(guān)鍵開關(guān)集合一套實(shí)測(cè)可用的 CMake 命令這里直接上我最終驗(yàn)證通過的完整配置。源碼目錄我放在~/vtk-src版本標(biāo)簽是v9.3.1build 目錄是~/vtk-android-build。cmake -G Unix Makefiles \ -DCMAKE_TOOLCHAIN_FILE$ANDROID_NDK/build/cmake/android.toolchain.cmake \ -DANDROID_ABIarm64-v8a \ -DANDROID_PLATFORMandroid-26 \ -DANDROID_USE_LEGACY_TOOLCHAIN_FILEOFF \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX$HOME/vtk-android-install \ -DBUILD_SHARED_LIBSON \ -DVTK_ANDROID_SUPPORTON \ -DVTK_ANDROID_BUILDON \ -DVTK_OPENGL_HAS_EGLON \ -DVTK_USE_XOFF \ -DVTK_GROUP_ENABLE_RenderingON \ -DVTK_GROUP_ENABLE_ImagingOFF \ -DVTK_GROUP_ENABLE_ViewsOFF \ -DVTK_GROUP_ENABLE_WebOFF \ -DVTK_GROUP_ENABLE_QtOFF \ -DVTK_GROUP_ENABLE_MPIOFF \ -DVTK_GROUP_ENABLE_StandAloneOFF \ -DVTK_WRAP_JAVAOFF \ -DVTK_BUILD_TESTINGOFF \ -DVTK_BUILD_EXAMPLESOFF \ -DVTK_ENABLE_LOGGINGOFF \ -DVTK_REQUIRE_ANDROID_OPENGLES3ON \ ~/vtk-src很多參數(shù)一眼看不懂我解釋下幾個(gè)關(guān)鍵的含義VTK_ANDROID_SUPPORTON和VTK_ANDROID_BUILDON這是讓 VTK 走vtkAndroidRenderWindow、vtkAndroidRenderWindowInteractor這套 Android 特有的窗口和后端邏輯的開關(guān)。不開的話它會(huì)去找 X11 或者 Cocoa立刻掛掉。VTK_OPENGL_HAS_EGLONAndroid 上 OpenGL ES 需要 EGL 來管理上下文這個(gè)是核心。VTK_USE_XOFF關(guān)掉 X11 依賴不然鏈接時(shí)找不到libX11.so。VTK_REQUIRE_ANDROID_OPENGLES3ON這個(gè)我必須強(qiáng)調(diào)。VTK 默認(rèn)在 Android 上如果沒檢測(cè)到 GLES3會(huì)嘗試走 GLES2 的兼容路徑。但 GLES2 下很多 shader 寫法會(huì)出問題。我在集成測(cè)試階段發(fā)現(xiàn)GLES2 路徑渲染出來的模型經(jīng)常黑屏改成 GLES3 后端后一切正常。所以從編譯階段就鎖定 GLES3 最省事。BUILD_SHARED_LIBSON編成 .so。雖然后續(xù)也可以選擇靜態(tài)庫但 VTK 的模塊特別多全靜態(tài)編會(huì)導(dǎo)致一個(gè)巨大無比的 so加載慢且容易 OOM。動(dòng)態(tài)庫方案更常見。3.3 關(guān)于 Android ABI 的選擇這個(gè)項(xiàng)目里我只編譯了arm64-v8a。按說應(yīng)該連armeabi-v7a一起編但 VTK 9.3.1 在 32 位 ARM 上的 CMake 配置經(jīng)?？ㄔ趂latbuffers的生成階段問題很多。如果你只是做現(xiàn)代 Android 設(shè)備適配建議只出 arm64。實(shí)在要兼容老設(shè)備建議單獨(dú)再開一個(gè) build 目錄專門編 32 位不要混在同一個(gè) CMake 目錄里切 ABI這會(huì)引發(fā)緩存污染。這里有個(gè)容易被忽略的點(diǎn)ANDROID_PLATFORMandroid-26表示最低支持 Android 8.0。如果你的應(yīng)用 minSdk 是 21可以降到android-21但GLES3 支持在 ndk 的 API level 21 之后就已經(jīng)有綁定了降到 21 不影響 GLES3。我之所以用 26是為了保證 Android Native 的AAssetManager接口穩(wěn)定避免兼容邏輯干擾問題。3.4 為什么 Qt 組必須關(guān)掉這個(gè)問題值得單獨(dú)說。VTK 的VTK_GROUP_ENABLE_Qt默認(rèn)是開啟的它會(huì)把vtkGUISupportQt、vtkGUISupportQtQuick等模塊納入編譯這些模塊需要桌面版 Qt5 或者 Qt 6 的QtWidgets頭文件。而 Qt 并沒有針對(duì)安卓的標(biāo)準(zhǔn) apt 包就算你通過android_arm64_v8a的 Qt 安裝包配好了VTK 的 Qt 模塊在 Android 上也沒有實(shí)際意義——因?yàn)樽罱K渲染還是走 OpenGL ESQt 只負(fù)責(zé) UI 殼子。所以直接關(guān)掉是唯一合理選擇不然 CMake 檢測(cè)階段就會(huì)報(bào)Qt5 not found白白打斷配置。4. 鏈接期連環(huán)炸我的失敗日志與逐條定位4.1 第一個(gè)炸點(diǎn)OpenGL 庫找不到CMake 配置通過后開始 make前 30% 編譯都比較順利雖然慢到鏈接某個(gè)模塊時(shí)突然報(bào)undefined reference to glBindBuffer undefined reference to eglCreateContext當(dāng)時(shí)我第一反應(yīng)是難道 OpenGLES 相關(guān)的庫沒鏈接進(jìn)去后來排查發(fā)現(xiàn)是VTK_USE_XOFF和VTK_OPENGL_HAS_EGLON的組合雖然開了但 CMake 某些模塊在find_package(OpenGL)階段會(huì)把OPENGL_LIBRARIES指到一個(gè)空變量導(dǎo)致鏈接命令里沒有-lGLESv3 -lEGL。解決方法是在 CMake 命令里手動(dòng)注入-DOPENGL_gl_LIBRARY$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/26/libGLESv3.so -DOPENGL_egl_LIBRARY$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/26/libEGL.so注意路徑里的26對(duì)應(yīng)ANDROID_PLATFORM。如果你選的是android-21這個(gè)路徑就要改成21。NDK 從 r25 開始sysroot 里的庫路徑帶有 API level 子目錄很容易被忽略。提示libGLESv3.so在 NDK 里是一個(gè)很小的庫它和libGLESv2.so是同一個(gè)符號(hào)鏈接體系A(chǔ)ndroid 系統(tǒng)里只存在libGLESv2.so。但鏈接期寫libGLESv3.so是 OK 的因?yàn)?NDK 提供了這個(gè) stub。4.2 第二個(gè)炸點(diǎn)atomic 符號(hào)和 libc 版本沖突在鏈接vtkCommonCore時(shí)又出現(xiàn)了一批undefined reference to __atomic_load_16。這個(gè)坑很經(jīng)典。NDK 的arm64-v8a目標(biāo)默認(rèn)支持部分原子操作但 16 字節(jié)的 atomic 操作比如std::atomiclong double或std::atomic__int128需要顯式鏈接libatomic.a。VTK 的某些頭文件在容器或數(shù)學(xué)計(jì)算里用了 16 字節(jié) atomic而 CMake 沒有自動(dòng)幫你加上這個(gè)庫。解決辦法是手動(dòng)設(shè)置-DCMAKE_EXE_LINKER_FLAGS-latomic -DCMAKE_SHARED_LINKER_FLAGS-latomic這里要注意-latomic必須出現(xiàn)在鏈接命令里且順序不能亂。有些教程推薦直接在target_link_libraries里加但 VTK 這種大工程手動(dòng)全局鏈接標(biāo)志是最快的解法。4.3 第三個(gè)炸點(diǎn)內(nèi)存不足導(dǎo)致的編譯中斷編譯進(jìn)行到 70% 左右的時(shí)候我的機(jī)器16GB 內(nèi)存開始頻繁報(bào)c: fatal error: Killed signal terminated program cc1plus這不是代碼問題是并行編譯時(shí)內(nèi)存爆了。VTK 的vtkRenderingOpenGL2里有些模板頭文件比如vtkOpenGLPolyDataMapper單文件編譯可能占用 2-3GB 內(nèi)存。我用的-j$(nproc)把整機(jī)資源全部拉滿結(jié)果系統(tǒng) OOM直接殺掉了編譯器。處理辦法是降低并行度先make -j4。另外可以用-DVTK_ENABLE_WRAPPINGOFF減少一處內(nèi)存占用雖然我們沒開 Java wrap但 VTK 內(nèi)部還有 C wrapping 的流程。還有個(gè)經(jīng)驗(yàn)是在鏈接大 so 時(shí)單線程比多線程更穩(wěn)。我干脆把編譯并行度控制到-j4鏈接時(shí)用-j1前后耗時(shí)其實(shí)差不了太多但穩(wěn)定性提高了一個(gè)檔次。別迷信 nproc編譯個(gè)大型庫貪多嚼不爛的道理依然成立。4.4 第四個(gè)炸點(diǎn)flatbuffers 生成器的宿主平臺(tái)問題VTK 里有個(gè)vtkIOMINC或者vtkFiltersParallelDIY模塊依賴diylog和flatbuffers。在交叉編譯中flatbuffers 需要先在宿主機(jī)也就是你的 Ubuntu上編譯一個(gè)flatc工具再拿去生成頭文件。問題在于如果 CMake 沒有明確宿主平臺(tái)和 target 平臺(tái)的區(qū)別它可能嘗試用 clang 交叉編譯的flatc去跑然后一運(yùn)行就Exec format error。排查時(shí)看到這個(gè)錯(cuò)誤我第一反應(yīng)是 CMake 緩存有問題。后來發(fā)現(xiàn)是VTK_GROUP_ENABLE_StandAloneOFF之后部分模塊的依賴被錯(cuò)誤關(guān)閉導(dǎo)致 flatbuffers 的BUILD_EXECUTABLE選項(xiàng)被跳過了。解決辦法是單獨(dú)強(qiáng)制打開 flatbuffers 的 host 工具編譯-DVTK_BUILD_FLATBUFFERS_EXECUTABLEON或者在配置階段就加一個(gè)-DFLATBUFFERS_BUILD_EXECUTABLEON這樣 CMake 會(huì)先編譯一個(gè)宿主版本的flatc再進(jìn)入生成階段。這個(gè)問題不動(dòng)手遇到真是猜不到。4.5 第五個(gè)炸點(diǎn)絕對(duì)路徑與 ccache 引發(fā)的迷之錯(cuò)誤有一陣子鏈接時(shí)反復(fù)報(bào)No such file or directory: /home/myuser/vtk-android-build/../../../usr/include/python3.12/Python.h看到這個(gè)路徑的第一反應(yīng)是頭文件搜索路徑寫錯(cuò)了../../../多跳了幾級(jí)。排查之后發(fā)現(xiàn)這其實(shí)和編譯參數(shù)無關(guān)是 CMake 在安裝階段用了緩存的CMAKE_PREFIX_PATH而那個(gè)路徑里混入了宿主機(jī)的/usr/include/python3.12。VTK 的 Python 包裝雖然沒開但 CMake 的find_package(Python3)還是會(huì)被某些模塊隱式調(diào)用一旦找到宿主機(jī) Python就會(huì)把頭文件目錄寫進(jìn)INCLUDE_DIRECTORIES最終在 Android 鏈接命令里出現(xiàn)一個(gè)包含/usr/include的路徑。解決方法是顯式禁用-DVTK_USE_PYTHONOFF -DVTK_WRAP_PYTHONOFF同時(shí)清掉 build 目錄重新配置。這里強(qiáng)調(diào)一下修改 CMake 選項(xiàng)后一定要?jiǎng)h掉 CMakeCache.txt 或直接刪 build 目錄因?yàn)楹芏鄁ind_package結(jié)果會(huì)緩存不是所有選項(xiàng)變更都會(huì)觸發(fā)重新檢測(cè)。4.6 構(gòu)建成功的標(biāo)志經(jīng)過以上五輪折騰最終看到[100%] Built target vtkRenderingOpenGL2并且在lib/目錄下出現(xiàn)了libvtkCommonCore-9.3.so libvtkCommonDataModel-9.3.so libvtkFiltersCore-9.3.so libvtkRenderingCore-9.3.so libvtkRenderingOpenGL2-9.3.so ...這也意味著 VTK 9.3.1 的 Android 版本算是編譯出來了。5. 產(chǎn)物驗(yàn)證so 庫、JNI 封裝和編譯期宏的最終檢查5.1 用 readelf 檢查依賴編譯成功不等于能在 Android 上直接跑。我第一步是用 NDK 自帶的llvm-readelf查看 so 的依賴$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-readelf -d libvtkRenderingOpenGL2-9.3.so | grep NEEDED正常情況應(yīng)該看到libGLESv2.so libEGL.so libandroid.so liblog.so libc_shared.so libm.so libdl.so libc.so如果你的列表里出現(xiàn)了libX11.so、libGL.so或者libpython3.12.so說明 CMake 配置階段混入了宿主機(jī)依賴這個(gè) so 裝到 Android 上必然UnsatisfiedLinkError。這時(shí)候要回頭檢查VTK_USE_X、VTK_USE_PYTHON這些開關(guān)。5.2 檢查 GLES3 符號(hào)我還用了一個(gè)更直接的方式驗(yàn)證 GLES3 綁定$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-nm -D libvtkRenderingOpenGL2-9.3.so | grep glCreateShader如果能看到glCreateShader這樣的符號(hào)說明渲染模塊確實(shí)鏈接到了 GLES 的 stub 庫運(yùn)行時(shí)由 Android 系統(tǒng)解析到實(shí)際驅(qū)動(dòng)。5.3 AAR / JNI 集成前的最后準(zhǔn)備VTK 編譯出來的是一堆獨(dú)立的 so不是現(xiàn)成的 AAR。要在 Android Studio 里用有兩種路徑把 so 文件放到app/src/main/jniLibs/arm64-v8a/下然后自己寫 JNI 頭文件和 .cpp。這是最靈活的方式。用 CMake 在安卓工程里直接鏈接這些 so需要在build.gradle里指定externalNativeBuild。以第一種為例你的AndroidManifest.xml里需要聲明uses-feature android:glEsVersion0x00030000 android:requiredtrue /因?yàn)?VTK 的 OpenGLES3 后端在運(yùn)行期需要 GLES3 上下文如果系統(tǒng)不支持運(yùn)行時(shí)直接崩潰。這個(gè)不是編譯期問題但很關(guān)鍵。然后在 JNI 代碼里記得加一個(gè)初始化調(diào)用#include vtkAndroidRenderWindow.h #include vtkRenderWindow.h vtkSmartPointervtkRenderWindow window vtkSmartPointervtkAndroidRenderWindow::New();Android 上不能直接創(chuàng)建普通vtkRenderWindow必須用vtkAndroidRenderWindow或vtkAndroidRenderWindowInteractor子類它內(nèi)部處理了ANativeWindow與 OpenGLES 上下文的綁定。這也是為什么編譯時(shí)必須開VTK_ANDROID_SUPPORT。5.4 一個(gè)容易忽略的宏定義問題如果你是從桌面項(xiàng)目遷移過來的測(cè)試代碼可能在初始化之前會(huì)調(diào)用vtkRenderWindow::SetGlobalMaximumNumberOfMultiSamples(0);或者設(shè)置一些桌面 OpenGL 的擴(kuò)展選項(xiàng)。Android 的 GLES3 與傳統(tǒng)桌面 OpenGL 的 API 集合差異很大很多 VTK 底層 check 在VTK_OPENGL_HAS_EGLON時(shí)并不會(huì)預(yù)編譯桌面路徑所以這些選項(xiàng)不會(huì)生效甚至可能因?yàn)檎{(diào)用了不存在的方法導(dǎo)致 crash。寫 JNI 代碼時(shí)建議直接#ifdef一個(gè)自己的宏比如VTK_ANDROID_BUILD這個(gè)宏在 VTK 源碼里其實(shí)是存在的把桌面專用邏輯隔離開。驗(yàn)證簽名階段最好在真機(jī)上跑一個(gè)最小 demo創(chuàng)建vtkAndroidRenderWindow、設(shè)置RenderWindowInteractor、加載一個(gè)簡單的 sphere polydata 并渲染。如果渲染黑屏但沒崩潰基本可以鎖定是 GLES2/GLES3 上下文問題而不是庫的問題。6. 關(guān)于 Ubuntu 24.04 這套環(huán)境我還踩過的幾個(gè)周邊坑前面五個(gè)炸點(diǎn)都是 VTK 交叉編譯的核心問題。但 Ubuntu 24.04 本身還有一些周邊坑雖然不影響最終 so但會(huì)嚴(yán)重打斷你的節(jié)奏。6.1 apt 源與依賴安裝慢的問題Ubuntu 24.04 默認(rèn)的 apt 源在國內(nèi)訪問很慢編譯前要裝 zip、unzip、ninja-build、openjdk 等基礎(chǔ)工具如果一直卡在下載階段后續(xù)什么都干不了。解決方案有幾種最基本的先把 apt 源換成可用的鏡像然后執(zhí)行sudo apt update sudo apt install -y cmake ninja-build zip unzip openjdk-17-jdk這里裝ninja是可選的VTK 用 Unix Makefiles 也能編但 Ninja 的輸出更清晰出錯(cuò)時(shí)定位更快。實(shí)測(cè)下來兩者編譯時(shí)間沒有明顯差異。6.2 ccache 配置不當(dāng)導(dǎo)致的問題如果你本機(jī)裝了 ccache 并設(shè)置了CCACHE_PREFIX或CCACHE_DIR全局環(huán)境變量交叉編譯時(shí)會(huì)導(dǎo)致一個(gè)很奇怪的現(xiàn)象編譯產(chǎn)物一樣但每次 configure 都會(huì)重新觸發(fā)全量編譯因?yàn)?ccache 對(duì)交叉編譯器的hash_dir處理比較敏感。解決方法是給該項(xiàng)目的編譯單獨(dú)設(shè)置export CCACHE_DIR$HOME/.ccache-vtk-android不要用默認(rèn)的~/.ccache。這樣不僅避免串臺(tái)還能保留桌面編譯的緩存。6.3 磁盤空間和 inode 用量VTK 9.3.1 源碼加 build 目錄體積很容易超過 15GB且全是小文件在 ext4 上會(huì)消耗大量 inode。如果你用的是一塊分區(qū)空間很小的虛擬機(jī)磁盤編譯到一半報(bào)No space left on device且 df -h 顯示還有空間那就是 inode 用光了。檢查命令df -i $HOME/vtk-android-build如果Use%接近 100%趕緊清理其它項(xiàng)目緩存或者挪到一個(gè)更大的分區(qū)。別問我為什么強(qiáng)調(diào)這一點(diǎn)我第一次是在 WSL 的虛擬磁盤上編譯的20GB 空間剩了 3GB結(jié)果 inode 用盡只能從頭再來。6.4 關(guān)于 WSL 的額外提醒我看到熱搜詞里有 Ubuntu 24.04 和 WSL 相關(guān)的條目順帶提一句。WSL2 環(huán)境下編譯 VTK Android 版理論上可行但需要注意WSL2 的跨文件系統(tǒng)性能非常差源碼和 build 目錄必須放在 WSL 的 ext4 文件系統(tǒng)內(nèi)即~/下不要放在/mnt/c/。否則 CMake 生成階段會(huì)因?yàn)槲募?IO 極慢而顯得像死機(jī)一樣。如果你看到 configure 卡在Optimize for native binaries很久不動(dòng)先檢查路徑位置再檢查 resctrl 之類的 CPU 限制問題。7. 我最終沉淀下來的幾件事這個(gè)項(xiàng)目做完之后有幾個(gè)判斷我認(rèn)為是長期有效的干脆一起寫出來。第一VTK 的 Android 編譯不存在“一個(gè)命令行搞定”的靈丹妙藥。網(wǎng)上流傳的官方文檔命令我試過好幾次要么模塊裁剪不夠、要么鏈接期失敗。主要是因?yàn)?VTK 版本、NDK 版本、CMake 版本三者的排列組合實(shí)在太多。解決問題的核心不是背命令行而是理解 module 依賴關(guān)系和 CMake 交叉編譯的原理這樣碰到任何版本的 VTK 都能從容應(yīng)對(duì)。第二編譯前先確定渲染后端。如果你的應(yīng)用目標(biāo)機(jī)型基本都是 2018 年之后的直接鎖 GLES3如果需要兼容老設(shè)備最好在工程里準(zhǔn)備兩套 so或者在運(yùn)行期動(dòng)態(tài)探測(cè) GPU 能力。但 VTK 的源碼本身在 GLES2/GLES3 之間切換并不平滑跑起來再切換容易出狀態(tài)殘留。這件事必須在編譯前決定。第三盡量把 build 腳本沉淀下來。我后來寫了一個(gè)build_android.sh每次配置、構(gòu)建、安裝、驗(yàn)證全部封裝成腳本哪怕三個(gè)月后再編譯一次也不會(huì)慌亂。過程腳本比文檔靠譜。最后再分享一個(gè)小技巧編譯完成后別急著刪 build 目錄。VTK 的install目錄和 build 目錄里的CMakeCache.txt是后續(xù)排查問題的重要線索。如果集成階段發(fā)現(xiàn)某個(gè)符號(hào)缺失回來看 build 目錄里的CMakeFiles/CMakeError.log和CMakeOutput.log比重新跑一遍編譯要快得多。這個(gè)習(xí)慣在我用 VTK 做渲染項(xiàng)目時(shí)救過我很多次。 Ubuntu 24.04下VTK 9.3.1交叉編譯Android實(shí)戰(zhàn)：CMake配置與鏈接踩坑全記錄
最早接到這個(gè)任務(wù)時(shí)我原本以為只是把桌面版的 VTK 用 CMake 交叉編譯到 Android 平臺(tái)照著官方文檔跑一遍就行。真正動(dòng)手之后才發(fā)現(xiàn)Ubuntu 24.04 配合 VTK 9.3.1 這套組合坑點(diǎn)比我想象的多得多光是解決鏈接期報(bào)錯(cuò)就花了我兩個(gè)晚上。這篇文章就是一次完整復(fù)盤從環(huán)境準(zhǔn)備、CMake 配置到鏈接階段連環(huán)炸、最終產(chǎn)物驗(yàn)證把我實(shí)測(cè)踩過的每一個(gè)坑、當(dāng)時(shí)的判斷依據(jù)、以及最終怎么繞過去的全部記錄下來。先說清楚我做的到底是什么。VTKVisualization Toolkit是一個(gè)開源的三維可視化庫桌面端常用在醫(yī)學(xué)影像、科學(xué)計(jì)算可視化、點(diǎn)云渲染這些場(chǎng)景。我這里的目標(biāo)是編譯出能在 Android 上運(yùn)行的 VTK 9.3.1 動(dòng)態(tài)庫后續(xù)要接進(jìn) Android Studio 的 JNI 工程里。編譯環(huán)境是 Ubuntu 24.04 LTSNDK 版本 r25cCMake 3.29JDK 17。如果你也準(zhǔn)備干同樣的事可以參考我這套流程但我不保證完全適用你的環(huán)境組合畢竟 NDK 和 CMake 的版本搭配足夠讓人折騰一陣子。1. 為什么非要在 Linux 上給安卓交叉編譯 VTK先回答一個(gè)很多人會(huì)問的問題VTK 官方不是有現(xiàn)成的 Android 構(gòu)建腳本嗎為什么不直接用VTK 倉庫里確實(shí)有CMakeLists.txt和官方的 Android 工具鏈支持但官方提供的只是“構(gòu)建入口”不是“現(xiàn)成產(chǎn)物”。官方 CI 會(huì)出一些預(yù)編譯包但版本更新滯后且不一定包含你需要的模塊組合。比如我需要的是帶Rendering、Filters、IO這幾個(gè)核心模塊同時(shí)要能用 OpenGLES 渲染的版本預(yù)編譯包要么缺模塊要么渲染后端對(duì)不上最后還是得自己編。另外一個(gè)現(xiàn)實(shí)問題是VTK 9.3.1 對(duì) CMake 的最低版本要求是 3.16但真正編譯 Android 版本時(shí)NDK 的android.toolchain.cmake和 VTK 的VTK_ANDROID_SUPPORT這套邏輯對(duì) CMake 版本很敏感。如果你直接用 Ubuntu 24.04 自帶的 CMake3.28去跑大概率會(huì)碰到“Policy CMP0148”或 NDK toolchain 相關(guān)的兼容性警告。我后面會(huì)細(xì)說怎么處理。再說個(gè)更實(shí)際的原因Windows 上裝 NDK 交叉編譯也不是不行但 VTK 的 Java/Android 包裝層、vtkJavaUtil、JNI 相關(guān)的符號(hào)生成在 Linux 環(huán)境下更順暢。而且后續(xù)如果你要跑測(cè)試用例、用ctest驗(yàn)證編譯結(jié)果Linux 下的腳本兼容性明顯更好。所以我個(gè)人建議是不要試圖在 Windows 上繞直接用 Linux 做交叉編譯省下的時(shí)間足夠你多踩兩個(gè)別的坑。還有一個(gè)隱藏動(dòng)機(jī)是——Android 端的 VTK 往往不只是渲染還需要做模型處理、坐標(biāo)變換、數(shù)據(jù) IO。這時(shí)候光用vtkAndroidRenderWindow不夠需要把整套 VTK 編進(jìn)去這就繞不開完整編譯。所以這個(gè)項(xiàng)目本質(zhì)上是“在 Linux 上制作一個(gè)給安卓用的 VTK SDK”你說它是交叉編譯其實(shí)更接近“定制化 SDK 構(gòu)建”。小結(jié)自己做編譯不是為了顯得專業(yè)而是為了拿到一個(gè)干凈、可裁剪、帶特定渲染后端和模塊集的產(chǎn)物。這決定了后面所有 CMake 參數(shù)怎么選。2. 環(huán)境準(zhǔn)備Ubuntu 24.04 上最容易翻車的三個(gè)環(huán)節(jié)2.1 CMake 版本Ubuntu 自帶的不一定夠用Ubuntu 24.04 的官方源里CMake 版本是 3.28.x。VTK 9.3.1 官方 CMakeLists 寫著最低 3.16理論上 3.28 夠用。但實(shí)際跑起來你會(huì)發(fā)現(xiàn)NDK r25c 里的android.toolchain.cmake在處理ANDROID_ABI和ANDROID_PLATFORM時(shí)有一些只在 CMake 3.21 才完善的行為比如對(duì)ANDROID_PLATFORM的字符串規(guī)范化。如果版本偏低可能會(huì)出現(xiàn)Invalid ANDROID_PLATFORM這類讓人摸不著頭腦的報(bào)錯(cuò)。我一開始用自帶 CMake報(bào)了一個(gè)非常詭異的錯(cuò)CMake Error: CMAKE_C_COMPILER not set, after EnableLanguage這個(gè)錯(cuò)表面看是編譯器沒找到但其實(shí)是 toolchain 文件解析出了問題。升級(jí)到 CMake 3.29從 Kitware 官方 apt 源裝之后同樣的配置一次通過。安裝方式不復(fù)雜無非是添加 Kitware 源或者直接下載官方 tar.gz。我用了 Kitware 官方倉庫sudo apt update sudo apt install -y software-properties-common lsb-release wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2/dev/null | \ gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg /dev/null echo deb [signed-by/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ noble main | sudo tee /etc/apt/sources.list.d/kitware.list sudo apt update sudo apt install cmake -y提示noble是 Ubuntu 24.04 的代號(hào)別復(fù)制成jammy否則會(huì)裝到舊版本。2.2 NDK 版本與 toolchain 文件路徑VTK 的 Android 編譯官方推薦 NDK r25 或 r26。我實(shí)測(cè) r25c 匹配良好r26b 也能編但部分老模塊的-Werror會(huì)報(bào)警告升級(jí)成錯(cuò)誤需要額外處理。建議直接用 r25c省心。下載之后解壓到一個(gè)沒有空格的路徑這點(diǎn)非常重要。比如我放到~/android-ndk-r25c而不是~/Program Files/Android/...?？崭駟栴}會(huì)在 CMake 生成階段引發(fā)各種No such file or directory但報(bào)錯(cuò)信息完全看不出來是路徑問題。NDK 裝好之后toolchain 文件位置是export ANDROID_NDK~/android-ndk-r25c $ANDROID_NDK/build/cmake/android.toolchain.cmake后面 CMake 配置時(shí)用-DCMAKE_TOOLCHAIN_FILE指向這個(gè)文件即可。但是VTK 有自己的一套 Android 支持邏輯不只靠 NDK 的 toolchain還需要開啟VTK_ANDROID_SUPPORT或使用它的CMake/vtkAndroid.cmake。這塊我在第三節(jié)詳細(xì)展開。2.3 JDK 版本與 Java 依賴如果你只是編 C 庫JDK 看似無關(guān)。但 VTK 的 Android 構(gòu)建里包含Wrapping/Java這一層它需要 JDK 和 Ant/Gradle 才能生成 Java 包裝類。我最初是純 C 需求沒裝 JDK結(jié)果 CMake 配置階段就中斷了Could NOT find Java。Ubuntu 24.04 默認(rèn)倉庫里有 OpenJDK 17安裝后記得設(shè)置JAVA_HOMEsudo apt install openjdk-17-jdk -y export JAVA_HOME/usr/lib/jvm/java-17-openjdk-amd64安裝完后CMake 能自動(dòng)檢測(cè)到 Java但如果你不需要 Java 包裝層其實(shí)可以在配置時(shí)直接關(guān)閉。我是因?yàn)楹罄m(xù)要自己寫 JNI 調(diào)用不需要 VTK 自動(dòng)生成的 Java 層所以選擇了關(guān)閉-DVTK_WRAP_JAVAOFF。這一步能省掉非常多麻煩尤其是少碰 ant 和 javac 版本不匹配的破事。注意就算你不開 Java 包裝VTK 的 Android 構(gòu)建仍然會(huì)檢查 Java所以 JDK 還是要裝。這是 VTK 源碼里CMake/vtkAndroid.cmake對(duì) Java 的隱式依賴?yán)@不過去。3. CMake 配置階段這些參數(shù)不調(diào)對(duì)后面全白干3.1 必須先了解 VTK 的模塊體系VTK 9.x 以 module 為組織單位默認(rèn)會(huì)編譯一大堆模塊包含vtkRenderingOpenGL2、vtkInteractionStyle、vtkIOMINC、vtkFiltersParallel等等。Android 平臺(tái)用不到桌面版的 OpenGL很多并行計(jì)算模塊也沒有意義。如果全編光編譯時(shí)間就夠睡兩覺還會(huì)因?yàn)槟K依賴關(guān)系在鏈接期瘋狂報(bào) undefined reference。所以我推薦的思路是基于模塊分組做裁剪。VTK 提供了VTK_GROUP_ENABLE_*這類開關(guān)可以批量控制組內(nèi)的模塊是否啟用。常用的組有組名默認(rèn)狀態(tài)Android 編譯建議VTK_GROUP_ENABLE_RenderingON需要但只開 OpenGL2 部分VTK_GROUP_ENABLE_ImagingON按需不開也行VTK_GROUP_ENABLE_ViewsON建議 OFFVTK_GROUP_ENABLE_WebON建議 OFFVTK_GROUP_ENABLE_QtON必須 OFFVTK_GROUP_ENABLE_MPION必須 OFFVTK_GROUP_ENABLE_StandAloneON建議 OFF我最終只保留了這些模塊組-DVTK_GROUP_ENABLE_RenderingON -DVTK_GROUP_ENABLE_ImagingOFF -DVTK_GROUP_ENABLE_ViewsOFF -DVTK_GROUP_ENABLE_WebOFF -DVTK_GROUP_ENABLE_QtOFF -DVTK_GROUP_ENABLE_MPIOFF -DVTK_GROUP_ENABLE_StandAloneOFF3.2 關(guān)鍵開關(guān)集合一套實(shí)測(cè)可用的 CMake 命令這里直接上我最終驗(yàn)證通過的完整配置。源碼目錄我放在~/vtk-src版本標(biāo)簽是v9.3.1build 目錄是~/vtk-android-build。cmake -G Unix Makefiles \ -DCMAKE_TOOLCHAIN_FILE$ANDROID_NDK/build/cmake/android.toolchain.cmake \ -DANDROID_ABIarm64-v8a \ -DANDROID_PLATFORMandroid-26 \ -DANDROID_USE_LEGACY_TOOLCHAIN_FILEOFF \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX$HOME/vtk-android-install \ -DBUILD_SHARED_LIBSON \ -DVTK_ANDROID_SUPPORTON \ -DVTK_ANDROID_BUILDON \ -DVTK_OPENGL_HAS_EGLON \ -DVTK_USE_XOFF \ -DVTK_GROUP_ENABLE_RenderingON \ -DVTK_GROUP_ENABLE_ImagingOFF \ -DVTK_GROUP_ENABLE_ViewsOFF \ -DVTK_GROUP_ENABLE_WebOFF \ -DVTK_GROUP_ENABLE_QtOFF \ -DVTK_GROUP_ENABLE_MPIOFF \ -DVTK_GROUP_ENABLE_StandAloneOFF \ -DVTK_WRAP_JAVAOFF \ -DVTK_BUILD_TESTINGOFF \ -DVTK_BUILD_EXAMPLESOFF \ -DVTK_ENABLE_LOGGINGOFF \ -DVTK_REQUIRE_ANDROID_OPENGLES3ON \ ~/vtk-src很多參數(shù)一眼看不懂我解釋下幾個(gè)關(guān)鍵的含義VTK_ANDROID_SUPPORTON和VTK_ANDROID_BUILDON這是讓 VTK 走vtkAndroidRenderWindow、vtkAndroidRenderWindowInteractor這套 Android 特有的窗口和后端邏輯的開關(guān)。不開的話它會(huì)去找 X11 或者 Cocoa立刻掛掉。VTK_OPENGL_HAS_EGLONAndroid 上 OpenGL ES 需要 EGL 來管理上下文這個(gè)是核心。VTK_USE_XOFF關(guān)掉 X11 依賴不然鏈接時(shí)找不到libX11.so。VTK_REQUIRE_ANDROID_OPENGLES3ON這個(gè)我必須強(qiáng)調(diào)。VTK 默認(rèn)在 Android 上如果沒檢測(cè)到 GLES3會(huì)嘗試走 GLES2 的兼容路徑。但 GLES2 下很多 shader 寫法會(huì)出問題。我在集成測(cè)試階段發(fā)現(xiàn)GLES2 路徑渲染出來的模型經(jīng)常黑屏改成 GLES3 后端后一切正常。所以從編譯階段就鎖定 GLES3 最省事。BUILD_SHARED_LIBSON編成 .so。雖然后續(xù)也可以選擇靜態(tài)庫但 VTK 的模塊特別多全靜態(tài)編會(huì)導(dǎo)致一個(gè)巨大無比的 so加載慢且容易 OOM。動(dòng)態(tài)庫方案更常見。3.3 關(guān)于 Android ABI 的選擇這個(gè)項(xiàng)目里我只編譯了arm64-v8a。按說應(yīng)該連armeabi-v7a一起編但 VTK 9.3.1 在 32 位 ARM 上的 CMake 配置經(jīng)?？ㄔ趂latbuffers的生成階段問題很多。如果你只是做現(xiàn)代 Android 設(shè)備適配建議只出 arm64。實(shí)在要兼容老設(shè)備建議單獨(dú)再開一個(gè) build 目錄專門編 32 位不要混在同一個(gè) CMake 目錄里切 ABI這會(huì)引發(fā)緩存污染。這里有個(gè)容易被忽略的點(diǎn)ANDROID_PLATFORMandroid-26表示最低支持 Android 8.0。如果你的應(yīng)用 minSdk 是 21可以降到android-21但GLES3 支持在 ndk 的 API level 21 之后就已經(jīng)有綁定了降到 21 不影響 GLES3。我之所以用 26是為了保證 Android Native 的AAssetManager接口穩(wěn)定避免兼容邏輯干擾問題。3.4 為什么 Qt 組必須關(guān)掉這個(gè)問題值得單獨(dú)說。VTK 的VTK_GROUP_ENABLE_Qt默認(rèn)是開啟的它會(huì)把vtkGUISupportQt、vtkGUISupportQtQuick等模塊納入編譯這些模塊需要桌面版 Qt5 或者 Qt 6 的QtWidgets頭文件。而 Qt 并沒有針對(duì)安卓的標(biāo)準(zhǔn) apt 包就算你通過android_arm64_v8a的 Qt 安裝包配好了VTK 的 Qt 模塊在 Android 上也沒有實(shí)際意義——因?yàn)樽罱K渲染還是走 OpenGL ESQt 只負(fù)責(zé) UI 殼子。所以直接關(guān)掉是唯一合理選擇不然 CMake 檢測(cè)階段就會(huì)報(bào)Qt5 not found白白打斷配置。4. 鏈接期連環(huán)炸我的失敗日志與逐條定位4.1 第一個(gè)炸點(diǎn)OpenGL 庫找不到CMake 配置通過后開始 make前 30% 編譯都比較順利雖然慢到鏈接某個(gè)模塊時(shí)突然報(bào)undefined reference to glBindBuffer undefined reference to eglCreateContext當(dāng)時(shí)我第一反應(yīng)是難道 OpenGLES 相關(guān)的庫沒鏈接進(jìn)去后來排查發(fā)現(xiàn)是VTK_USE_XOFF和VTK_OPENGL_HAS_EGLON的組合雖然開了但 CMake 某些模塊在find_package(OpenGL)階段會(huì)把OPENGL_LIBRARIES指到一個(gè)空變量導(dǎo)致鏈接命令里沒有-lGLESv3 -lEGL。解決方法是在 CMake 命令里手動(dòng)注入-DOPENGL_gl_LIBRARY$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/26/libGLESv3.so -DOPENGL_egl_LIBRARY$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/sysroot/usr/lib/aarch64-linux-android/26/libEGL.so注意路徑里的26對(duì)應(yīng)ANDROID_PLATFORM。如果你選的是android-21這個(gè)路徑就要改成21。NDK 從 r25 開始sysroot 里的庫路徑帶有 API level 子目錄很容易被忽略。提示libGLESv3.so在 NDK 里是一個(gè)很小的庫它和libGLESv2.so是同一個(gè)符號(hào)鏈接體系A(chǔ)ndroid 系統(tǒng)里只存在libGLESv2.so。但鏈接期寫libGLESv3.so是 OK 的因?yàn)?NDK 提供了這個(gè) stub。4.2 第二個(gè)炸點(diǎn)atomic 符號(hào)和 libc 版本沖突在鏈接vtkCommonCore時(shí)又出現(xiàn)了一批undefined reference to __atomic_load_16。這個(gè)坑很經(jīng)典。NDK 的arm64-v8a目標(biāo)默認(rèn)支持部分原子操作但 16 字節(jié)的 atomic 操作比如std::atomiclong double或std::atomic__int128需要顯式鏈接libatomic.a。VTK 的某些頭文件在容器或數(shù)學(xué)計(jì)算里用了 16 字節(jié) atomic而 CMake 沒有自動(dòng)幫你加上這個(gè)庫。解決辦法是手動(dòng)設(shè)置-DCMAKE_EXE_LINKER_FLAGS-latomic -DCMAKE_SHARED_LINKER_FLAGS-latomic這里要注意-latomic必須出現(xiàn)在鏈接命令里且順序不能亂。有些教程推薦直接在target_link_libraries里加但 VTK 這種大工程手動(dòng)全局鏈接標(biāo)志是最快的解法。4.3 第三個(gè)炸點(diǎn)內(nèi)存不足導(dǎo)致的編譯中斷編譯進(jìn)行到 70% 左右的時(shí)候我的機(jī)器16GB 內(nèi)存開始頻繁報(bào)c: fatal error: Killed signal terminated program cc1plus這不是代碼問題是并行編譯時(shí)內(nèi)存爆了。VTK 的vtkRenderingOpenGL2里有些模板頭文件比如vtkOpenGLPolyDataMapper單文件編譯可能占用 2-3GB 內(nèi)存。我用的-j$(nproc)把整機(jī)資源全部拉滿結(jié)果系統(tǒng) OOM直接殺掉了編譯器。處理辦法是降低并行度先make -j4。另外可以用-DVTK_ENABLE_WRAPPINGOFF減少一處內(nèi)存占用雖然我們沒開 Java wrap但 VTK 內(nèi)部還有 C wrapping 的流程。還有個(gè)經(jīng)驗(yàn)是在鏈接大 so 時(shí)單線程比多線程更穩(wěn)。我干脆把編譯并行度控制到-j4鏈接時(shí)用-j1前后耗時(shí)其實(shí)差不了太多但穩(wěn)定性提高了一個(gè)檔次。別迷信 nproc編譯個(gè)大型庫貪多嚼不爛的道理依然成立。4.4 第四個(gè)炸點(diǎn)flatbuffers 生成器的宿主平臺(tái)問題VTK 里有個(gè)vtkIOMINC或者vtkFiltersParallelDIY模塊依賴diylog和flatbuffers。在交叉編譯中flatbuffers 需要先在宿主機(jī)也就是你的 Ubuntu上編譯一個(gè)flatc工具再拿去生成頭文件。問題在于如果 CMake 沒有明確宿主平臺(tái)和 target 平臺(tái)的區(qū)別它可能嘗試用 clang 交叉編譯的flatc去跑然后一運(yùn)行就Exec format error。排查時(shí)看到這個(gè)錯(cuò)誤我第一反應(yīng)是 CMake 緩存有問題。后來發(fā)現(xiàn)是VTK_GROUP_ENABLE_StandAloneOFF之后部分模塊的依賴被錯(cuò)誤關(guān)閉導(dǎo)致 flatbuffers 的BUILD_EXECUTABLE選項(xiàng)被跳過了。解決辦法是單獨(dú)強(qiáng)制打開 flatbuffers 的 host 工具編譯-DVTK_BUILD_FLATBUFFERS_EXECUTABLEON或者在配置階段就加一個(gè)-DFLATBUFFERS_BUILD_EXECUTABLEON這樣 CMake 會(huì)先編譯一個(gè)宿主版本的flatc再進(jìn)入生成階段。這個(gè)問題不動(dòng)手遇到真是猜不到。4.5 第五個(gè)炸點(diǎn)絕對(duì)路徑與 ccache 引發(fā)的迷之錯(cuò)誤有一陣子鏈接時(shí)反復(fù)報(bào)No such file or directory: /home/myuser/vtk-android-build/../../../usr/include/python3.12/Python.h看到這個(gè)路徑的第一反應(yīng)是頭文件搜索路徑寫錯(cuò)了../../../多跳了幾級(jí)。排查之后發(fā)現(xiàn)這其實(shí)和編譯參數(shù)無關(guān)是 CMake 在安裝階段用了緩存的CMAKE_PREFIX_PATH而那個(gè)路徑里混入了宿主機(jī)的/usr/include/python3.12。VTK 的 Python 包裝雖然沒開但 CMake 的find_package(Python3)還是會(huì)被某些模塊隱式調(diào)用一旦找到宿主機(jī) Python就會(huì)把頭文件目錄寫進(jìn)INCLUDE_DIRECTORIES最終在 Android 鏈接命令里出現(xiàn)一個(gè)包含/usr/include的路徑。解決方法是顯式禁用-DVTK_USE_PYTHONOFF -DVTK_WRAP_PYTHONOFF同時(shí)清掉 build 目錄重新配置。這里強(qiáng)調(diào)一下修改 CMake 選項(xiàng)后一定要?jiǎng)h掉 CMakeCache.txt 或直接刪 build 目錄因?yàn)楹芏鄁ind_package結(jié)果會(huì)緩存不是所有選項(xiàng)變更都會(huì)觸發(fā)重新檢測(cè)。4.6 構(gòu)建成功的標(biāo)志經(jīng)過以上五輪折騰最終看到[100%] Built target vtkRenderingOpenGL2并且在lib/目錄下出現(xiàn)了libvtkCommonCore-9.3.so libvtkCommonDataModel-9.3.so libvtkFiltersCore-9.3.so libvtkRenderingCore-9.3.so libvtkRenderingOpenGL2-9.3.so ...這也意味著 VTK 9.3.1 的 Android 版本算是編譯出來了。5. 產(chǎn)物驗(yàn)證so 庫、JNI 封裝和編譯期宏的最終檢查5.1 用 readelf 檢查依賴編譯成功不等于能在 Android 上直接跑。我第一步是用 NDK 自帶的llvm-readelf查看 so 的依賴$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-readelf -d libvtkRenderingOpenGL2-9.3.so | grep NEEDED正常情況應(yīng)該看到libGLESv2.so libEGL.so libandroid.so liblog.so libc_shared.so libm.so libdl.so libc.so如果你的列表里出現(xiàn)了libX11.so、libGL.so或者libpython3.12.so說明 CMake 配置階段混入了宿主機(jī)依賴這個(gè) so 裝到 Android 上必然UnsatisfiedLinkError。這時(shí)候要回頭檢查VTK_USE_X、VTK_USE_PYTHON這些開關(guān)。5.2 檢查 GLES3 符號(hào)我還用了一個(gè)更直接的方式驗(yàn)證 GLES3 綁定$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-nm -D libvtkRenderingOpenGL2-9.3.so | grep glCreateShader如果能看到glCreateShader這樣的符號(hào)說明渲染模塊確實(shí)鏈接到了 GLES 的 stub 庫運(yùn)行時(shí)由 Android 系統(tǒng)解析到實(shí)際驅(qū)動(dòng)。5.3 AAR / JNI 集成前的最后準(zhǔn)備VTK 編譯出來的是一堆獨(dú)立的 so不是現(xiàn)成的 AAR。要在 Android Studio 里用有兩種路徑把 so 文件放到app/src/main/jniLibs/arm64-v8a/下然后自己寫 JNI 頭文件和 .cpp。這是最靈活的方式。用 CMake 在安卓工程里直接鏈接這些 so需要在build.gradle里指定externalNativeBuild。以第一種為例你的AndroidManifest.xml里需要聲明uses-feature android:glEsVersion0x00030000 android:requiredtrue /因?yàn)?VTK 的 OpenGLES3 后端在運(yùn)行期需要 GLES3 上下文如果系統(tǒng)不支持運(yùn)行時(shí)直接崩潰。這個(gè)不是編譯期問題但很關(guān)鍵。然后在 JNI 代碼里記得加一個(gè)初始化調(diào)用#include vtkAndroidRenderWindow.h #include vtkRenderWindow.h vtkSmartPointervtkRenderWindow window vtkSmartPointervtkAndroidRenderWindow::New();Android 上不能直接創(chuàng)建普通vtkRenderWindow必須用vtkAndroidRenderWindow或vtkAndroidRenderWindowInteractor子類它內(nèi)部處理了ANativeWindow與 OpenGLES 上下文的綁定。這也是為什么編譯時(shí)必須開VTK_ANDROID_SUPPORT。5.4 一個(gè)容易忽略的宏定義問題如果你是從桌面項(xiàng)目遷移過來的測(cè)試代碼可能在初始化之前會(huì)調(diào)用vtkRenderWindow::SetGlobalMaximumNumberOfMultiSamples(0);或者設(shè)置一些桌面 OpenGL 的擴(kuò)展選項(xiàng)。Android 的 GLES3 與傳統(tǒng)桌面 OpenGL 的 API 集合差異很大很多 VTK 底層 check 在VTK_OPENGL_HAS_EGLON時(shí)并不會(huì)預(yù)編譯桌面路徑所以這些選項(xiàng)不會(huì)生效甚至可能因?yàn)檎{(diào)用了不存在的方法導(dǎo)致 crash。寫 JNI 代碼時(shí)建議直接#ifdef一個(gè)自己的宏比如VTK_ANDROID_BUILD這個(gè)宏在 VTK 源碼里其實(shí)是存在的把桌面專用邏輯隔離開。驗(yàn)證簽名階段最好在真機(jī)上跑一個(gè)最小 demo創(chuàng)建vtkAndroidRenderWindow、設(shè)置RenderWindowInteractor、加載一個(gè)簡單的 sphere polydata 并渲染。如果渲染黑屏但沒崩潰基本可以鎖定是 GLES2/GLES3 上下文問題而不是庫的問題。6. 關(guān)于 Ubuntu 24.04 這套環(huán)境我還踩過的幾個(gè)周邊坑前面五個(gè)炸點(diǎn)都是 VTK 交叉編譯的核心問題。但 Ubuntu 24.04 本身還有一些周邊坑雖然不影響最終 so但會(huì)嚴(yán)重打斷你的節(jié)奏。6.1 apt 源與依賴安裝慢的問題Ubuntu 24.04 默認(rèn)的 apt 源在國內(nèi)訪問很慢編譯前要裝 zip、unzip、ninja-build、openjdk 等基礎(chǔ)工具如果一直卡在下載階段后續(xù)什么都干不了。解決方案有幾種最基本的先把 apt 源換成可用的鏡像然后執(zhí)行sudo apt update sudo apt install -y cmake ninja-build zip unzip openjdk-17-jdk這里裝ninja是可選的VTK 用 Unix Makefiles 也能編但 Ninja 的輸出更清晰出錯(cuò)時(shí)定位更快。實(shí)測(cè)下來兩者編譯時(shí)間沒有明顯差異。6.2 ccache 配置不當(dāng)導(dǎo)致的問題如果你本機(jī)裝了 ccache 并設(shè)置了CCACHE_PREFIX或CCACHE_DIR全局環(huán)境變量交叉編譯時(shí)會(huì)導(dǎo)致一個(gè)很奇怪的現(xiàn)象編譯產(chǎn)物一樣但每次 configure 都會(huì)重新觸發(fā)全量編譯因?yàn)?ccache 對(duì)交叉編譯器的hash_dir處理比較敏感。解決方法是給該項(xiàng)目的編譯單獨(dú)設(shè)置export CCACHE_DIR$HOME/.ccache-vtk-android不要用默認(rèn)的~/.ccache。這樣不僅避免串臺(tái)還能保留桌面編譯的緩存。6.3 磁盤空間和 inode 用量VTK 9.3.1 源碼加 build 目錄體積很容易超過 15GB且全是小文件在 ext4 上會(huì)消耗大量 inode。如果你用的是一塊分區(qū)空間很小的虛擬機(jī)磁盤編譯到一半報(bào)No space left on device且 df -h 顯示還有空間那就是 inode 用光了。檢查命令df -i $HOME/vtk-android-build如果Use%接近 100%趕緊清理其它項(xiàng)目緩存或者挪到一個(gè)更大的分區(qū)。別問我為什么強(qiáng)調(diào)這一點(diǎn)我第一次是在 WSL 的虛擬磁盤上編譯的20GB 空間剩了 3GB結(jié)果 inode 用盡只能從頭再來。6.4 關(guān)于 WSL 的額外提醒我看到熱搜詞里有 Ubuntu 24.04 和 WSL 相關(guān)的條目順帶提一句。WSL2 環(huán)境下編譯 VTK Android 版理論上可行但需要注意WSL2 的跨文件系統(tǒng)性能非常差源碼和 build 目錄必須放在 WSL 的 ext4 文件系統(tǒng)內(nèi)即~/下不要放在/mnt/c/。否則 CMake 生成階段會(huì)因?yàn)槲募?IO 極慢而顯得像死機(jī)一樣。如果你看到 configure 卡在Optimize for native binaries很久不動(dòng)先檢查路徑位置再檢查 resctrl 之類的 CPU 限制問題。7. 我最終沉淀下來的幾件事這個(gè)項(xiàng)目做完之后有幾個(gè)判斷我認(rèn)為是長期有效的干脆一起寫出來。第一VTK 的 Android 編譯不存在“一個(gè)命令行搞定”的靈丹妙藥。網(wǎng)上流傳的官方文檔命令我試過好幾次要么模塊裁剪不夠、要么鏈接期失敗。主要是因?yàn)?VTK 版本、NDK 版本、CMake 版本三者的排列組合實(shí)在太多。解決問題的核心不是背命令行而是理解 module 依賴關(guān)系和 CMake 交叉編譯的原理這樣碰到任何版本的 VTK 都能從容應(yīng)對(duì)。第二編譯前先確定渲染后端。如果你的應(yīng)用目標(biāo)機(jī)型基本都是 2018 年之后的直接鎖 GLES3如果需要兼容老設(shè)備最好在工程里準(zhǔn)備兩套 so或者在運(yùn)行期動(dòng)態(tài)探測(cè) GPU 能力。但 VTK 的源碼本身在 GLES2/GLES3 之間切換并不平滑跑起來再切換容易出狀態(tài)殘留。這件事必須在編譯前決定。第三盡量把 build 腳本沉淀下來。我后來寫了一個(gè)build_android.sh每次配置、構(gòu)建、安裝、驗(yàn)證全部封裝成腳本哪怕三個(gè)月后再編譯一次也不會(huì)慌亂。過程腳本比文檔靠譜。最后再分享一個(gè)小技巧編譯完成后別急著刪 build 目錄。VTK 的install目錄和 build 目錄里的CMakeCache.txt是后續(xù)排查問題的重要線索。如果集成階段發(fā)現(xiàn)某個(gè)符號(hào)缺失回來看 build 目錄里的CMakeFiles/CMakeError.log和CMakeOutput.log比重新跑一遍編譯要快得多。這個(gè)習(xí)慣在我用 VTK 做渲染項(xiàng)目時(shí)救過我很多次。