Skip to content

Build With Scons

Jump to bottom
George L. Albany edited this page Mar 27, 2026 · 30 revisions

Note

Run commands in the project's root directory.

Quick Commands

Command Description
scons Builds the project as an editor target for the native platform with as many threads as cores minus 1, e.g. If you have 12 cores, it builds with 11 threads.
scons compiledb=yes compiledb Builds the project's compilation database without building the whole project, recommended to run if you added, removed, or moved any source files, see compiledb.
scons compiledb=yes Builds the project's compilation database alongside building the whole project as an editor target for the native platform, see compiledb.
scons dev_build=yes Builds the project as an editor target for the native platform with debugger support, see dev_build.
scons -c Cleans/Deletes the project's build files.
scons target=template_release Builds the project as a template_release target, ready for release export in Godot. This does not build for running in the Godot Editor.
scons target=template_debug Builds the project as a template_debug target, ready for debug export in Godot. This does not build for running in the Godot Editor.
scons --help Lists out all build options, may include options inaccessible at root found in submodules.

Build Options

Option Values Platform Description
dev_build yes, no (default) All Whether to build debugger flags. e.g. Enables the use of breakpoints when a debugger is active.
debug_symbols yes, no (default) All Whether to build debug symbols.
platform linux, macos, windows All The target platform to build the GDExtension for. Default value is the detected native platform.
target editor (default), template_release, template_debug All The type of build the GDExtension is built for, editor is needed to run the project from the Godot Editor meaning any case that you have not exported the game, see Run With Godot. Template targets are meant only for exporting with release and debug Godot templates respectively.
arch universal, x86_32, x86_64, arm32, arm64, rv64, ppc32, ppc64, wasm32 All The type of architecture to build for. Default value depends on platform and native architecture.
lto auto (default), none, thin, full All

Link-Time Optimization:

  • auto:

    • If Linux or use_llvm=yes or use_mingw=yes on Windows then becomes full
    • Else becomes none

  • none - Disables Link-Time Optimization

  • thin - Only available if use_llvm=yes, see ThinLTO

  • full - Full Link-Time Optimization
optimize auto (default), none, custom, debug, speed, speed_trace, size All

Optimization level:

  • auto:

  • none - Disables optimization, on MSVC builds with /Od, else builds with -O0

  • custom

  • debug - On MSVC builds with /Od, else builds with -Od

  • speed - On MSVC builds with /O2 and links with /OPT:REF, else builds with -O3

  • speed_trace - On MSVC builds with /O2 and links with /OPT:REF and /OPT:NOICF, else builds with -O2

  • size - On MSVC builds with /O1 and links with /OPT:REF and /OPT:NOICF, else builds with -Os
harden_memory auto (default), none, fast All

The level of memory hardening that should be used:

  • auto:

  • none - Disables memory hardening

  • fast - Enables a set of performant options for memory hardening, e.g. out-of-bounds memory access will crash for standard library classes
compiledb yes, no (default) All Whether to generate compilation DB (compile_commands.json) for external tools. See clangd's Compile Commands and Clang's JSON Compilation Database Format Specification for details.
compiledb_file All Path to a custom compile_commands.json file.
use_hot_reload yes, no All Whether the build accounts for potential hot reloading of the GDExtension while Godot is running. Defaults to no if target is template_release, else defaults to yes.
use_ubsan yes, no (default) Linux, Mac Whether the project is built with Undefined Behavior Sanitizer.
use_asan yes, no (default) All Whether the project is built with Address Sanitizer.
use_tsan yes, no (default) Linux, Mac Whether the project is built with Thread Sanitizer.
use_msan yes, no (default) Linux Whether the project is built with Memory Sanitizer.
use_lsan yes, no (default) Linux Whether the project is built with Leak Sanitizer.
use_llvm yes, no (default) Linux, Windows Whether the project is built using LLVM or not.
use_static_cpp yes, no (default) Linux, Windows Whether the project is built linking the C++ standard library statically.
verbose yes, no (default) All Whether the project is built with verbose build output.

Clone this wiki locally