Einführung in das Buildsystem

Godot ist in erster Linie ein C++-Projekt und verwendet das SCons-Buildsystem. Wir lieben SCons, weil es unser Buildsystem so wartbar und einfach einzurichten macht. Und dank dieser Tatsache kann das Kompilieren von Godot aus dem Quellcode so einfach sein wie das Ausführen von:

scons

Dies erzeugt einen Editor-Build für Ihre aktuelle Plattform, Ihr Betriebssystem und Ihre Architektur. Sie können ändern, was gebaut werden soll, indem Sie ein Target, eine Plattform und/oder eine Architektur angeben. Um zum Beispiel eine Exportvorlage zu erstellen, die zum Ausführen exportierter Spiele verwendet wird, können Sie Folgendes ausführen:

scons target=template_release

Wenn Sie vorhaben, die Engine zu debuggen oder weiterzuentwickeln, dann sollten Sie die Option dev_build aktivieren, um den Debugging-Code für Entwickler zu ermöglichen:

scons dev_build=yes

In den folgenden Abschnitten dieses Artikels werden diese und andere universelle Optionen ausführlicher erläutert. Bevor Sie Godot kompilieren können, müssen Sie jedoch einige Voraussetzungen installieren. Weitere Informationen dazu finden Sie in der Dokumentation der Plattform:

Diese Artikel beschreiben sehr detailliert, wie Sie Ihre Umgebung für das Kompilieren von Godot auf einer bestimmten Plattform einrichten, und wie Sie für diese Plattform kompilieren. Sie können gerne zwischen den Artikeln und diesem Artikel hin- und herspringen, um plattformspezifische und universelle Konfigurationsoptionen zu finden.

Multithreading verwenden

Der Erstellungsprozess kann eine Weile dauern, je nachdem, wie leistungsfähig Ihr System ist. Standardmäßig ist das SCons-Setup von Godot so konfiguriert, dass alle CPU-Threads bis auf einen verwendet werden (um das System während der Kompilierung reaktionsfähig zu halten). Wenn Sie einstellen wollen, wie viele CPU-Threads SCons verwenden soll, verwenden Sie den Parameter -j <Threads>, um anzugeben, wie viele Threads für den Build verwendet werden sollen.

Beispiel für die Verwendung von 4 Threads:

scons -j4

Plattformauswahl

Das Buildsystem von Godot erkennt zunächst die Plattformen, für die es bauen kann. Wenn die Plattform nicht erkannt wird, erscheint sie einfach nicht in der Liste der verfügbaren Plattformen. Die Build-Anforderungen für jede Plattform werden im weiteren Verlauf dieses Tutorials beschrieben.

SCons wird einfach durch den Aufruf von scons aufgerufen. Wenn keine Plattform angegeben wird, erkennt SCons die Target-Plattform automatisch anhand der Host-Plattform. Es wird dann sofort mit der Erstellung für die Target-Plattform beginnen.

Um die verfügbaren Target-Plattformen aufzulisten, verwenden Sie scons platform=list:

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

    android
    ios
    linuxbsd
    macos
    web
    windows

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

Um für eine Plattform zu bauen (zum Beispiel linuxbsd), verwenden Sie das Argument platform= (oder kurz p=):

scons platform=linuxbsd

Erzeugte Binärdatei

Die erzeugten Binärdateien werden in das Unterverzeichnis bin/ gelegt, im Allgemeinen mit folgender Namenskonvention:

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

Für den obigen Build-Versuch würde das Ergebnis folgendermaßen aussehen:

ls bin
bin/godot.linuxbsd.editor.x86_64

Das bedeutet, dass die Binärdatei für Linux oder *BSD (nicht beide) ist, nicht optimiert ist, den gesamten Editor einkompiliert hat und für 64 Bit gedacht ist.

Eine Windows-Binärdatei mit derselben Konfiguration sieht folgendermaßen aus:

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

Kopieren Sie diese Binärdatei an einen beliebigen Ort, da sie den Projektmanager, den Editor und alle Elemente zur Ausführung des Spiels enthält. Es fehlen jedoch die Daten, um es auf die verschiedenen Plattformen zu exportieren. Dafür werden die Exportvorlagen benötigt (die entweder von godotengine.org heruntergeladen werden können, oder die Sie sie selbst erstellen können).

Abgesehen davon gibt es einige Standardoptionen, die in allen Build-Targets gesetzt werden können und die im Folgenden erläutert werden.

Target

The target option controls if the editor is compiled and debug flags are used. Optimization levels (optimize) and whether each build contains debug symbols (debug_symbols) is controlled separately from the target. Each mode means:

  • target=editor: Build an editor binary (defines TOOLS_ENABLED and DEBUG_ENABLED)

  • target=template_debug: Build a debug export template (defines DEBUG_ENABLED)

  • target=template_release: Build a release export template

Der Editor ist bei allen PC-Targets (Linux, Windows, macOS) standardmäßig aktiviert, bei allen anderen deaktiviert. Die Deaktivierung des Editors erzeugt eine Binärdatei, die Projekte ausführen kann, aber weder den Editor noch den Projektmanager enthält.

The list of command line arguments available varies depending on the build type.

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

Aliasnamen für Entwicklung und Produktion

Bei der Erstellung von Builds für die Entwicklung (mit Debugging/Profiling-Tools) verfolgt man oft andere Ziele als bei Produktions-Builds (Erzeugen von möglichst schnellen und kleinen Binärdateien).

Godot bietet zwei Aliasnamen für diesen Zweck:

  • dev_mode=yes ist ein Alias für verbose=yes warnings=extra werror=yes tests=yes. Dies aktiviert warnings-as-errors-Verhalten (ähnlich wie Godots Continuous Integration-Setup) und baut auch Unit-Tests, so dass Sie sie lokal ausführen können.

  • production=yes ist ein Alias für use_static_cpp=yes debug_symbols=no lto=auto. Das statische Linken von libstdc++ ermöglicht eine bessere Binärportabilität beim Kompilieren für Linux. Dieser Alias aktiviert auch die Link-Time-Optimierung beim Kompilieren für Linux, Web und Windows mit MinGW, aber LTO bleibt deaktiviert, wenn für macOS, iOS oder Windows mit MSVC kompiliert wird. Der Grund dafür ist, dass LTO auf diesen Plattformen sehr langsam linkt oder Probleme mit dem generierten Code hat.

Sie können die Optionen dieser Aliase manuell außer Kraft setzen, indem Sie sie in derselben Kommandozeile mit anderen Werten angeben. Zum Beispiel können Sie scons production=yes debug_symbols=yes verwenden, um produktionsoptimierte Binärdateien mit Debug-Symbolen zu erzeugen.

Dev-Build

Bemerkung

dev_build sollte nicht mit dev_mode verwechselt werden, welches ein Alias für mehrere entwicklungsbezogene Optionen ist (siehe oben).

Bei der Engine-Entwicklung kann die Option dev_build zusammen mit target verwendet werden, um entwicklungsspezifischen Code zu aktivieren. dev_build definiert DEV_ENABLED, deaktiviert die Optimierung (-O0//0d), aktiviert die Erzeugung von Debug-Symbolen und definiert NDEBUG nicht (so dass assert() in Bibliotheken von Drittanbietern funktioniert).

scons platform=<platform> dev_build=yes

Dieses Flag fügt das Suffix .dev (für englisch "development") an den erzeugten Binärnamen an.

Siehe auch

Es gibt zusätzliche SCons-Optionen, um Sanitizer zu aktivieren, das sind Tools, die Sie zur Kompilierungszeit aktivieren können, um bestimmte Engine-Probleme besser zu debuggen. Siehe Verwendung von Sanitizern für weitere Informationen.

Debug-Symbole

Standardmäßig wird debug_symbols=no verwendet, was bedeutet, dass keine Debug-Symbole in kompilierten Binärdateien enthalten sind. Verwenden Sie debug_symbols=yes, um Debugsymbole in kompilierte Binärdateien einzubinden, was Debuggern und Profilern erlaubt, korrekt zu arbeiten. Debug-Symbole sind auch erforderlich, damit Godots Crash-Stacktraces mit Verweisen auf Quellcode-Dateien und -Zeilen angezeigt werden.

Der Nachteil ist, dass Debug-Symbole große Dateien sind (wesentlich größer als die Binärdateien selbst). Aus diesem Grund enthalten die offiziellen Binärdateien derzeit keine Debug-Symbole. Das bedeutet, dass Sie Godot selbst kompilieren müssen, um Zugang zu Debug-Symbolen zu haben.

Wenn Sie debug_symbols=yes verwenden, können Sie auch separate_debug_symbols=yes verwenden, um Debug-Informationen in einer separaten Datei mit der Endung .debug abzulegen. Dies erlaubt es, beide Dateien unabhängig voneinander zu veröffentlichen. Beachten Sie, dass unter Windows, wenn Sie mit MSVC kompilieren, die Debugging-Informationen immer in eine separate .pdb-Datei geschrieben werden, unabhängig von separate_debug_symbols.

Tipp

Verwenden Sie den Befehl strip <path/to/binary>, um Debug-Symbole aus einer bereits kompilierten Binärdatei zu entfernen.

Optimierungsstufen

Es können verschiedene Optimierungsstufen des Compilers ausgewählt werden:

  • optimize=speed_trace (Standardeinstellung, wenn Nicht-Web-Plattformen verwendet werden): Begünstigt die Ausführungsgeschwindigkeit auf Kosten einer größeren Binärgröße. Optimierungen können sich manchmal negativ auf die Nutzung des Debuggers auswirken (Stack Traces können weniger genau sein. Wenn dies bei Ihnen auftritt, verwenden Sie stattdessen optimize=debug.

  • optimize=speed: Bevorzugt noch mehr Ausführungsgeschwindigkeit, auf Kosten einer noch größeren Binärgröße im Vergleich zu optimize=speed_trace. Im Vergleich zu optimize=debug ist diese Option noch weniger debug-freundlich, da sie die aggressivsten verfügbaren Optimierungen verwendet.

  • optimize=size (Default, wenn das Target die Web-Plattform ist): Bevorzugt kleine Binärdateien auf Kosten einer langsameren Ausführungsgeschwindigkeit.

  • optimize=debug: Aktiviert nur Optimierungen, die das Debugging in keiner Weise beeinflussen. Dies führt zu schnelleren Binärdateien als optimize=none, aber zu langsameren Binärdateien als optimize=speed_trace.

  • optimize=none: Keine Optimierung durchführen. Dies bietet die schnellsten Build-Zeiten, aber die langsamsten Ausführungszeiten.

  • optimize=custom (nur für fortgeschrittene Benutzer): Übergeben Sie keine Optimierungsargumente an die C/C++ Compiler. Sie müssen die Argumente manuell mit den SCons-Optionen cflags, ccflags und cxxflags übergeben.

Architektur

Die Option arch ist dazu gedacht, die CPU- oder Betriebssystemversion zu bestimmen, auf der die Binärdateien laufen sollen. Sie ist hauptsächlich auf Desktop-Plattformen ausgerichtet und wird überall sonst ignoriert.

Unterstützte Werte für die Option arch sind auto, x86_32, x86_64, arm32, arm64, rv64, ppc32, ppc64 und wasm32.

scons platform=<platform> arch={auto|x86_32|x86_64|arm32|arm64|rv64|ppc32|ppc64|wasm32}

Dieses Flag fügt den Wert von arch an die resultierenden Binärdateien an, wenn dies relevant ist. Der Standardwert arch=auto erkennt die Architektur, die der Host-Plattform entspricht.

Benutzerdefinierte Module

Es ist möglich, neben den Built-in-Modulen auch Module zu kompilieren, die sich außerhalb des Godot-Verzeichnisbaums befinden.

Eine custom_modules Build-Option kann vor dem Kompilieren an die Kommandozeile übergeben werden. Die Option stellt eine durch Kommas getrennte Liste von Verzeichnispfaden dar, die eine Sammlung unabhängiger C++-Module enthalten, die als C++-Pakete angesehen werden können, genau wie das Built-in-Verzeichnis modules/.

So ist es beispielsweise möglich, sowohl relative und absolute Pfade als auch Pfade zum Benutzerverzeichnis anzugeben, die solche Module enthalten:

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

Bemerkung

Wenn es ein benutzerdefiniertes Modul mit dem gleichen Verzeichnisnamen wie ein Built-in-Modul gibt, kompiliert die Engine nur das benutzerdefinierte Modul. Diese Logik kann verwendet werden, um Built-in-Modulimplementierungen außer Kraft zu setzen.

Siehe auch

Benutzerdefinierte Module in C++

Erzeugte Dateien bereinigen

Manchmal kann ein Fehler auftreten, weil noch generierte Dateien vorhanden sind. Sie können diese entfernen, indem Sie scons --clean <options> verwenden, wobei <options> die Liste der Build-Optionen ist, die Sie zuvor zum Bauen von Godot verwendet haben.

Alternativ können Sie auch git clean -fixd verwenden, das die Build-Artefakte für alle Plattformen und Konfigurationen bereinigt. Seien Sie vorsichtig, da dies alle nicht getrackten und ignorierten Dateien im Repository entfernt. Führen Sie diesen Befehl nicht aus, wenn Sie Ihre Arbeit noch nicht committet haben!

Weitere Build-Optionen

Es gibt verschiedene andere Build-Optionen, die Sie verwenden können, um die Art und Weise zu konfigurieren, wie Godot gebaut werden soll (Compiler, Debug-Optionen usw.) sowie die einzuschließenden/abzuschaltenden Features.

Schauen Sie sich die Ausgabe von scons --help an, um für die Version, die Sie kompilieren wollen, Details über jede Option zu erfahren.

Überschreiben der Build-Optionen

Überschreiben per Datei

Die Standarddatei custom.py kann im Stammverzeichnis des Godot-Engine-Quellcodes erstellt werden, um alle SCons-Build-Optionen zu initialisieren, die über die Kommandozeile übergeben werden:

custom.py
optimize = "size"
module_mono_enabled = "yes"
use_llvm = "yes"
extra_suffix = "game_title"

You can also disable some of the built-in modules before compiling, saving some time it takes to build the engine. See Einen Build auf Größe optimieren page for more details.

Siehe auch

Sie können den Online Godot Build Options Generator nutzen, um eine custom.py Datei zu erzeugen, welche die SCons-Optionen beinhaltet. Dann kann diese Datei im Stammverzeichnis von Godot gespeichert werden.

Eine weitere benutzerdefinierte Datei kann explizit mit der profile-Kommandozeilenoption angegeben werden; beides überschreibt die Default-Build-Konfiguration:

scons profile=path/to/custom.py

Bemerkung

Buildoptionen, die aus der Datei festgelegt wurden, können durch die Kommandozeilenoptionen überschrieben werden.

Es ist auch möglich, die Optionen bedingt zu überschreiben:

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

Verwenden per SCONSFLAGS

SCONSFLAGS ist eine Umgebungsvariable, die von SCons verwendet wird, um die Optionen automatisch zu setzen, ohne sie über die Kommandozeile eingeben zu müssen.

Sie können zum Beispiel eine Anzahl von CPU-Threads mit der oben erwähnten Option -j für alle zukünftigen Builds erzwingen:

export SCONSFLAGS="-j4"

SCU (Single Compilation Unit) bauen

Normale Builds neigen dazu, durch die Einbeziehung einer großen Anzahl von Headern in jede Compilation Translation Unit zu einem Bottleneck zu werden. In erster Linie, um die Entwicklung zu beschleunigen (und nicht für Produktions-Builds), bietet Godot einen "Single Compilation Unit"-Build (auch bekannt als "Unity/Jumbo"-Build) an.

Für die Ordner, die durch diese Option beschleunigt werden, werden mehrere .cpp-Dateien in jeder Translation-Unit kompiliert, so dass Header von mehreren Dateien gemeinsam genutzt werden können, was die Build-Zeit drastisch reduzieren kann.

Um einen SCU-Build durchzuführen, verwenden Sie die SCons-Option scu_build=yes.

Bemerkung

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.

Exportvorlagen

Offizielle Exportvorlagen können von der Godot-Engine-Website heruntergeladen werden: godotengine.org. Vielleicht möchten Sie sie jedoch selbst erstellen (falls Sie neuere Vorlagen benötigen, benutzerdefinierte Module verwenden oder einfach Ihrem eigenen Schatten nicht trauen).

Wenn Sie das offizielle Exportvorlagenpaket herunterladen und entpacken, werden Sie feststellen, dass die meisten Dateien optimierte Binärdateien oder Pakete für jede Plattform sind:

android_debug.apk
android_release.apk
android_source.zip
ios.zip
linux_debug.arm32
linux_debug.arm64
linux_debug.x86_32
linux_debug.x86_64
linux_release.arm32
linux_release.arm64
linux_release.x86_32
linux_release.x86_64
macos.zip
version.txt
web_debug.zip
web_dlink_debug.zip
web_dlink_nothreads_debug.zip
web_dlink_nothreads_release.zip
web_dlink_release.zip
web_nothreads_debug.zip
web_nothreads_release.zip
web_release.zip
windows_debug_x86_32_console.exe
windows_debug_x86_32.exe
windows_debug_x86_64_console.exe
windows_debug_x86_64.exe
windows_debug_arm64_console.exe
windows_debug_arm64.exe
windows_release_x86_32_console.exe
windows_release_x86_32.exe
windows_release_x86_64_console.exe
windows_release_x86_64.exe
windows_release_arm64_console.exe
windows_release_arm64.exe

Um diese selbst zu erstellen, folgen Sie den Anweisungen, die für jede Plattform in diesem Abschnitt des Tutorials aufgeführt sind. Jede Plattform erklärt, wie man ihre eigene Vorlage erstellt.

Die Datei version.txt sollte den entsprechenden Godot-Versionsbezeichner enthalten. Diese Datei wird verwendet, um Exportvorlagen in einem versionsspezifischen Verzeichnis zu installieren, um Konflikte zu vermeiden. Wenn Sie beispielsweise Exportvorlagen für Godot 3.1.1 erstellen, sollte version.txt in der ersten Zeile 3.1.1.stable enthalten (und nichts anderes). Diese Versionskennung basiert auf den Zeilen major, minor, patch (falls vorhanden) und status der Datei version.py im Godot-Git-Repository.

Wenn Sie für mehrere Plattformen entwickeln, ist macOS definitiv die bequemste Host-Plattform für die Cross-Kompilierung, da Sie für jedes Target crosskompilieren können. Linux und Windows kommen an zweiter Stelle, aber Linux hat den Vorteil, dass es die einfachere Plattform ist, um dies einzurichten.