Work in progress

Godot documentation is being updated to reflect the latest changes in version 4.0. Some documentation pages may still state outdated information. This banner will tell you if you're reading one of such pages.

The contents of this page are up to date. If you can still find outdated information, please open an issue.

Introduction to the buildsystem

SCons

Godot uses SCons to build. We love it, we are not changing it for anything else. We are not even sure other build systems are up to the task of building Godot. We constantly get requests to move the build system to CMake, or Visual Studio, but this is not going to happen. There are many reasons why we have chosen SCons over other alternatives, for example:

  • Godot can be compiled for a dozen different platforms: all PC platforms, all mobile platforms, many consoles, and WebAssembly.

  • Developers often need to compile for several of the platforms at the same time, or even different targets of the same platform. They can't afford reconfiguring and rebuilding the project each time. SCons can do this with no sweat, without breaking the builds.

  • SCons will never break a build no matter how many changes, configurations, additions, removals etc. You have more chances to die struck by lightning than needing to clean and rebuild in SCons.

  • Godot build process is not simple. Several files are generated by code (binders), others are parsed (shaders), and others need to offer customization (plugins). This requires complex logic which is easier to write in an actual programming language (like Python) rather than using a mostly macro-based language only meant for building.

  • Godot build process makes heavy use of cross-compiling tools. Each platform has a specific detection process, and all these must be handled as specific cases with special code written for each.

So, please try to keep an open mind and get at least a little familiar with it if you are planning to build Godot yourself.

Setup

Please refer to the documentation for Compiling for Android, Compiling for iOS, Compiling for Linux, *BSD, Compiling for macOS, Compiling for Universal Windows Platform, Compiling for the Web, and Compiling for Windows.

Note that for Windows/Visual Studio, you need to use x86_x64 Cross Tools Command Prompt for VS 2017 or similar, depending on your install, instead of the standard Windows command prompt to enter the commands below.

Platform selection

Godot's build system will begin by detecting the platforms it can build for. If not detected, the platform will simply not appear on the list of available platforms. The build requirements for each platform are described in the rest of this tutorial section.

SCons is invoked by just calling scons. If no platform is specified, SCons will detect the target platform automatically based on the host platform. It will then start building for the target platform right away.

To list the available target platforms, use scons platform=list:

scons platform=list
scons: Reading SConscript files ...
The following platforms are available:

    android
    javascript
    linuxbsd
    server
    windows

Please run SCons again and select a valid platform: platform=<string>

To build for a platform (for example, linuxbsd), run with the platform= (or p= to make it short) argument:

scons platform=linuxbsd

This will start the build process, which will take a while. By default, Godot's SCons setup is configured to use all CPU threads but one (to keep the system responsive during compilation). If you want to adjust how many CPU threads SCons will use, use the -j <threads> parameter to specify how many threads will be used for the build.

Example for using 4 threads:

scons platform=linuxbsd -j4

Resulting binary

The resulting binaries will be placed in the bin/ subdirectory, generally with this naming convention:

godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]

For the previous build attempt, the result would look like this:

ls bin
bin/godot.linuxbsd.editor.x86_64

This means that the binary is for Linux or *BSD (not both), is not optimized, has the whole editor compiled in, and is meant for 64 bits.

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

C:\godot> dir bin/
godot.windows.editor.64.exe

Copy that binary to any location you like, as it contains the project manager, editor and all means to execute the game. However, it lacks the data to export it to the different platforms. For that the export templates are needed (which can be either downloaded from godotengine.org, or you can build them yourself).

Aside from that, there are a few standard options that can be set in all build targets, and which will be explained below.

Target

Target controls if the editor is contained and debug flags are used. All builds are optimized. Each mode means:

  • editor: Build with editor, optimized, with debugging code (defines: TOOLS_ENABLED, DEBUG_ENABLED, -O2//O2)

  • template_debug: Build with C++ debugging symbols (defines: DEBUG_ENABLED, -O2//O2)

  • template_release: Build without symbols (defines: -O3//O2)

The editor is enabled by default in all PC targets (Linux, Windows, macOS), disabled for everything else. Disabling the editor produces a binary that can run projects but that does not include the editor or the project manager.

scons platform=<platform> target=editor/template_debug/template_release

Dev build

When doing engine development the dev_build option can be used together with target to enable dev-specific code. dev_build defines DEV_ENABLED, disables optimization (-O0//0d), enables generating debug symbols, and does not define NDEBUG (so assert() works in thirdparty libraries).

scons platform=<platform> dev_build=yes

This flag appends the .dev suffix (for development) to the generated binary name.

Architecture

The arch option is meant to control the CPU or OS version intended to run the binaries. It is focused mostly on desktop platforms and ignored everywhere else.

Supported values for the arch option are auto, x86_32, x86_64, arm32, arm64, rv64, ppc32, ppc64 and wasm32.

scons platform