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 。
arch

CMake 通过工具链文件设置架构， macOS 通用架构通过 CMAKE_OSX_ARCHITECTURES 属性控制，该属性在定义目标时会被复制到目标中。
debug_crt

CMake 通过将 CMAKE_MSVC_RUNTIME_LIBRARIES 的值复制到目标定义中来控制 Windows 运行时库的链接。如果该变量尚未设置，godot-cpp 将会设置它。因此，请在引入其他依赖项之前包含 godot-cpp，以确保该值在所有项目中生效。

基本操作流程

克隆 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=

编译

该命令指示 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