构建系统介绍

SCons

Godot 使用 SCons 来构建。我们喜欢它，不会因为其他任何事情而改变它。我们甚至不确定其他构建系统是否可以完成 Godot 的构建任务。我们不断收到将构建系统移至 CMake 或 Visual Studio 的请求，但这不会发生。我们选择 SCons 而不是其他构建系统的原因有很多，例如：

• Godot 可以针对多种不同的平台进行编译：所有 PC 平台、所有移动平台、各种游戏主机、WebAssembly。

• 开发者们经常需要同时将代码编译到多个平台上，或者同一个平台的不同架构上，但他们负担不起每次都要重新配置和重构项目。SCons 可以毫不费力地完成此任务，而不会破坏构建。

• 无论对项目做出多少修改、配置、增加、删除之类的事情，SCons 都不会把构建工作搞砸。你需要通过 Scons 进行清理和重新构建的机会比你被闪电击中的几率还低。

• Godot的构建过程并不简单. 几个文件由代码生成(绑定), 其他文件被解析(着色器), 而其他文件则需要提供自定义(插件). 这需要复杂的逻辑, 而该逻辑更容易用实际的编程语言(如Python)编写, 而不是使用仅用于构建的基于宏的语言.

• Godot的构建过程大量使用了交叉编译工具. 每个平台都有特定的检测过程, 需为每个平台编写特殊代码, 将这些作为特殊情况处理.

因此, 如果你想要自己构建 Godot 的话, 请持一个开放的态度, 至少稍微熟悉一下这个构建系统.

场景布置

你可以参照平台相关的构建文档 为 Android 平台编译、为 iOS 平台编译、为 macOS 平台编译、为通用 Windows 平台编译、为 Web 平台编译、为 Windows 平台编译、为 X11 平台编译（Linux、*BSD 操作系统）。

注意, 在 Windows/Visual Studio 环境下, 你要使用 VS2017 x86_x64 兼容工具命令提示符 这类工具(具体视你安装的版本来定), 而不是标准Windows命令提示符下输入以下命令.

选择平台

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

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

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

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

    android
    javascript
    server
    windows
    x11

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

运行时使用 platform= (或简称为 p=)参数, 为特定平台构建(例如x11):

scons platform=x11

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=x11 -j 4

生成的二进制文件

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

godot.<platform>.[opt].[tools/debug].<architecture>[extension]

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

ls bin
bin/godot.x11.tools.64

这意味着该二进制文件适用于X11, 未经过优化, 具有已编译的工具(整个编辑器), 并且适用于64位.

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

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

将该二进制文件复制到您喜欢的任何位置, 因为它包含项目管理器, 编辑器和执行游戏的所有方法. 但是, 它缺少将其导出到不同平台的数据. 为此, 需要导出模板(可以从 godotengine.org 下载, 或者您可以自己构建它们).

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

工具

在所有PC平台(Linux, Windows, macOS)上工具默认被启用, 在其他平台上默认被禁用. 禁用工具会生成可以运行项目的二进制文件, 但不包括编辑器和项目管理器.

scons platform=<platform> tools=yes/no

目标

构建目标控制着优化和调试标志. 每种模式表示:

• debug : 使用C ++调试符号进行构建, 运行时检查(执行检查并报告错误), 并且几乎没有优化.

• release_debug : 不使用C ++调试符号和优化进行构建, 但保留运行时检查(执行检查并报告错误). 官方编辑器二进制文件使用此配置.

• release : 不使用符号进行构建, 具有优化功能, 几乎没有运行时检查. 该构建目标不能与 tools=yes 一起使用, 因为编辑器需要一些调试功能和运行时检查才能运行.

scons platform=<platform> target=debug/release_debug/release

该标志追加 .debug 后缀(用于调试), 或 .tools (用于启用工具的调试). 启用优化(release)后, 它会追加 .opt 后缀.

位（Bit）

位用于控制要运行二进制文件的CPU或OS版本. 它主要针对在桌面平台, 而在其他平台都会被忽略.

• 32 : 为32位平台构建二进制文件.

• 64 : 为64位平台构建二进制文件.

• default : 针对与主机平台匹配的架构进行构建.

scons platform=<platform> bits=default/32/64

相关时, 此标志在生成的二进制文件后附加 .32 或 .64 后缀. 如果使用 bits=default, 则后缀将匹配检测到的体系结构.

自定义模块

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

导出模板

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

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

android_debug.apk
android_release.apk
webassembly_debug.zip
webassembly_release.zip
linux_server_32
linux_server_64
linux_x11_32_debug
linux_x11_32_release
linux_x11_64_debug
linux_x11_64_release
osx.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的优势是易于设置.