Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Sistema di compilazione principale: lavorare con SCons

Vedi anche

Questa pagina documenta come compilare godot-cpp. Se invece si desidera compilare Godot, consultare Introduzione al sistema di compilazione.

godot-cpp usa SCons per il suo sistema di compilazione principale. È modellato sul sistema di compilazione di Godot e alcuni comandi disponibili lì sono disponibili anche nei progetti godot-cpp.

Per cominciare

Per compilare un progetto godot-cpp, in genere basta installare SCons ed eseguirlo nella cartella del progetto:

scons

Potresti voler conoscere le opzioni disponibili:

scons --help

Per ricompilare correttamente il proprio progetto, aggiungere --clean al comando di compilazione:

scons --clean

È possibile trovare ulteriori informazioni sugli argomenti comuni di SCons e sui modelli di compilazione nella Guida utente di SCons. È possibile che i singoli progetti godot-cpp abbiano aggiunto commandi in più, quindi consulta la loro documentazione specifica per ulteriori informazioni.

Configurare un IDE

La maggior parte degli IDE può utilizzare un file compile_commands.json per interpretare un progetto C++. È possibile generarlo con godot-cpp attraverso il seguente comando:

# Generate compile_commands.json while compiling.
scons compiledb=yes

# Generate compile_commands.json without compiling.
scons compiledb=yes compile_commands.json

Per ulteriori informazioni, consultare le guide di configurazione per gli IDE. Sebbene scritte per i collaboratori del motore Godot, sono ampiamente applicabili anche ai progetti godot-cpp.

Caricare la propria GDExtension in Godot

Godot carica le GDExtensions individuando i file .gdextension nella cartella del progetto. I file .gdextension servono per selezionare e caricare un binario compatibile con il computer/sistema operativo attuale.

Il template godot-cpp-template, così come la sezione Per cominciare, forniscono file .gdextension di esempio per le GDExtensions, ampiamente compatibili con molti sistemi diversi.

Compilare per più piattaforme

Le GDExtension sono progettate per funzionare su molti sistemi diversi, ognuno con binari e configurazioni di compilazione separati. Se si intende pubblicare la propria GDExtension, consigliamo di fornire i binari per tutte le configurazioni menzionate nel file godot-cpp-template .gdextension file.

Esistono due modi popolari per realizzare build multipiattaforma:

• Strumenti di compilazione multipiattaforma

• Integrazione continua (CI)

godot-cpp-template contiene un esempio di configurazione per un flusso di lavoro CI basato su GitHub.

Utilizzare un file API personalizzato

Ogni ramo di godot-cpp include un file API (extension_api.json) appropriato per la rispettiva versione di Godot (ad esempio, il ramo 4.3 include il file API compatibile con Godot versione 4.3 e successive).

Tuttavia, potrebbe essere desiderato utilizzare un file extension_api.json personalizzato, ad esempio:

• Se si desidera utilizzare le API più recenti dal master di Godot.

• Se si compila Godot autonomamente con opzioni diverse dalle build ufficiali (ad esempio, disable_3d=yes o precision=double).

• Se si desidera utilizzare le API esposte dai moduli personalizzati.

Per utilizzare un file API personalizzato, bisogna prima generarlo dall'eseguibile Godot appropriato:

godot --dump-extension-api

Il file extension_api.json risultante sarà creato nella cartella dell'eseguibile. Per utilizzarlo, è possibile aggiungere custom_api_file al comando di compilazione:

scons platform=<platform> custom_api_file=<PATH_TO_FILE>

Alternativamente, è possibile aggiungerlo come file API predefinito al progetto aggiungendo la seguente riga al file SConstruct:

localEnv["custom_api_file"] = "extension_api.json"

Modifying generated files

If you have to modify the files generated by godot-cpp, its hook system is the right way of doing so. We provide the BindingGeneratorHooks class, located at godot-cpp/tools/binding_generator_hooks.py. Your custom hooks are a python class that extends BindingGeneratorHooks and overrides (some of) its methods. After defining your subclass, you should export an instance of it from your SConstruct with the key binding_hooks to godot-cpp's SConstruct. This way you let godot-cpp's SConstruct know about your class, see the example below for one way of doing this.

Esempio

This example adds a string constant of every signal in a class to its class header. For example, in base_button.hpp we will add static constexpr char SIGNAL_PRESSED[] = "pressed"; for the pressed signal. We will use the SConstruct file from the godot-cpp template. We start by creating custom_generator.py at the root of our project. It only overrides alter_engine_class_header, as that is all we need.

custom_generator.py

import sys

sys.path.insert(0, "godot-cpp")
from tools.binding_generator_hooks import BindingGeneratorHooks

class CustomBindingGeneratorHooks(BindingGeneratorHooks):
    def alter_engine_class_header(self, class_api, lines):
        signals = []
        if "signals" in class_api:
            for signal_api in class_api["signals"]:
                name = signal_api["name"]
                signal_constant = "\tstatic constexpr char SIGNAL_" + name.upper() + '[] = "' + name + '";'
                signals.append(signal_constant)
            try:
                idx = lines.index("public:") + 1
                for signal_const in signals:
                    lines.insert(idx, signal_const)
                    idx += 1
            except ValueError:
                print("no public keyword found, not adding signals")
        return lines

Next, we import the class in our SConstruct file:

from custom_generator import CustomBindingGeneratorHooks

Additionally, we edit the line that exports variables to godot-cpp/SConstruct to include an instance of our class, like so:

env = SConscript("godot-cpp/SConstruct", {"env": env, "customs": customs, "binding_hooks": CustomBindingGeneratorHooks()})

This is everything you need, when you regenerate the files they should contain signal name constants for all signals in the API file.