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.

次級建置系統:使用 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 。

  • arch

    CMake 通過工具鏈檔案設定架構, macOS 通用架構通過 CMAKE_OSX_ARCHITECTURES 屬性控制,該屬性在定義目標時會被複製到目標中。

  • debug_crt

    CMake 通過將 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