Build System

Relevant source files

• SConstruct
• core/SCsub
• drivers/SCsub
• drivers/register_driver_types.cpp
• editor/SCsub
• editor/icons/SCsub
• main/SCsub
• methods.py
• modules/SCsub
• modules/gdscript/editor/script_templates/SCsub
• modules/modules_builders.py
• 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/visionos/detect.py
• platform/web/detect.py
• platform/windows/SCsub
• platform/windows/detect.py
• platform_methods.py
• scene/theme/icons/SCsub

This page documents Godot's SCons-based build system: its entry point, platform scanning, build options, module discovery, and the compilation hierarchy through SCsub scripts. For deeper technical details, see the child pages:

• Build Configuration — SConstruct entry point, methods.py utilities, build options, and compiler setup;
• Platform Detection — platform-specific detection scripts (detect.py), compiler, linker, and flags configuration;
• Module System — module discovery, detection, SCsub build scripts, and dependencies;
• CI/CD and Static Checks — continuous integration workflows, static analysis, and test infrastructure.

---

Overview

Godot uses the SCons build system to orchestrate multi-platform and multi-configuration compilation. The entire build process is controlled by a single root SConstruct script. Key roles of SConstruct include:

1. Loading internal helper modules such as methods.py, platform_methods.py, and others, which provide build utility functions and environment extensions SConstruct25-54
2. Scanning all subdirectories under platform/ for presence of detect.py which identifies supported build platforms and provides platform-specific options and build configuration SConstruct77-109
3. Defining and parsing configurable build options (architecture, target type, optimization settings, etc.), including user overrides via custom.py or specified build profiles SConstruct149-187
4. Detecting built-in and custom modules, integrating their configuration options and source files.
5. Setting up the SCons environment by selecting appropriate build tools, flags, and environment variables guided by the platform-specific configure() functions SConstruct115-140
6. Delegating compilation tasks to a hierarchy of SCsub scripts found under directories such as core/, drivers/, scene/, editor/, modules/, and main/.
7. Linking the final executable (or library) into the bin/ directory with platform, target, and architecture-specific naming methods.py87-112

Godot's build system targets SCons 4.4 and Python 3.9 or newer as minimum requirements SConstruct4-5

Sources: SConstruct1-115 SConstruct149-200 methods.py87-112

---

Build Invocation Summary

A typical build command is:

• The platform option selects the OS and hardware target (e.g., linuxbsd, windows, android, web) SConstruct161
• The target chooses the build type, commonly SConstruct162-166:
  • editor - full editor build with debug tools enabled;
  • template_release - optimized export template without debug code;
  • template_debug - debug export template.

The SConstruct script autodetects platforms by scanning each platform/* directory and loading its detect.py which implements:

• can_build(): returns if the current host supports building for that platform platform/windows/detect.py49-61
• get_opts(): platform-specific build option definitions platform/linuxbsd/detect.py29-76
• get_tools(): compilers and linkers to enable platform/web/detect.py33-35
• configure(env): environment setup for compiler flags and toolchain paths platform/android/detect.py132-216

These are invoked automatically during build initialization SConstruct77-109

Sources: SConstruct77-109 SConstruct160-187 platform/windows/detect.py49-198 platform/android/detect.py18-216 platform/web/detect.py29-172

---

Build Flow Diagram

Sources: SConstruct25-109 SConstruct158-187 methods.py1-84

---

Environment Setup and Extensions

Godot configures a root SCons environment with no default tools to avoid unwanted assumptions about the build host SConstruct115 It adds Godot-specific methods directly onto env:

Method	Purpose	Location
add_source_files(files)	Add source files (with SCU support) to compile in env	methods.py79-84
add_library(name, sources)	Define a static library target	SConstruct132
add_shared_library(name, sources)	Define a shared library target	SConstruct131
add_program(name, sources)	Define a program/executable target	SConstruct133
disable_warnings()	Disable warnings for a given env	methods.py114-119
force_optimization_on_debug()	Force optimizations even on debug target	methods.py122-130
CommandNoCache()	Define commands that skip scons cache	SConstruct134

This extended environment API simplifies writing build logic in SCsub files and module config files. Object files and libraries are emitted into bin/obj/ via redirect_emitter to cleanly separate generated build files from source code methods.py87-112

Sources: SConstruct115-139 methods.py79-130

---

Platform Detection and Configuration

Each target platform must supply a platform/<platform>/detect.py file. At startup, SConstruct imports each detect.py and calls can_build() to assemble the list of available platforms SConstruct77-109

For example:

• Windows: supports native build with MSVC or cross-build with MinGW-w64 platform/windows/detect.py175-198
• Android: requires ANDROID_HOME and the NDK; sets cross compilation toolchain paths and compiler flags platform/android/detect.py57-201
• LinuxBSD: detects POSIX hosts with pkg-config; supports clang/gcc and sanitizers platform/linuxbsd/detect.py18-175
• Web: uses the Emscripten toolchain with emcc and specialized WASM configuration platform/web/detect.py105-162

Diagram: Platform Detection Code Relationships

Sources: SConstruct77-109 platform/windows/detect.py19-198 platform/android/detect.py14-216 platform/linuxbsd/detect.py13-94 platform/web/detect.py25-172

---

Module System and SCsub Compilation Hierarchy

Godot's codebase is modularized. Each component provides an SCsub script defining compilation. The build system uses multiple SCsub scripts at various levels:

• core/SCsub: Compiles core engine units and bundled thirdparty code like zlib or zstd core/SCsub83-165
• drivers/SCsub: Orchestrates audio, input, and rendering drivers (Vulkan, GLES3, etc.) drivers/SCsub11-70
• editor/SCsub: Compiles the editor application, including translations and icons editor/SCsub12-101
• platform/<name>/SCsub: Platform-specific source compilation and final linking platform/windows/SCsub15-119

Diagram: Module and Compilation Dependency Flow

Sources: platform/windows/SCsub13-119 platform/android/SCsub13-51 editor/SCsub4-103 core/SCsub12-165 drivers/SCsub8-75

---

Build Options Reference (Highlights)

Godot defines many build options via SCons Variables SConstruct158-187

Option	Default	Description
platform (p)	-	Target platform (auto-discovered)
target	editor	Build target: editor, template_release, template_debug
arch	auto	CPU architecture (x86_64, arm64, wasm32, etc.)
dev_build	False	Enable development/debugging code (DEV_ENABLED)
optimize	auto	Optimization level: none, debug, speed, size, etc.
lto	none	Link-time optimization: none, auto, thin, full
scu_build	False	Use Single Compilation Unit build for faster builds methods.py55-74

Sources: SConstruct160-187 methods.py55-74 platform/android/detect.py20-142 platform/windows/detect.py201-210

---

Build Output

• The final binary is placed into the bin/ directory.
• Object files are redirected under bin/obj/ methods.py87-112
• Platform-specific post-build steps (e.g., creating APKs for Android or APP bundles for macOS) are triggered by SCsub commands platform/android/SCsub113-118 platform/macos/detect.py72

Sources: methods.py87-112 platform/windows/SCsub114-120 platform/android/SCsub51-119

---

Summary Diagram: Natural Language to Code Entity Space Mapping

Sources: SConstruct25-109 methods.py1-84 platform/windows/detect.py19-198 platform/android/detect.py14-216 core/SCsub drivers/SCsub editor/SCsub

---

Further Reading

• Build Configuration — Explains the root build script details and build targets.
• Platform Detection — In-depth coverage of each platform's detection scripts.
• Module System — Details about module detection and dependency management.
• CI/CD and Static Checks — Overview of continuous integration workflows and test infrastructure.

Sources: SConstruct1-187 methods.py1-130 platform/windows/detect.py19-198 platform/android/detect.py14-216 platform/linuxbsd/detect.py13-94 platform/web/detect.py25-172 platform/windows/SCsub13-119 platform/android/SCsub13-119 editor/SCsub4-103