构建系统介绍

SCons

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

  • Godot可以针对多种不同的平台进行编译：所有PC平台、所有移动平台、各种游戏机、和WebAssembly。
  • 开发者们经常需要 同时 将代码编译到多个平台上，或者同一个平台的不同架构上，但他们负担不起每次都要重新配置和重构项目。SCons可以毫不费力地完成此任务，而不会破坏构建。
  • 无论对项目做出多少修改、配置、增加、删除之类的事情，SCons 都不会 把构建工作搞砸。你需要通过Scons进行清理和重新构建的机会比你被闪电击中的几率还低。
  • Godot的构建过程并不简单。几个文件由代码生成(绑定)，其他文件被解析(着色器)，而其他文件则需要提供自定义(插件)。这需要复杂的逻辑，而该逻辑更容易用实际的编程语言(如Python)编写，而不是使用仅用于构建的基于宏的语言。
  • Godot的构建过程大量使用了交叉编译工具。每个平台都有特定的检测过程，需为每个平台编写特殊代码，将这些作为特殊情况处理。

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

场景布置

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

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

选择平台

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

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

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

  1. scons platform=list
  2. scons: Reading SConscript files ...
  3. The following platforms are available:
  5.     android
  6.     javascript
  7.     server
  8.     windows
  9.     x11
  11. Please run SCons again and select a valid platform: platform=<string>

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

  1. scons platform=x11

这将开始 Godot 的构建进程，需要花一段时间才能完成。如果您希望 Scons 的构建速度更快，请使用 -j <cores> 参数指定构建任务要使用多少个CPU核心。或者只是让它使用一个核心，这样您可以继续使用您的电脑的做其他事情 :)

使用 4 核的示例：

  1. scons platform=x11 -j 4

生成的二进制文件

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

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

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

  1. ls bin
  2. bin/godot.x11.tools.64

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

A Windows binary with the same configuration will look like this:

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

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

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

工具

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

  1. scons platform=<platform> tools=yes/no

目标

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

  • debug：使用C ++调试符号进行构建，运行时检查(执行检查并报告错误)，并且几乎没有优化。
  • release_debug：不使用C ++调试符号和优化进行构建，但保留运行时检查(执行检查并报告错误)。官方编辑器二进制文件使用此配置。
  • release：不使用符号进行构建，具有优化功能，几乎没有运行时检查。该构建目标不能与 tools=yes 一起使用，因为编辑器需要一些调试功能和运行时检查才能运行。
  1. scons platform=<platform> target=debug/release_debug/release

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

位 (bits)

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

  • 32：为32位平台构建二进制文件。
  • 64：为64位平台构建二进制文件。
  • default：针对与主机平台匹配的架构进行构建。
  1. scons platform=<platform> bits=default/32/64

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

Custom modules

It’s possible to compile modules residing outside of Godot’s directory tree, along with the built-in modules.

A custom_modules build option can be passed to the command line before compiling. The option represents a comma-separated list of directory paths containing a collection of independent C++ modules that can be seen as C++ packages, just like the built-in modules/ directory.

For instance, it’s possible to provide both relative, absolute, and user directory paths containing such modules:

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

注解

If there’s any custom module with the exact directory name as a built-in module, the engine will only compile the custom one. This logic can be used to override built-in module implementations.

参见

自定义C++模块

Cleaning generated files

Sometimes, you may encounter an error due to generated files being present. You can remove them by using scons --clean <options>, where <options> is the list of build options you’ve used to build Godot previously.

Alternatively, you can use git clean -fixd which will clean build artifacts for all platforms and configurations. Beware, as this will remove all untracked and ignored files in the repository. Don’t run this command if you have uncommitted work!

其他构建选项

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

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

Overriding the build options

Using a file

The default custom.py file can be created at the root of the Godot Engine source to initialize any SCons build options passed via the command line:

  1. # custom.py
  3. optimize = "size"
  4. module_mono_enabled = "yes"
  5. use_llvm = "yes"
  6. extra_suffix = "game_title"

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

Another custom file can be specified explicitly with the profile command line option, both overriding the default build configuration:

  1. scons profile=path/to/custom.py

注解

Build options set from the file can be overridden by the command line options.

It’s also possible to override the options conditionally:

  1. # custom.py
  3. import version
  5. # Override options specific for Godot 3.x and 4.x versions.
  6. if version.major == 3:
  7.     pass
  8. elif version.major == 4:
  9.     pass

Using the SCONSFLAGS

SCONSFLAGS is an environment variable which is used by the SCons to set the options automatically without having to supply them via the command line.

For instance, you may want to build Godot in parallel with the aforementioned -j option for all the future builds:

Linux/macOS

Windows (cmd)

Windows (powershell)

  1. export SCONSFLAGS="-j4"
  1. set SCONSFLAGS=-j4
  1. $env:SCONSFLAGS="-j4"

导出模板

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

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

  1. android_debug.apk
  2. android_release.apk
  3. webassembly_debug.zip
  4. webassembly_release.zip
  5. linux_server_32
  6. linux_server_64
  7. linux_x11_32_debug
  8. linux_x11_32_release
  9. linux_x11_64_debug
  10. linux_x11_64_release
  11. osx.zip
  12. version.txt
  13. windows_32_debug.exe
  14. windows_32_release.exe
  15. windows_64_debug.exe
  16. 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的优势是易于设置。