Introduction to the buildsystem

SCons

Godot usa SCons para construir. Nós o amamos, não iremos trocá-lo por mais nada. Nem mesmo temos certeza se outros sistemas de construção estão à altura da tarefa de construir o Godot. Constantemente recebemos solicitações para mover o sistema de compilação para CMake ou Visual Studio, mas isto não vai acontecer. Existem muitos motivos pelos quais escolhemos SCons em vez de outras alternativas, por exemplo:

• Godot pode ser compilado para uma dúzia de plataformas diferentes: todas as plataformas de PC, todas as plataformas móveis, muitos consoles e WebAssembly.

• Os desenvolvedores geralmente precisam compilar para várias plataformas ao mesmo tempo, ou até mesmo destinos diferentes da mesma plataforma. Eles não podem se dar ao luxo de reconfigurar e reconstruir o projeto todas as vezes. SCons pode fazer isso sem suor, sem quebrar as compilações.

• 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.

Configurar

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

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.

Seleção de plataforma

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
    server
    windows
    x11

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

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

scons platform=x11

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=x11 -j 4

Resulting binary

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

godot.<platform>.[opt].[tools/debug].<architecture>[extension]

Para a tentativa de compilação anterior, o resultado ficaria assim:

ls bin
bin/godot.x11.tools.64

This means that the binary is for X11, is not optimized, has tools (the whole editor) compiled in, and is meant for 64 bits.

Um binário do Windows com a mesma configuração terá esta aparência:

C:\godot> dir bin/
godot.windows.tools.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.

Ferramentas

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

scons platform=<platform> tools=yes/no

Alvo

Target controls optimization and debug flags. Each mode means:

• debug: Build with C++ debugging symbols, runtime checks (performs checks and reports error) and none to little optimization.

• release_debug: Build without C++ debugging symbols and optimization, but keep the runtime checks (performs checks and reports errors). Official editor binaries use this configuration.

• release: Build without symbols, with optimization and with little to no runtime checks. This target can't be used together with tools=yes, as the editor requires some debug functionality and run-time checks to run.

scons platform=<platform> target=debug/release_debug/release

This flag appends the .debug suffix (for debug), or .tools (for debug with tools enabled). When optimization is enabled (release), it appends the .opt suffix.

Bits

Bits destina-se a controlar a versão da CPU ou do sistema operacional destinada a executar os binários. Ele é focado principalmente em plataformas de desktop e ignorado em qualquer outro lugar.

• 32: Compilar binários para plataformas de 32 bits.

• 64: Compilar binários para plataformas de 64 bits.

• default: Compilar para a arquitetura que corresponde à plataforma do host.

scons platform=<platform> bits=default/32/64

This flag appends .32 or .64 suffixes to resulting binaries when relevant. If bits=default is used, the suffix will match the detected architecture.

Módulos personalizados

It's possible to compile modules residing outside of Godot's directory tree, along with the built-in modules.

A custom_modules build option can be passed to the command line before compiling. The option represents a comma-separated list of directory paths containing a collection of independent C++ modules that can be seen as C++ packages, just like the built-in modules/ directory.

For instance, it's possible to provide both relative, absolute, and user directory paths containing such modules:

scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules"

Nota

If there's any custom module with the exact directory name as a built-in module, the engine will only compile the custom one. This logic can be used to override built-in module implementations.

Ver também

Módulos personalizados em C++

Limpando arquivos gerados

Sometimes, you may encounter an error due to generated files being present. You can remove them by using scons --clean <options>, where <options> is the list of build options you've used to build Godot previously.

Alternatively, you can use git clean -fixd which will clean build artifacts for all platforms and configurations. Beware, as this will remove all untracked and ignored files in the repository. Don't run this command if you have uncommitted work!

Other build options

There are several other build options that you can use to configure the way Godot should be built (compiler, debug options, etc.) as well as the features to include/disable.

Check the output of scons --help for details about each option for the version you are willing to compile.

Sobrescrevendo as opções de compilação

Usando um arquivo

The default custom.py file can be created at the root of the Godot Engine source to initialize any SCons build options passed via the command line:

# custom.py

optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"

Você também pode desativar alguns dos módulos embutidos antes de compilar, economizando algum tempo para construir a engine. Veja a página ref:doc_optimizing_for_size para mais detalhes.

Ver também

You can use the online Godot build options generator to generate a custom.py file containing SCons options. You can then save this file and place it at the root of your Godot source directory.

Another custom file can be specified explicitly with the profile command line option, both overriding the default build configuration:

scons profile=path/to/custom.py

Nota

Build options set from the file can be overridden by the command line options.

It's also possible to override the options conditionally:

# custom.py

import version

# Override options specific for Godot 3.x and 4.x versions.
if version.major == 3:
    pass
elif version.major == 4:
    pass

Usando o SCONSFLAGS

SCONSFLAGS is an environment variable which is used by the SCons to set the options automatically without having to supply them via the command line.

For instance, you may want to force a number of CPU threads with the aforementioned -j option for all future builds:

Linux/macOSWindows (cmd)Windows (powershell)

export SCONSFLAGS="-j4"

Modelos de exportação

Official export templates are downloaded from the Godot Engine site: godotengine.org. However, you might want to build them yourself (in case you want newer ones, you are using custom modules, or simply don't trust your own shadow).

If you download the official export templates package and unzip it, you will notice that most files are optimized binaries or packages for each platform:

android_debug.apk
android_release.apk
webassembly_debug.zip
webassembly_release.zip
linux_server_32
linux_server_64
linux_x11_32_debug
linux_x11_32_release
linux_x11_64_debug
linux_x11_64_release
osx.zip
version.txt
windows_32_debug.exe
windows_32_release.exe
windows_64_debug.exe
windows_64_release.exe

To create those yourself, follow the instructions detailed for each platform in this same tutorial section. Each platform explains how to create its own template.

The version.txt file should contain the corresponding Godot version identifier. This file is used to install export templates in a version-specific directory to avoid conflicts. For instance, if you are building export templates for Godot 3.1.1, version.txt should contain 3.1.1.stable on the first line (and nothing else). This version identifier is based on the major, minor, patch (if present) and status lines of the version.py file in the Godot Git repository.

If you are developing for multiple platforms, macOS is definitely the most convenient host platform for cross-compilation, since you can cross-compile for almost every target (except for UWP). Linux and Windows come in second place, but Linux has the advantage of being the easier platform to set this up.