构建系统介绍

Godot is a primarily C++ project and it uses the SCons build system. We love SCons for how maintainable and easy to set up it makes our buildsystem. And thanks to that compiling Godot from source can be as simple as running:

scons

This produces an editor build for your current platform, operating system, and architecture. You can change what gets built by specifying a target, a platform, and/or an architecture. For example, to build an export template used for running exported games, you can run:

scons target=template_release

If you plan to debug or develop the engine, then you might want to enable the dev_build option to enable dev-only debugging code:

scons dev_build=yes

Following sections in the article will explain these and other universal options in more detail. But before you can compile Godot, you need to install a few prerequisites. Please refer to the platform documentation to learn more:

These articles cover in great detail both how to setup your environment to compile Godot on a specific platform, and how to compile for that platform. Please feel free to go back and forth between them and this article to reference platform-specific and universal configuration options.

Using multi-threading

The build process may take a while, depending on how powerful your system is. By default, Godot's SCons setup is configured to use all CPU threads but one (to keep the system responsive during compilation). If you want to adjust how many CPU threads SCons will use, use the -j <threads> parameter to specify how many threads will be used for the build.

Example for using 4 threads:

scons -j4

选择平台

Godot的构建系统将从检测可构建的平台开始. 如果未检测到, 该平台将不会出现在可用平台列表中. 本教程后续部分将介绍每种平台的构建要求.

仅通过调用 scons 即可调用SCons. 如果未指定平台,SCons将基于主机平台自动检测目标平台. 然后它将立即开始为目标平台构建.

要列出可用的目标平台，请使用 scons platform=list：

scons platform=list
scons: Reading SConscript files ...
The following platforms are available:

    android
    ios
    linuxbsd
    macos
    web
    windows

Please run SCons again and select a valid platform: platform=<string>

To build for a platform (for example, linuxbsd), run with the platform= (or p= to make it short) argument:

scons platform=linuxbsd

生成的二进制文件

生成的二进制文件将被放置在 bin/ 子目录中，通常使用这种命名约定：

godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]

For the previous build attempt, the result would look like this:

ls bin
bin/godot.linuxbsd.editor.x86_64

This means that the binary is for Linux or *BSD (not both), is not optimized, has the whole editor compiled in, and is meant for 64 bits.

一个具有相同配置的Windows二进制文件将如下所示:

C:\godot> dir bin/
godot.windows.editor.64.exe

Copy that binary to any location you like, as it contains the Project Manager, editor and all means to execute the game. However, it lacks the data to export it to the different platforms. For that the export templates are needed (which can be either downloaded from godotengine.org, or you can build them yourself).

除此之外, 在所有的构建目标平台中有几个标准选项可以进行设置, 下面将对此进行说明.

目标

The target option controls if the editor is compiled and debug flags are used. Optimization levels (optimize) and whether each build contains debug symbols (debug_symbols) is controlled separately from the target. Each mode means:

  • target=editor: Build an editor binary (defines TOOLS_ENABLED and DEBUG_ENABLED)

  • target=template_debug: Build a debug export template (defines DEBUG_ENABLED)

  • target=template_release: Build a release export template

所有 PC 目标（Linux、Windows、macOS）上都默认启用了编辑器，其他目标默认禁用。禁用编辑器时得到的二进制文件可以运行项目，但不包含编辑器和项目管理器。

The list of command line arguments available varies depending on the build type.

scons platform=<platform> target=editor|template_debug|template_release

开发别名与生产别名

针对开发创建构建（运行调试工具或性能分析工具）时，你的目的通常与生产构建不同（生产构建要求让二进制文件尽可能又快又小）。

Godot 为此提供了两种别名：

  • dev_mode=yes 是 verbose=yes warnings=extra werror=yes tests=yes 的别名，启用了“将警告当作错误”的行为（与 Godot 的持续集成设置一致），并且会构建单元测试，这些测试能够在本地运行。

  • production=yes 是 use_static_cpp=yes debug_symbols=no lto=auto 的别名。为 Linux 构建时，静态链接 libstdc++ 可以提升二进制文件的可移植性。在 Linux、Web 和在 Windows 上使用 MinGW 编译时，这个别名还会启用链接时优化（Link-Time Optimization，LTO），而在 macOS、iOS 和在 Windows 上使用 MSVC 编译时 LTO 是禁用的。这是因为这些平台上的 LTO 不是非常缓慢就是生成的代码有问题。

这些别名中的选项可以手动覆盖，在命令行中将其指定为不同的值即可。例如使用 scons production=yes debug_symbols=yes 即可创建针对生产优化并且带有调试符号的二进制文件。

开发构建

备注

请勿混淆 dev_build 与 dev_mode，后者是部分开发相关选项的别名（见上文）。

When doing engine development the dev_build option can be used together with target to enable dev-specific code. dev_build defines DEV_ENABLED, disables optimization (-O0//0d), enables generating debug symbols, and does not define NDEBUG (so assert() works in thirdparty libraries).

scons platform=<platform> dev_build=yes

This flag appends the .dev suffix (for development) to the generated binary name.

参见

There are additional SCons options to enable sanitizers, which are tools you can enable at compile-time to better debug certain engine issues. See 使用 Sanitizer for more information.

调试符号

By default, debug_symbols=no is used, which means no debugging symbols are included in compiled binaries. Use debug_symbols=yes to include debug symbols within compiled binaries, which allows debuggers and profilers to work correctly. Debugging symbols are also required for Godot's crash stacktraces to display with references to source code files and lines.

The downside is that debugging symbols are large files (significantly larger than the binaries themselves). As a result, official binaries currently do not include debugging symbols. This means you need to compile Godot yourself to have access to debugging symbols.

When using debug_symbols=yes, you can also use separate_debug_symbols=yes to put debug information in a separate file with a .debug suffix. This allows distributing both files independently. Note that on Windows, when compiling with MSVC, debugging information is always written to a separate .pdb file regardless of separate_debug_symbols.

小技巧

Use the strip <path/to/binary> command to remove debugging symbols from a binary you've already compiled.

优化级别

以下几种编译器优化级别可供选择：

  • optimize=speed_trace（目标平台非 Web 时默认）：执行速度更快，但二进制文件更大。优化有时会对调试器的使用产生负面影响（可能会降低堆栈跟踪的准确性）。如果遇到了这种情况，请改用 optimize=debug。

  • optimize=speed：与 optimize=speed_trace 相比，执行速度更快，但二进制文件也更大。与 optimize=debug 相比更不利于调试，因为会尽可能使用最激进的优化手段。

  • optimize=size（目标平台为 Web 时默认）：二进制文件更小，但执行速度更慢。

  • optimize=debug：仅启用不会对调试产生影响的优化手段。得到的二进制文件比 optimize=none 快、比 optimize=speed_trace 慢。

  • optimize=none：不进行任何优化。构建时间最快、执行速度最慢。

  • optimize=custom（仅限高阶用户）：不会向 C/C++ 编译器传递优化参数。你需要通过 cflags、ccflags、cxxflags SCons 选项手动传递参数。

架构

arch 选项的作用是控制用于运行二进制文件的 CPU 或操作系统版本。主要针对桌面平台，其他平台都会忽略该选项。

arch 选项支持的取值有：auto、 x86_32、 x86_64、 arm32、 arm64、 rv64、 ppc32、 ppc64、 wasm32。

scons platform=<platform> arch={auto|x86_32|x86_64|arm32|arm64|rv64|ppc32|ppc64|wasm32}

使用该标志时，最终得到的二进制文件的末尾会加上 arch 的取值。默认值 arch=auto 会检测与宿主平台匹配的架构。

自定义模块

可以编译驻扎在Godot目录树之外的模块, 以及内置模块.

在编译之前, 可以在命令行中传递一个 custom_modules 构建选项. 这个选项代表了一个以逗号分隔的目录路径列表, 其中包含了一系列独立的C++模块, 这些模块可以被看作是C++包, 就像内置的 modules/ 目录一样.

例如, 可以同时提供包含此类模块的相对, 绝对和用户目录路径:

scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules"

备注

如果有任何自定义模块的目录名与内置模块的目录名完全相同, 引擎将只编译自定义模块. 这个逻辑可以用来覆盖内置模块的实现.

参见

自定义 C++ 模块

清理生成的文件

有时, 你可能会遇到一个错误, 因为生成的文件存在. 你可以使用``scons --clean <options>``删除它们, 其中 <options> 是你之前用来构建Godot的构建选项列表.

或者, 你也可以使用``git clean -fixd``来清理所有平台和配置的构建工件. 注意, 这将删除版本库中所有未跟踪和忽略的文件. 如果你有未提交的工作, 请不要运行这个命令！

其他构建选项

你还可以使用其他几个构建选项来配置Godot的构建方式(编译器, 调试选项等), 以及要包含/禁用的功能.

检查 scons --help 的输出, 以获取有关你愿意编译的版本的每个选项的详细信息.

重写构建选项

使用文件

默认的 custom.py 文件可以在Godot引擎源的根部创建, 以初始化任何通过命令行传递的SCons构建选项:

custom.py
optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"

You can also disable some of the built-in modules before compiling, saving some time it takes to build the engine. See 为尺寸优化构建 page for more details.

参见

你可以使用在线 Godot 构建选项生成器 , 生成一个包含SCons选项的 custom.py 文件. 然后你可以保存这个文件, 并将其放在Godot源目录的根目录下.

另一个自定义文件可以用 profile 命令行选项明确指定, 都会覆盖默认的构建配置:

scons profile=path/to/custom.py

备注

从文件中设置的构建选项可以被命令行选项所覆盖.

也可以有条件地重写这些选项:

custom.py
import version

# Override options specific for Godot 3.x and 4.x versions.
if version.major == 3:
    pass
elif version.major == 4:
    pass

使用SCONSFLAGS

SCONSFLAGS 是一个环境变量,SCons用来自动设置选项, 而无需通过命令行提供.

例如你可能会想要让后续的构建都使用前面提到的 -j 选项来强制使用特定数量的 CPU 线程：

export SCONSFLAGS="-j4"

SCU（单编译单元）构建

普通构建的瓶颈通常在于每个编译翻译单元都包含了大量的头文件。为了加速开发（并非针对生产构建），Godot 提供了“单编译单元”构建（也叫“统一构建”或“巨型构建”）。

在能够被该选项加速的文件夹中，每个翻译单元都会编译多个 .cpp 文件，因此头文件会在多个文件之间共享，从而大幅降低编译时长。

要进行 SCU 构建，请使用 Scons 选项 scu_build=yes。

备注

When developing a Pull Request using SCU builds, be sure to make a regular build prior to submitting the PR. This is because SCU builds by nature include headers from earlier .cpp files in the translation unit, therefore won't catch all the includes you will need in a regular build. The CI will catch these errors, but it will usually be faster to catch them on a local build on your machine.

导出模板

官方的导出模板可以从 Godot 的官方网站 下载到. 此外, 你可能想要自己构建它们(可能想要构建更新的版本, 要使用自定义模块, 不信任我们编译的包是否安全).

如果下载官方导出模板程序包并解压缩, 你会注意到大多数文件都是针对每个平台的优化二进制文件或程序包:

android_debug.apk
android_release.apk
android_source.zip
ios.zip
linux_debug.arm32
linux_debug.arm64
linux_debug.x86_32
linux_debug.x86_64
linux_release.arm32
linux_release.arm64
linux_release.x86_32
linux_release.x86_64
macos.zip
version.txt
web_debug.zip
web_dlink_debug.zip
web_dlink_nothreads_debug.zip
web_dlink_nothreads_release.zip
web_dlink_release.zip
web_nothreads_debug.zip
web_nothreads_release.zip
web_release.zip
windows_debug_x86_32_console.exe
windows_debug_x86_32.exe
windows_debug_x86_64_console.exe
windows_debug_x86_64.exe
windows_debug_arm64_console.exe
windows_debug_arm64.exe
windows_release_x86_32_console.exe
windows_release_x86_32.exe
windows_release_x86_64_console.exe
windows_release_x86_64.exe
windows_release_arm64_console.exe
windows_release_arm64.exe

要自己创建它们, 请按照该教程中针对每个平台的详细说明的部分进行操作. 每个平台都说明了如何创建自己的模板.

version.txt 文件应包含相应的 Godot 版本标识符。该文件用于在特定于版本的目录中安装导出模板，以避免冲突。例如，如果你要为 Godot 3.1.1 构建导出模板，则 version.txt 文件的第一行应包含 3.1.1.stable（没有其他内容）。该版本标识符在 Godot Git 仓库库中的 version.py 文件的 major、minor、patch（如果存在）和 status 行。

If you are developing for multiple platforms, macOS is definitely the most convenient host platform for cross-compilation, since you can cross-compile for every target. Linux and Windows come in second place, but Linux has the advantage of being the easier platform to set this up.