构建系统

相关源文件

• SConstruct
• core/SCsub
• core/core_builders.py
• editor/SCsub
• editor/editor_builders.py
• editor/editor_translation.cpp
• editor/editor_translation.h
• editor/icons/SCsub
• editor/icons/editor_icons_builders.py
• editor/template_builders.py
• editor/themes/editor_theme_builders.py
• gles3_builders.py
• glsl_builders.py
• main/SCsub
• main/main_builders.py
• methods.py
• modules/SCsub
• modules/gdscript/editor/script_templates/SCsub
• modules/mono/editor/script_templates/SCsub
• platform/SCsub
• platform/android/SCsub
• platform/android/detect.py
• platform/ios/detect.py
• platform/linuxbsd/detect.py
• platform/macos/detect.py
• platform/web/detect.py
• platform/windows/SCsub
• platform/windows/detect.py
• platform_methods.py
• scene/theme/default_theme_builders.py
• scene/theme/icons/SCsub
• scene/theme/icons/default_theme_icons_builders.py

本文档解释了 Godot 的构建系统，该系统使用 SCons 作为基础，并辅以自定义 Python 脚本来处理特定于平台的编译、模块集成和资源生成。有关为 Godot 贡献、设置开发环境或为特定平台编译的信息，请参阅官方文档。

概述

Godot 的构建系统旨在从单一代码库为多个平台编译引擎及其模块。它可以生成不同的构建目标（编辑器、调试模板、发布模板），并支持广泛的配置和优化。构建系统还负责生成引擎使用的各种资源和代码文件。

来源： SConstruct1-717 methods.py1-219 platform_methods.py1-162

构建系统组件

SConstruct

构建系统的主要入口点是存储库根目录下的 SConstruct 文件。该文件

1. 设置构建环境
2. 解析命令行选项
3. 检测可用平台
4. 配置特定于平台的设置
5. 检测并配置模块
6. 管理构建过程

来源： SConstruct1-57 SConstruct102-145 SConstruct183-268 SConstruct357-394 SConstruct427-501

Methods.py

此文件包含在整个构建过程中使用的辅助函数。关键函数包括

• add_source_files：将源文件添加到构建目标
• detect_modules：检测指定路径中的可用模块
• CommandNoCache：创建一个不使用 SCons 缓存的命令
• get_version_info：获取构建的版本信息
• detect_compiler_version：检测编译器版本
• module_check_dependencies：检查模块依赖项是否满足

这些函数简化了构建脚本，并提供了构建系统中跨使用的通用功能。

来源： methods.py33-83 methods.py234-294 methods.py332-356 methods.py138-159 methods.py651-770

平台检测

每个支持的平台在其平台目录中都有一个 detect.py 文件。这些文件提供了关于以下方面的信息

• 当前主机系统是否可以构建该平台
• 特定于平台的编译器和链接器标志
• 特定于平台的构建选项
• 特定于平台的库和依赖项

平台检测系统允许 Godot 使用相同的代码库在多个平台上进行构建和针对多个平台构建。

来源： platform/windows/detect.py18-172 platform/linuxbsd/detect.py12-72 platform/macos/detect.py12-67 platform/android/detect.py14-41 platform/ios/detect.py15-59 platform/web/detect.py15-90

平台配置

检测完平台后，构建系统会使用特定于平台的设置配置环境。每个平台的 detect.py 文件都有一个 configure 函数，该函数会设置构建所需的编译器、链接器和其他工具。

Windows 配置

在 Windows 上，构建系统可以使用 MSVC（Visual Studio）或 MinGW（GCC）工具链。它会配置

• 所选工具链的编译器和链接器标志
• 特定于 Windows 的库和依赖项
• 对不同渲染后端（OpenGL、Vulkan、DirectX）的支持

来源： platform/windows/detect.py286-564 platform/windows/detect.py636-747

LinuxBSD 配置

在 Linux 和 BSD 系统上，构建系统会配置

• GCC 或 Clang 编译器
• 系统库和依赖项
• X11、Wayland 和其他显示服务器支持
• 音频和输入系统支持

来源： platform/linuxbsd/detect.py74-474

macOS 配置

对于 macOS，构建系统会配置

• Apple Clang 编译器
• macOS 框架和库
• Metal 和 OpenGL 渲染支持
• x86_64 和 arm64 架构的通用二进制文件支持

来源： platform/macos/detect.py68-262

Android 配置

Android 构建使用以下内容配置

• Android NDK 工具链
• ARM 或 x86 架构支持
• Android 特定库和 API
• APK 生成设置

来源： platform/android/detect.py100-246

iOS 配置

iOS 构建使用以下内容配置

• iOS SDK 和工具链
• ARM64 或 x86_64（模拟器）架构
• iOS 特定框架和库
• App bundle 生成设置

来源： platform/ios/detect.py61-184

Web 配置

使用Emscripten的Web构建配置为

• Emscripten 编译器和链接器标志
• WebAssembly 目标设置
• JavaScript 集成选项
• WebGL 渲染支持

来源： platform/web/detect.py100-306

模块系统

Godot 的构建系统包含一个模块系统，允许通过附加功能来扩展引擎。模块可以是内置的（包含在 Godot 仓库中）或自定义的（独立于仓库）。

来源： methods.py234-294 methods.py297-304 modules/SCsub15-79

模块检测

模块在 modules 目录以及通过 custom_modules 选项指定的任何自定义路径中进行检测。模块必须包含

• 一个 register_types.h 文件：声明模块初始化和反初始化函数
• 一个 SCsub 文件：定义如何构建模块
• 一个 config.py 文件：包含模块配置选项和依赖项检查

来源： methods.py234-294 methods.py297-304 modules/SCsub15-79

模块配置

每个模块的 config.py 文件可以定义

• 模块的构建选项
• 模块是否默认启用
• 模块对其他模块的依赖项

构建系统会处理这些配置，并根据其依赖项和用户选项来启用或禁用模块。

来源： SConstruct402-430 methods.py319-356 SConstruct373-393

模块注册

构建系统会生成一个 register_module_types.gen.cpp 文件，该文件包含所有启用的模块，并调用它们的初始化和反初始化函数。这使得模块可以在运行时集成到引擎中。

来源： modules/SCsub31-76

构建目标

Godot 的构建系统支持三个主要的构建目标

1. 编辑器 (Editor)：包含所有编辑器功能的 Godot 编辑器
2. 模板调试 (Template Debug)：Godot 运行时的一个调试构建，不包含编辑器功能
3. 模板发布 (Template Release)：Godot 运行时的一个经过优化的发布构建

构建目标通过 target 选项指定，它会影响各种构建设置，包括优化、调试符号和包含的功能。

来源： SConstruct161-162 SConstruct474-503

构建配置

构建系统支持各种配置，这些配置可以与构建目标结合使用

• 调试功能 (Debug Features)：启用调试功能，例如详细日志和调试可视化
• 开发者构建 (Developer Build)：包含引擎开发者工具和功能
• 优化级别 (Optimization Level)：控制编译器优化（无、调试、速度、大小）
• 调试符号 (Debug Symbols)：包含用于崩溃报告和调试的调试符号

这些配置允许针对不同用例对构建进行精细调整。

来源： SConstruct442-503

资产生成

除了编译源代码之外，构建系统还生成引擎使用的各种资产和代码文件

• 图标 (Icons)：将 SVG 图标转换为 C++ 代码
• 翻译 (Translations)：处理编辑器的翻译文件和引擎
• 文档 (Documentation)：处理 XML 文档文件
• 着色器 (Shaders)：处理 GLSL 和 GLES3 着色器文件

这些生成的资产会包含在构建中，并提供引擎运行时所需的资源。

来源： editor/icons/SCsub1-24 editor/editor_builders.py12-96 gles3_builders.py8-103 glsl_builders.py8-96 main/main_builders.py6-42 core/core_builders.py9-28

命令行选项

构建系统提供了多种命令行选项来自定义构建。一些关键选项包括

选项	描述	默认
platform	目标平台 (windows, linuxbsd, macos, android, ios, web)	自动检测
target	编译目标 (editor, template_release, template_debug)	editor
arch	CPU 架构 (x86_32, x86_64, arm32, arm64 等)	自动检测
optimize	优化级别 (none, debug, speed, size)	基于 target
debug_symbols	包含调试符号	取决于 target
use_llvm	使用 LLVM/Clang 编译器	false
use_lto	使用链接时优化	none
tools	包含编辑器功能	true
tests	包含测试	false
custom_modules	自定义模块的路径	""

来源： SConstruct147-252

单编译单元 (SCU) 构建

Godot 的构建系统支持单编译单元 (SCU) 构建，它将多个源文件合并到一个编译单元中以提高构建时间。这由 scu_build 选项控制。

来源： methods.py23-83 SConstruct616-627

构建流程

整体构建流程遵循以下步骤

来源： SConstruct101-717

构建 Godot

构建 Godot 的典型过程是

1. 安装您平台所需的依赖项
2. 克隆 Godot 仓库
3. 使用所需的选项运行 SCons

4. 编译后的二进制文件将放置在 bin/ 目录中

例如，使用 MSVC 为 Windows 构建编辑器

或为 Android 构建发布模板

来源： SConstruct633

交叉编译

构建系统支持跨平台编译

• 使用 MinGW 从 Linux 构建 Windows
• 使用 OSXCROSS 从 Linux 构建 macOS
• 使用 OSXCROSS 从 Linux 构建 iOS
• 从任何主机平台构建 Android

交叉编译需要针对目标平台的额外设置和依赖项。

来源： platform/windows/detect.py47-59 platform/macos/detect.py76-137 platform/ios/detect.py85-137 platform/android/detect.py112-176

结论

Godot 的构建系统是一个基于 SCons 的复杂设置，它处理了构建跨平台游戏引擎的复杂性，支持多种配置和目标。它提供了一种灵活而强大的方式来定制构建过程，同时保持跨多种平台和体系结构的兼容性。