Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
Introduction au buildsystem¶
Godot is a primarily C++ project and it uses the SCons build system. We love SCons for how maintainable and easy to set up it makes our buildsystem. And thanks to that compiling Godot from source can be as simple as running:
scons
This produces an export template for your current platform, operating system, and architecture. An export template is a build of the engine that is used for running exported projects. To build the editor instead you can run the following command:
scons target=editor
If you plan to debug or develop the engine, then you might want to add another option to the command:
scons dev_build=yes
scons target=editor dev_build=yes
Following sections in the article will explain these and other universal options in more detail. But before you can compile Godot, you need to install a few prerequisites. Please refer to the platform documentation to learn more:
These articles cover in great detail both how to setup your environment to compile Godot on a specific platform, and how to compile for that platform. Please feel free to go back and forth between them and this article to reference platform-specific and universal configuration options.
Using multi-threading¶
The build process may take a while, depending on how powerful your system is. 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 -j4
Choix de la plate-forme¶
Le système de construction(build) de Godot commencera par détecter les plateformes pour lesquelles il peut construire(build). Si elle n'est pas détectée, la plate-forme n'apparaîtra tout simplement pas dans la liste des plates-formes disponibles. Les exigences de construction(build) pour chaque plateforme sont décrites dans la suite de ce tutoriel.
SCons est invoqué en appelant simplement scons
. Si aucune plate-forme n'est spécifiée, SCons détectera automatiquement la plate-forme cible en fonction de la plate-forme hôte. Il commencera alors immédiatement à construire pour la plate-forme cible.
Pour lister les plates-formes cibles disponibles, utilisez 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
Binaire résultant¶
Les binaires résultants seront placés dans le sous-répertoire bin/
, généralement avec cette convention de nommage :
godot.<platform>.<target>[.dev][.double].<arch>[.<extra_suffix>][.<ext>]
Pour la précédente tentative de compilation, le résultat serait le suivant :
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.
Un binaire Windows avec la même configuration ressemblera à ceci :
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).
En dehors de cela, il y a quelques options standard qui peuvent être définies dans toutes les cibles de build, et qui seront expliquées ci-dessous.
Cible¶
Target controls if the editor is contained and debug flags are used. All builds are optimized. Each mode means:
target=editor
: Build with editor, optimized, with debugging code (defines:TOOLS_ENABLED
,DEBUG_ENABLED
,-O2
//O2
)target=template_debug
: Build with C++ debugging symbols (defines:DEBUG_ENABLED
,-O2
//O2
)target=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 does not include the editor or the Project Manager.
scons platform=<platform> target=editor/template_debug/template_release
Development and production aliases¶
When creating builds for development (running debugging/profiling tools), you often have different goals compared to production builds (making binaries as fast and small as possible).
Godot provides two aliases for this purpose:
dev_mode=yes
is an alias forverbose=yes warnings=extra werror=yes tests=yes
. This enables warnings-as-errors behavior (similar to Godot's continuous integration setup) and also builds unit tests so you can run them locally.production=yes
is an alias foruse_static_cpp=yes debug_symbols=no lto=auto
. Statically linking libstdc++ allows for better binary portability when compiling for Linux. This alias also enables link-time optimization when compiling for Linux, Web and Windows with MinGW, but keeps LTO disabled when compiling for macOS, iOS or Windows with MSVC. This is because LTO on those platforms is very slow to link or has issues with the generated code.
You can manually override options from those aliases by specifying them on the
same command line with different values. For example, you can use scons
production=yes debug_symbols=yes
to create production-optimized binaries with
debugging symbols included.
Dev build¶
Note
dev_build
should not be confused with dev_mode
, which is an
alias for several development-related options (see above).
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.
Voir aussi
There are additional SCons options to enable sanitizers, which are tools you can enable at compile-time to better debug certain engine issues. See Using sanitizers for more information.
Debugging symbols¶
By default, debug_symbols=no
is used, which means no debugging symbols
are included in compiled binaries. Use debug_symbols=yes
to include debug
symbols within compiled binaries, which allows debuggers and profilers to work
correctly. Debugging symbols are also required for Godot's crash stacktraces to
display with references to source code files and lines.
The downside is that debugging symbols are large files (significantly larger than the binaries themselves). As a result, official binaries currently do not include debugging symbols. This means you need to compile Godot yourself to have access to debugging symbols.
When using debug_symbols=yes
, you can also use
separate_debug_symbols=yes
to put debug information in a separate file with
a .debug
suffix. This allows distributing both files independently. Note
that on Windows, when compiling with MSVC, debugging information is always
written to a separate .pdb
file regardless of separate_debug_symbols
.
Astuce
Use the strip <path/to/binary>
command to remove debugging symbols from
a binary you've already compiled.
Optimization level¶
Several compiler optimization levels can be chosen from:
optimize=speed_trace
(default when targeting non-Web platforms): Favors execution speed at the cost of larger binary size. Optimizations may sometimes negatively impact debugger usage (stack traces may be less accurate. If this occurs to you, useoptimize=debug
instead.optimize=speed
: Favors even more execution speed, at the cost of even larger binary size compared tooptimize=speed_trace
. Even less friendly to debugging compared tooptimize=debug
, as this uses the most aggressive optimizations available.optimize=size
(default when targeting the Web platform): Favors small binaries at the cost of slower execution speed.optimize=debug
: Only enables optimizations that do not impact debugging in any way. This results in faster binaries thanoptimize=none
, but slower binaries thanoptimize=speed_trace
.optimize=none
: Do not perform any optimization. This provides the fastest build times, but the slowest execution times.optimize=custom
(advanced users only): Do not pass optimization arguments to the C/C++ compilers. You will have to pass arguments manually using theCFLAGS
,CCFLAGS
andCXXFLAGS
SCons options.
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=<platform> arch={auto|x86_32|x86_64|arm32|arm64|rv64|ppc32|ppc64|wasm32}
This flag appends the value of arch
to resulting binaries when
relevant. The default value arch=auto
detects the architecture
that matches the host platform.
Modules personnalisées¶
Il est possible de compiler des modules résidant à l’extérieur de l’arbre de répertoire de Godot, en même temps que les modules intégrés.
Une option de compilation custom_modules
peut être passée à la ligne de commande avant la compilation. L'option représente une liste de chemins de répertoire séparés par des virgules contenant une collection de modules C++ indépendants qui peuvent être considérés comme des paquets C++, tout comme le répertoire intégré modules/
.
Par exemple, il est possible de fournir à la fois des chemins d'accès relatifs, absolus et des répertoires utilisateurs contenant de tels modules :
scons custom_modules="../modules,/abs/path/to/modules,~/src/godot_modules"
Note
S'il existe un module personnalisé avec le nom exact du répertoire comme module intégré, le moteur ne compilera que le module personnalisé. Cette logique peut être utilisée pour passer outre les implémentations de modules intégrés.
Voir aussi
Nettoyage des fichiers générés¶
Parfois, vous pouvez rencontrer une erreur due à la présence de fichiers générés. Vous pouvez les supprimer en utilisant scons --clean <options>
, où <options>
est la liste des options de compilation que vous avez utilisées pour compiler Godot précédemment.
Vous pouvez aussi utiliser git clean -fixd
qui nettoiera les artefacts de compilation pour toutes les plateformes et configurations. Attention, car cela supprimera tous les fichiers non suivis et ignorés dans le répertoire. Ne lancez pas cette commande si vous avez un travail non commité !
Autres options de compilation¶
Il y a plusieurs autres options de compilation que vous pouvez utiliser pour configurer la façon dont Godot devrait être compilé (compilateur, options de débogage, etc.) ainsi que les fonctionnalités à activer/désactiver.
Vérifiez le résultat de scons --help
pour obtenir des détails à propos de chaque option de la version que vous souhaitez compiler.
Remplacement des options de compilation¶
Utilisation d'un fichier¶
Le fichier custom.py
par défaut peut être créé à la racine du moteur Godot pour initialiser toutes les options de compilation de SCons passées par la ligne de commande :
# custom.py
optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"
Vous pouvez également désactiver certains des modules intégrés avant la compilation, ce qui permet d'économiser le temps nécessaire à la compilation du moteur, voir la page Optimiser une compilation pour sa taille pour plus de détails.
Voir aussi
Vous pouvez utiliser le générateur d'options de compilation de Godot en ligne pour générer un fichier custom.py
contenant les options SCons. Vous pouvez ensuite enregistrer ce fichier et le placer à la racine de votre répertoire source Godot.
Un autre fichier personnalisé peut être spécifié explicitement avec l'option de ligne de commande profile
, tous deux remplaçant la configuration de construction par défaut :
scons profile=path/to/custom.py
Note
Les options de compilation définies à partir du fichier peuvent être remplacées par les options de la ligne de commande.
Il est également possible de remplacer les options de manière conditionnelle :
# 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
Utilisation de SCONSFLAGS¶
SCONSFLAGS
est une variable d'environnement qui est utilisée par SCons pour définir les options automatiquement sans avoir à les fournir via la ligne de commande.
For instance, you may want to force a number of CPU threads with the
aforementioned -j
option for all future builds:
export SCONSFLAGS="-j4"
set SCONSFLAGS=-j4
$env:SCONSFLAGS="-j4"
SCU (single compilation unit) build¶
Regular builds tend to be bottlenecked by including large numbers of headers in each compilation translation unit. Primarily to speed up development (rather than for production builds), Godot offers a "single compilation unit" build (aka "Unity / Jumbo" build).
For the folders accelerated by this option, multiple .cpp
files are
compiled in each translation unit, so headers can be shared between multiple
files, which can dramatically decrease build times.
To make a SCU build, use the scu_build=yes
SCons option.
Note
When developing a Pull Request using SCU builds, be sure to make a
regular build prior to submitting the PR. This is because SCU builds
by nature include headers from earlier .cpp
files in the
translation unit, therefore won't catch all the includes you will
need in a regular build. The CI will catch these errors but it will
usually be faster to catch them on a local build on your machine.
Exporter des modèles¶
Les modèles d'exportation officiels sont téléchargés à partir du site Godot Engine : godotengine.org. Cependant, vous voudrez peut-être les construire vous-même (au cas où vous en voudriez de plus récents, que vous utilisez des modules personnalisés, ou tout simplement que vous ne faites pas confiance à votre propre ombre).
Si vous téléchargez le paquet officiel de modèles d'exportation et que vous le décompressez, vous remarquerez que la plupart des fichiers sont des binaires ou des paquets optimisés pour chaque plate-forme :
android_debug.apk
android_release.apk
web_debug.zip
web_release.zip
linux_server_32
linux_server_64
linux_x11_32_debug
linux_x11_32_release
linux_x11_64_debug
linux_x11_64_release
macos.zip
version.txt
windows_32_debug.exe
windows_32_release.exe
windows_64_debug.exe
windows_64_release.exe
Pour les créer vous-même, suivez les instructions détaillées pour chaque plate-forme dans cette même section de tutoriel. Chaque plateforme explique comment créer son propre modèle.
Le fichier version.txt
doit contenir l'identifiant de version Godot correspondant. Ce fichier est utilisé pour installer les modèles d'exportation dans un répertoire spécifique à la version afin d'éviter les conflits. Par exemple, si vous créez des modèles d'exportation pour Godot 3.1.1, le fichier version.txt
doit contenir 3.1.1.stable
sur la première ligne (et rien d'autre). Cet identifiant de version est basé sur les lignes major
, minor
, patch
(si présent) et status
du fichier version.py dans le dépôt Git Godot.
If you are developing for multiple platforms, macOS is definitely the most convenient host platform for cross-compilation, since you can cross-compile for every target. Linux and Windows come in second place, but Linux has the advantage of being the easier platform to set this up.