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...

主要构建系统：使用 SCons

参见

本页文档介绍了如何编译 godot-cpp。如果你想编译 Godot，请参阅 构建系统介绍。

godot-cpp 采用 SCons 作为其主要构建系统。该系统的设计仿照了 Godot 的构建系统，因此 Godot 中可用的部分命令在 godot-cpp 项目中同样适用。

新手入门

要构建一个 godot-cpp 项目，通常只需安装 SCons，然后在项目目录中直接运行以下命令：

scons

你可能需要了解可用的构建选项：

scons --help

若要彻底重新构建你的项目，请在构建命令中添加 --clean 参数：

scons --clean

关于常见的 SCons 参数和构建模式，你可以在 SCons 用户指南 中找到更多信息。此外，各个 godot-cpp 项目可能会添加额外的自定义命令，因此请查阅具体项目的文档以获取更多相关信息。

配置 IDE

大多数集成开发环境（IDE）可以通过读取 compile_commands.json 文件来解析 C++ 项目结构。你可以使用以下命令，通过 godot-cpp 生成此文件：

# Generate compile_commands.json while compiling.
scons compiledb=yes

# Generate compile_commands.json without compiling.
scons compiledb=yes compile_commands.json

如需了解更多信息，请查阅 IDE 配置指南。尽管该指南主要面向 Godot 引擎贡献者编写，但其内容大部分同样适用于 godot-cpp 项目。

在 Godot 中加载你的 GDExtension

Godot 通过在项目目录中查找 .gdextension 文件来加载 GDExtension。.gdextension 文件用于选择并加载与当前计算机/操作系统兼容的二进制文件。

godot-cpp-template 以及 入门章节 都提供了用于 GDExtension 的示例 .gdextension 文件，这些文件能与多种不同系统广泛兼容。

为多平台构建

GDExtension 需要能在多种不同的系统上运行，每个系统都需要单独的二进制文件和构建配置。如果你计划发布你的 GDExtension，我们建议你为 godot-cpp-template ` 中 .gdextension file 所提及的所有配置都提供相应的二进制文件。

有两种常用的方法可以实现跨平台构建：

  • 跨平台构建工具

  • 持续集成（CI）

godot-cpp-template 包含了一个基于 GitHub 的 CI 工作流的 示例配置。

使用自定义 API 文件

每个 godot-cpp 分支都附带一个适用于相应 Godot 版本的 API 文件（extension_api.json）（例如，4.3 分支附带与 Godot 版本 4.3 及更高版本兼容的 API 文件）。

不过，在某些情况下你可能希望使用自定义的 extension_api.json，例如：

  • 如果你希望使用来自 Godot master 分支的最新 API。

  • 如果你 自行构建，并且使用了与官方构建不同的选项（例如 disable_3d=yes 或 precision=double）。

  • 如果你希望使用由自定义模块暴露的 API。

要使用自定义 API 文件，首先需要从相应的 Godot 可执行文件生成它：

godot --dump-extension-api

生成的 extension_api.json 文件将位于可执行文件的目录下。想要使用它，你可以在构建命令中添加 custom_api_file 选项。

scons platform=<platform> custom_api_file=<PATH_TO_FILE>

或者，你也可以通过在 SConstruct 文件中添加以下一行，将其设置为项目的默认 API 文件：

localEnv["custom_api_file"] = "extension_api.json"