This page documents how Godot's build system identifies target platforms and configures compiler, linker flags, and libraries for each target platform. It covers the platform-specific detect.py scripts located in the platform/*/ subdirectories and their integration in the main SConstruct build script. The page explains the standardized interface that every platform must expose, details of per-platform implementations, architecture detection utilities, and how these configurations flow through the build environment setup.
For context on the overall build system and global build options, see Build Configuration. For integration with Godot modules, see Module System.
Godot supports multiple target platforms, each represented by a subfolder under the platform/ directory e.g.:
| Platform Name | Directory | Description |
|---|---|---|
| Windows | platform/windows/ | Native MSVC or cross-compile with MinGW |
| LinuxBSD | platform/linuxbsd/ | Linux and BSD variants |
| macOS | platform/macos/ | Native macOS or cross-compilation (OSXCROSS) |
| Android | platform/android/ | Android SDK/NDK-based builds |
| Web | platform/web/ | Emscripten (WebAssembly) target |
Each platform folder contains a detect.py, which provides discovery and configuration functions called by SConstruct. The main build script dynamically loads these detecting modules to learn what platforms are buildable on the current host environment, what options they provide, and how to configure the SCons environment (env) for compilation and linking.
The detection process happens in two passes:
can_build() and gather options/configuration defaults.get_tools() and configure(env) functions to set up toolchains, compiler flags, linker flags, and libraries.This modular approach isolates platform-specific build logic in each platform folder, enabling easy maintenance and expansion.
Sources: SConstruct77-109 platform/windows/detect.py19-20 platform/linuxbsd/detect.py14-15 platform/macos/detect.py16-17 platform/android/detect.py14-15 platform/web/detect.py25-26
detect.py InterfaceEvery platform's detect.py implements a defined interface that SConstruct expects. This allows uniform querying of platform capabilities and configuration without hardcoding platform logic in the main build script.
| Function | Return Type | Purpose | Example Location |
|---|---|---|---|
get_name() | str | Human-readable platform name | platform/windows/detect.py19-20 |
can_build() | bool | Whether this platform can be built on host | platform/android/detect.py18-19 |
get_opts() | list | List of SCons Variables for platform options | platform/linuxbsd/detect.py29-76 |
get_flags() | dict | Platform flag defaults (e.g. arch, target) | platform/web/detect.py78-94 |
configure(env) | None | Configures the SCons environment env | platform/macos/detect.py95-280 |
| Function | Return Type | Purpose | Example Location |
|---|---|---|---|
get_tools(env) | list[str] | List of SCons build tools to add (e.g. msvc) | platform/windows/detect.py175-198 |
get_doc_classes() | list[str] | Export class names for editor documentation | platform/android/detect.py46-49 |
get_doc_path() | str | Relative path to documentation XML files | platform/android/detect.py52-53 |
SConstructSources: SConstruct77-109 SConstruct499-509
SConstruct Loads PlatformsSConstruct scans all folders in platform/ and attempts to import detect.py from each. It queries if the platform can build on the host (can_build()), its build options (get_opts()), flags (get_flags()), and documentation class info. Platforms that cannot build are skipped.
This populates:
platform_list: List of buildable platforms.platform_opts: Option Variables per platform.platform_flags: Default build flags per platform.platform_doc_class_path: Documentation class paths per platform.This occurs at lines SConstruct77-109
If no platform argument is specified to scons, SConstruct infers platform from sys.platform:
This auto-selection is at SConstruct376-392
Old platform names can be passed via arguments, and SConstruct normalizes them to current names using compatibility_platform_aliases defined in platform_methods.py.
| Old Name | Current Name |
|---|---|
osx | macos |
iphone | ios |
x11 | linuxbsd |
javascript | web |
This mapping is at platform_methods.py62 and applied in SConstruct394-405
Once the target platform is selected, SConstruct reloads its detect.py to call get_tools(env) and loads those SCons tools into the environment. Then it calls configure(env) to mutate the environment with platform-specific compilers, compiler flags, linker flags, and libraries.
Sources: SConstruct499-509 SConstruct694
All platforms use utilities in platform_methods.py to consistently detect and validate architectures.
detect_arch()platform.machine() at runtime.architecture_aliases dictionary.| Canonical Architecture | Aliases |
|---|---|
x86_32 | x86, i386, i486, i586, i686 |
x86_64 | amd64, x64 |
arm32 | armv7, armv7a, arm |
arm64 | armv8, aarch64 |
rv64 | riscv, riscv64 |
validate_arch(arch, platform_name, supported_arches)configure(env) to verify requested architecture is valid.print_error.Sources: platform_methods.py18-57 SConstruct167 platform/linuxbsd/detect.py98-99
configure(env) DetailsEach platform's configure() function mutates the SCons environment by:
CC, CXX, AR, LINK, AS, RANLIB).CCFLAGS).LINKFLAGS).LIBS).CPPDEFINES).Example platform-configure call graph:
Sources:
can_build() is true for native (os.name == "nt") or if a mingw cross-compiler is detected on POSIX platform/windows/detect.py49-61get_tools(env) returns either:
["msvc", "mslink", "mslib"] for Visual Studio native builds.["mingw"] for cross-compile or MinGW builds platform/windows/detect.py175-198configure(env) selectively configures:
/MD or /MT.winmm, dsound, kernel32, ole32, user32, gdi32, shlwapi, ws2_32.lto=auto resolves to either thin (Clang) or full (GCC).Sources: platform/windows/detect.py243-519
pkg-config platform/linuxbsd/detect.py17-26use_llvm, linker selection (bfd, gold, lld, mold), sanitizers (ubsan, asan, etc.), X11 and Wayland support, ALSA, PulseAudio platform/linuxbsd/detect.py29-76pkg-config to detect and append system libraries and header paths for components like fontconfig, dbus, and alsa.Sources: platform/linuxbsd/detect.py96-530
OSXCROSS_ROOT or APPLE_LLVM_CROSS platform/macos/detect.py20-24configure(env) sets:
clang) paths or OSXCROSS binaries.arm64 (macOS 13.0+) or x86_64 (macOS 11.0+).Cocoa, Metal, AudioToolbox, IOKit, CoreAudio, CoreGraphics.-ld_classic platform/macos/detect.py126-128Sources: platform/macos/detect.py95-280
ANDROID_HOME or ANDROID_SDK_ROOT platform/android/detect.py57-58configure(env):
29.0.14206865), downloads it using sdkmanager if needed platform/android/detect.py70-98clang toolchain corresponding to target architecture triples (e.g., aarch64-linux-android).-fpic, -ffunction-sections, -fstack-protector-strong.OpenSLES, android, log.Sources: platform/android/detect.py132-244
can_build() checks presence of emcc on PATH platform/web/detect.py29-30configure(env):
emcc (CC), em++ (CXX), emar (AR), emranlib (RANLIB).>= 4.0.0).INITIAL_MEMORY, stack_size, threads.-Os optimization by default for smaller builds platform/web/detect.py93_main platform/web/detect.py123Sources: platform/web/detect.py105-353
Sources: SConstruct77-109 SConstruct374-433 SConstruct499-509 SConstruct694
Godot's platform detection system modularizes build infrastructure per platform via standardized detect.py scripts. These scripts guard for host compatibility (can_build()), expose custom build options, set default compilation flags, and configure the build environment with platform-specific toolchains, compiler/linker flags, libraries, and defines.
The main SConstruct orchestrates scanning all platform scripts, detecting the suitable platform, applying options and flags, and finalizing the compiler environment by invoking the chosen platform's configure() function. Architecture detection and validation ensure consistent naming and support checks across all platforms.
Sources: SConstruct77-109 platform_methods.py1-63 methods.py114-130
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.