Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
次級建置系統:使用 CMake
也參考
本頁文件介紹了如何編譯 godot-cpp。如果你想編譯 Godot,請參閱 建置系統介紹。
除了基於 SCons 的建置系統之外,godot-cpp 還提供了一個 CMakeLists.txt 檔案,以支援那些更喜歡使用 CMake 而不是 SCons 作為建置系統的使用者。
雖然 CMake 系統仍在積極維護中,但它被視為 SCons 建置系統的輔助系統。這意味著它可能缺少一些 SCons 專案可以使用的功能。
前言
獨立於擴充專案編譯 godot-cpp 的功能主要面向 godot-cpp 開發人員、套件維護人員和 CI/CD 人員。
以下範例展示了如何使用 CMake 在擴充專案中使用 godot-cpp 庫:
設定 godot-cpp 的範例列在頁面底部,其中許多範例可能對設定你的專案有所協助。
CMake 的 Debug vs Godot 的 template_debug
在許多討論中都提到過,人們常常將啟用除錯符號編譯 C++ 原始碼,和啟用除錯功能編譯 Godot 擴充混為一談。這兩個概念並非互斥。
Debug 功能
啟用預處理器定義,以便選擇性地編譯程式碼,從而協助 Godot 擴充的使用者開發自己的專案。
editor 和 template_debug 建置中啟用了除錯功能,可以在設定階段進行指定,如下所示:
cmake -S godot-cpp -B cmake-build -DGODOTCPP_TARGET=<target choice>
除錯
設定編譯器標誌 ,以便生成除錯符號,協助 Godot 擴充開發者除錯他們的擴充 。
Debug 是 CMake 專案的預設建置型別,選擇其他建置型別的方法取決於所使用的生成器:
對於單個設定生成器,在 configure 命令中新增
-DCMAKE_BUILD_TYPE=<type>。對於多設定生成器,請在建置命令中新增
--config<type>。
其中 <type> 是 Debug 、 Release 、 RelWithDebInfo 和 MinSizeRel 之一。
SCons 偏差
並非所有 SCons 系統中的程式碼都能完美地用 CMake 表示,以下是一些顯著差異:
debug_symbols不再是一個顯式選項,在使用 CMake 建置設定時啟用;
Debug,RelWithDebInfo。dev_build停用時未定義
NDEBUG,使用 CMake 建置設定時會設定NDEBUG,Release,MinSizeRel。archCMake 通過工具鏈檔案設定架構, macOS 通用架構通過
CMAKE_OSX_ARCHITECTURES屬性控制,該屬性在定義目標時會被複製到目標中。debug_crtCMake 通過將
CMAKE_MSVC_RUNTIME_LIBRARIES的值複製到目標定義中來控制 Windows 執行階段函式庫的連結。如果該變數尚未設定,godot-cpp 將會設定它。因此,請在引入其他相依項目之前包含 godot-cpp,以確保該值在所有專案中生效。
此外, hook system 在與 CMake 一起使用時的工作方式略有不同:
您的子類別名稱必須為
CustomBindingGeneratorHooks。將包含您自訂子類別的 Python 檔案的路徑通過 `
GODOTCPP_BINDING_HOOK_FILE` 選項傳遞給 CMake。
基本操作流程
克隆 Git 倉庫
git clone https://github.com/godotengine/godot-cpp.git
Cloning into 'godot-cpp'...
...
設定建置
cmake -S godot-cpp -B cmake-build -G Ninja
-S指定來源目錄為godot-cpp-B指定建置目錄為cmake-build-G指定生成器為Ninja
本例中的來源目錄是新克隆的 godot-cpp 的源根目錄。CMake 還會將命令中的第一個路徑解釋為來源路徑;如果指定了現有的建置路徑,則會從建置快取中推斷出來源路徑。
以下三個命令等效:
# Current working directory is the godot-cpp source root.
cmake . -B build-dir
# Current working directory is an empty godot-cpp/build-dir.
cmake ../
# Current working directory is an existing build path.
cmake .
指定建置目錄是為了避免生成的檔案使原始碼樹充斥著建置產物 。
CMake 本身並不直接編譯程式碼,它的作用是生成供建置工具使用的檔案。在此範例中,Ninja 生成器所建立的是 Ninja build 檔案。
要查看可用的生成器清單,請執行 cmake --help 命令。
建置選項
要列出可用的選項,請使用 -L[AH] 命令行標誌。其中 A 表示進階選項,H 表示附帶協助資訊:
cmake -S godot-cpp -LH
這些選項需在設定階段通過命令行指定,例如:
cmake -S godot-cpp -DGODOTCPP_USE_HOT_RELOAD:BOOL=ON \
-DGODOTCPP_PRECISION:STRING=double \
-DCMAKE_BUILD_TYPE:STRING=Debug
更多詳細資訊,請參閱 setting-build-variables 和 build-configurations 的相關文件。
以下是一些主要的選項(非完整清單):
// Path to a custom GDExtension API JSON file.
// (takes precedence over GODOTCPP_GDEXTENSION_DIR)
// ( /path/to/custom_api_file )
GODOTCPP_CUSTOM_API_FILE:FILEPATH=
// Force disabling exception handling code. (ON|OFF)
GODOTCPP_DISABLE_EXCEPTIONS:BOOL=ON
// Path to a custom directory containing the GDExtension interface
// header and API JSON file. ( /path/to/gdextension_dir )
GODOTCPP_GDEXTENSION_DIR:PATH=gdextension
// Set the floating-point precision level. (single|double)
GODOTCPP_PRECISION:STRING=single
// Enable the extra accounting required to support hot reload. (ON|OFF)
GODOTCPP_USE_HOT_RELOAD:BOOL=
// Use the binding generator's hook system to modify generated files.
// ( /path/to/custom_generator_file.py)
GODOTCPP_BINDING_HOOK_FILE:FILEPATH=
編譯
該命令指示 CMake 呼叫其在指定目錄中生成的建置系統。預設建置目標為 template_debug,預設建置設定為 Debug。
cmake --build cmake-build
範例
雖然這些範例主要為 godot-cpp 開發者、套件維護者和 CI/CD 流程設計,但它們也可作為設定你自己的擴充專案時的參考。
關於如何在實際的擴充專案中集成與使用 godot-cpp 庫,具體範例請參見 Introduction (介紹)部分。
啟用集成測試
測試目標 godot-cpp-test 受控於 GODOTCPP_ENABLE_TESTING 選項,該選項預設為關閉狀態。
要設定並建置 godot-cpp 專案以啟用集成測試目標,相應的命令範例如下:
cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
cmake --build cmake-build --target godot-cpp-test
Windows 平台與 MSVC - Release 版本
只要從 CMake Downloads 頁面安裝 CMake 並將其新增到系統 PATH 環境變數中,同時安裝了包含 C++ 支援的 Microsoft Visual Studio,CMake 就能夠自動檢測到 MSVC 編譯器。
請注意,Visual Studio 屬於多設定生成器,因此需要在建置時指定具體的建置設定,例如使用 --config Release 參數。
cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
cmake --build cmake-build -t godot-cpp-test --config Release
MSys2/clang64 環境,"Ninja" 建置系統 - Debug 設定
需確保已安裝 ming-w64-clang-x86_64 工具鏈。
請注意,Ninja 是單設定(Single-Config)生成器,因此需要在設定階段指定建置型別。
在 msys2/clang64 終端中執行:
cmake -S godot-cpp -B cmake-build -G"Ninja" \
-DGODOTCPP_ENABLE_TESTING=YES -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build -t godot-cpp-test
MSys2/clang64 環境,"Ninja Multi-Config" 建置系統 - 開發建置,含 Debug 符號
需確保已安裝 ming-w64-clang-x86_64 工具鏈。
本次我們選擇 'Ninja Multi-Config' 生成器,因此建置型別將在實際建置時指定。
在 msys2/clang64 終端中執行:
cmake -S godot-cpp -B cmake-build -G"Ninja Multi-Config" \
-DGODOTCPP_ENABLE_TESTING=YES -DGODOTCPP_DEV_BUILD:BOOL=ON
cmake --build cmake-build -t godot-cpp-test --config Debug
針對 Web 平台的 Emscripten
目前該方案僅在 Windows 平台經過測試。你可以參考以下工作流程:
克隆並安裝最新版 Emscripten 工具至
c:\emsdk。在目前 PowerShell 會話中執行
C:\emsdk\emsdk.ps1 activate latest以啟用環境。通過
emcmake.bat工具將 emscripten 工具鏈新增至 CMake 命令。此步驟可手動完成,具體路徑可在emcmake.bat檔案中查看
C:\emsdk\emsdk.ps1 activate latest
emcmake.bat cmake -S godot-cpp -B cmake-build-web -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-web
從 Windows 交叉編譯至 Android 平台
為 Android 進行設定時,你可以選擇兩種不同的路徑。
第一種方法是使用 cmake-toolchains 文件中列出的 CMAKE_ANDROID_* 變數,通過命令行或在你自己的工具鏈檔案中進行指定。
第二種方法是利用 Android SDK 提供的工具鏈和腳本,並使用其中列出的 ANDROID_* 變數進行調整。其中 <version> 表示你已安裝的 NDK 版本(已使用 28.1.13356709 測試),<platform> 指 Android SDK 平台版本(已使用 android-29 測試)。
警告
Android SDK 官網 明確指出,他們不支援使用 CMake 內建的方法,並建議開發者堅持使用其提供的工具鏈檔案。
使用自訂工具鏈檔案
如 CMake 文件中所述:
cmake -S godot-cpp -B cmake-build --toolchain my_toolchain.cmake
cmake --build cmake-build -t template_release
若要通過純命令行實現同等效果,可執行如下操作:
cmake -S godot-cpp -B cmake-build \
-DCMAKE_SYSTEM_NAME=Android \
-DCMAKE_SYSTEM_VERSION=<platform> \
-DCMAKE_ANDROID_ARCH_ABI=<arch> \
-DCMAKE_ANDROID_NDK=/path/to/android-ndk
cmake --build cmake-build
使用 Android SDK 工具鏈檔案
此設定預設為最低支援的版本及 armv7-a 架構。
cmake -S godot-cpp -B cmake-build \
--toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake
cmake --build cmake-build
指定 Android 平台與 ABI:
cmake -S godot-cpp -B cmake-build \
--toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake \
-DANDROID_PLATFORM:STRING=android-29 \
-DANDROID_ABI:STRING=armeabi-v7a
cmake --build cmake-build