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

构建系统介绍

场景布置

Godot uses the SCons build system. Please refer to the documentation for:

• 为 Android 平台编译

• 为 iOS 平台编译

• Compiling for Linux, *BSD

• 为 macOS 平台编译

• 为通用 Windows 平台编译

• 为 Web 平台编译

• 为 Windows 平台编译

选择平台

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

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

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

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

    android
    javascript
    linuxbsd
    server
    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

This will start the build process, which will take a while. 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 platform=linuxbsd -j4

生成的二进制文件

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

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

对于先前的构建尝试，结果将如下所示：

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

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

目标

Target controls if the editor is contained and debug flags are used. All builds are optimized. Each mode means:

• editor: Build with editor, optimized, with debugging code (defines: TOOLS_ENABLED, DEBUG_ENABLED, -O2//O2)

• template_debug: Build with C++ debugging symbols (defines: DEBUG_ENABLED, -O2//O2)

• template_release: Build without symbols (defines: -O3//O2)

The editor is enabled by default in all PC targets (Linux, Windows, macOS), disabled for everything else. Disabling the editor produces a binary that can run projects but does not include the editor or the Project Manager.

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

Development and production aliases

When creating builds for development (running debugging/profiling tools), you often have different goals compared to production builds (making binaries as fast and small as possible).

Godot provides two aliases for this purpose:

• dev_mode=yes is an alias for verbose=yes warnings=extra werror=yes tests=yes. This enables warnings-as-errors behavior (similar to Godot's continuous integration setup) and also builds unit tests so you can run them locally.

• production=yes is an alias for use_static_cpp=yes debug_symbols=no lto=auto. Statically linking libstdc++ allows for better binary portability when compiling for Linux. This alias also enables link-time optimization when compiling for Linux, Web and Windows with MinGW, but keeps LTO disabled when compiling for macOS, iOS or Windows with MSVC. This is because LTO on those platforms is very slow to link or has issues with the generated code.

You can manually override options from those aliases by specifying them on the same command line with different values. For example, you can use scons production=yes debug_symbols=yes to create production-optimized binaries with debugging symbols included.

Dev build

备注

dev_build should not be confused with dev_mode, which is an alias for several development-related options (see above).

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 Using sanitizers for more information.

Debugging symbols

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.

Optimization level

Several compiler optimization levels can be chosen from:

• optimize=speed_trace (default when targeting non-Web platforms): Favors execution speed at the cost of larger binary size. Optimizations may sometimes negatively impact debugger usage (stack traces may be less accurate. If this occurs to you, use optimize=debug instead.

• optimize=speed: Favors even more execution speed, at the cost of even larger binary size compared to optimize=speed_trace. Even less friendly to debugging compared to optimize=debug, as this uses the most aggressive optimizations available.

• optimize=size (default when targeting the Web platform): Favors small binaries at the cost of slower execution speed.

• optimize=debug: Only enables optimizations that do not impact debugging in any way. This results in faster binaries than optimize=none, but slower binaries than optimize=speed_trace.

• optimize=none: Do not perform any optimization. This provides the fastest build times, but the slowest execution times.

• optimize=custom (advanced users only): Do not pass optimization arguments to the C/C++ compilers. You will have to pass arguments manually using the CFLAGS, CCFLAGS and CXXFLAGS SCons options.

Architecture

The arch option is meant to control the CPU or OS version intended to run the binaries. It is focused mostly on desktop platforms and ignored everywhere else.

Supported values for the arch option are auto, x86_32, x86_64, arm32, arm64, rv64, ppc32, ppc64 and wasm32.

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

This flag appends the value of arch to resulting binaries when relevant. The default value arch=auto detects the architecture that matches the host platform.

自定义模块

可以编译驻扎在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"

你也可以在编译前禁用一些内置模块，节省一些构建引擎的时间。详情请参阅 为尺寸优化构建 页面。

参见

您可以使用在线 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用来自动设置选项, 而无需通过命令行提供.

For instance, you may want to force a number of CPU threads with the aforementioned -j option for all future builds:

Linux/macOSWindows (cmd)Windows (PowerShell)

export SCONSFLAGS="-j4"

SCU (single compilation unit) build

Regular builds tend to be bottlenecked by including large numbers of headers in each compilation translation unit. Primarily to speed up development (rather than for production builds), Godot offers a "single compilation unit" build (aka "Unity / Jumbo" build).

For the folders accelerated by this option, multiple .cpp files are compiled in each translation unit, so headers can be shared between multiple files, which can dramatically decrease build times.

To make a SCU build, use the scu_build=yes SCons option.

备注

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
web_debug.zip
web_release.zip
linux_server_32
linux_server_64
linux_x11_32_debug
linux_x11_32_release
linux_x11_64_debug
linux_x11_64_release
macos.zip
version.txt
windows_32_debug.exe
windows_32_release.exe
windows_64_debug.exe
windows_64_release.exe

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

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

如果要针对多个平台进行开发, 则macOS绝对是用于交叉编译的最方便的主机平台, 因为您可以针对几乎每个目标(UWP除外)进行交叉编译.Linux和Windows位居第二, 但是Linux的优势是易于设置.