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

Introduzione al sistema di compilazione

Godot è un progetto principalmente in C++ e utilizza il sistema di compilazione SCons. Amiamo SCons perché rende il nostro sistema di compilazione facile da gestire e configurare. E grazie a questo, compilare Godot da sorgente può essere tanto semplice quanto eseguire:

scons

Questo genera una build dell'editor per la piattaforma, il sistema operativo e l'architettura attuali. È possibile cambiare cosa viene compilato specificando una destinazione, una piattaforma e/o un'architettura. Ad esempio, per creare un modello di esportazione utilizzato per eseguire giochi esportati, è possibile eseguire:

scons target=template_release

Se si intende effettuare il debug o sviluppare il motore, magari si desidera abilitare l'opzione dev_build per abilitare il codice di debug solo per lo sviluppo:

scons dev_build=yes

Le sezioni successive dell'articolo spiegheranno queste e altre opzioni universali in modo più dettagliato. Tuttavia, prima di poter compilare Godot, è necessario installare alcuni prerequisiti. Consultare la documentazione della piattaforma specifica per saperne di più:

Questi articoli trattano in dettaglio sia come configurare il proprio ambiente per compilare Godot su una piattaforma specifica, sia come compilare per tale piattaforma. Non esitare a consultare entrambi gli articoli per conoscere le opzioni di configurazione universali e specifiche della piattaforma.

Utilizzo del multi-threading

Il processo di compilazione potrebbe richiedere del tempo, a seconda della potenza del sistema. Normalmente, SCons in Godot è configurato per utilizzare tutti i thread della CPU tranne uno (per mantenere il sistema reattivo durante la compilazione). Se il sistema ha 4 thread della CPU o meno, normalmente utilizzerà tutti i thread.

Se si desidera regolare il numero di thread della CPU che SCons utilizzerà, usare il parametro -j<threads> per specificare quanti thread saranno utilizzati per la compilazione.

Esempio per l'utilizzo di 12 thread:

scons -j12

Selezione della piattaforma

Il sistema di compilazione di Godot comincerà rilevando le piattaforme per cui può compilare. Se una piattaforma non è rilevata, non apparirà nell'elenco delle piattaforme disponibili. I requisiti di compilazione per ciascuna piattaforma sono descritti nel resto di questa sezione del tutorial.

SCons si invoca chiamando scons. Se nessuna piattaforma viene specificata, SCons rileverà automaticamente la piattaforma di destinazione in base alla piattaforma host. Comincerà quindi a compilare per la piattaforma di destinazione immediatamente.

Per elencare le piattaforme di destinazione disponibili, usare 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>

Per compilare per una piattaforma (ad esempio, linuxbsd), eseguire con l'argomento platform= (o p= per abbreviazione):

scons platform=linuxbsd

Eseguibile risultante

Gli eseguibili risultanti saranno inseriti nella sottocartella bin/, generalmente con questa convenzione di denominazione:

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

Per il tentativo di compilazione precedente, il risultato sarebbe simile al seguente:

ls bin
bin/godot.linuxbsd.editor.x86_64

Ciò significa che l'eseguibile è per Linux o *BSD (non entrambi), non è ottimizzato, ha l'intero editor compilato ed è pensato per 64 bit.

Un eseguibile di Windows con la stessa configurazione apparirà così:

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

Copia l'eseguibile in qualsiasi posizione desiderata, poiché contiene il Gestore dei progetti, l'editor e tutti ciò che serve per eseguire il gioco. Tuttavia, mancano i dati per esportarlo sulle diverse piattaforme. Per questo sono necessari i modelli di esportazione (che è possibile scaricare da godotengine.org, oppure creare manualmente).

Oltre a ciò, ci sono alcune opzioni standard che è possibile impostare in tutte le destinazioni di compilazione, e che saranno spiegate di seguito.

Target

L'opzione target controlla se l'editor è compilato e se i flag di debug sono utilizzati. I livelli di ottimizzazione (optimize) e se ogni build contiene i simboli di debug (debug_symbols) sono controllati separatamente dalla destinazione. Ogni modalità significa:

target=editor: compila un eseguibile dell'editor (definisce TOOLS_ENABLED e DEBUG_ENABLED)
target=template_debug: compila un modello di esportazione di debug (definisce DEBUG_ENABLED)
target=template_release: compila un modello di esportazione di rilascio

L'editor è abilitato come predefinito su tutte le destinazioni PC (Linux, Windows, macOS), mentre è disabilitato su tutte le altre. Disabilitando l'editor si ottiene un eseguibile che può eseguire progetti, ma non include né l'editor né il Gestore dei progetti.

L'elenco degli argomenti della riga di comando disponibili varia a seconda del tipo di compilazione.

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

Alias di sviluppo e produzione

Quando si creano compilazioni per lo sviluppo (che eseguono strumenti di debugging/profiling), spesso si hanno obiettivi diversi rispetto alle compilazioni di produzione (tra i quali, rendere gli eseguibili più veloci e piccoli possibile).

Godot fornisce due alias a questo scopo:

dev_mode=yes è un alias per verbose=yes warnings=extra werror=yes tests=yes. Questo abilita il comportamento degli avvisi come errori (simile alla configurazione di integrazione continua di Godot) e crea anche test unitari per poterli eseguire localmente.
production=yes is an alias for use_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.

È possibile sovrascrivere manualmente le opzioni di questi alias specificandole sulla stessa riga di comando con valori diversi. Ad esempio, è possibile utilizzare scons production=yes debug_symbols=yes per creare eseguibili ottimizzati per la produzione con simboli di debug inclusi.

Compilazione di sviluppo

Nota

dev_build non deve essere confuso con dev_mode, che è un alias per diverse opzioni relative allo sviluppo (vedi sopra).

Durante lo sviluppo del motore, l'opzione dev_build si può utilizzare insieme a target per abilitare codice specifico per lo sviluppo. dev_build definisce DEV_ENABLED, disabilita l'ottimizzazione (-O0//0d), abilita la generazione di simboli di debug e non definisce NDEBUG (affinché assert() funzioni nelle librerie di terze parti).

scons platform=<platform> dev_build=yes

Questo flag aggiunge il suffisso .dev (per sviluppo) al nome dell'eseguibile generato.

Vedi anche

Sono disponibili opzioni SCons aggiuntive per abilitare i sanitizer, ovvero strumenti in fase di compilazione per migliorare il debug di determinati problemi del motore. Consultare Utilizzare i sanitizer per ulteriori informazioni.

Simboli di debug

Come predefinito, è utilizzato debug_symbols=no, il che significa che nessun simbolo di debug è incluso negli eseguibili compilati. Utilizzare debug_symbols=yes per includere simboli di debug, consentendo ai debugger e ai profiler di funzionare correttamente. I simboli di debug sono necessari anche per mostrare gli stacktrace dei crash di Godot, con riferimenti a file e righe di codice sorgente.

Lo svantaggio è che i simboli di debug sono file grandi (significativamente più grandi degli eseguibili stessi). Pertanto, gli eseguibili ufficiali attualmente non includono simboli di debug. Ciò significa che è necessario compilare Godot autonomamente per avere accesso ai simboli di debug.

Quando si utilizza debug_symbols=yes, è anche possibile utilizzare separate_debug_symbols=yes per inserire le informazioni di debug in un file separato con un suffisso .debug. Questo consente di distribuire entrambi i file indipendentemente. Si noti che su Windows, quando si compila con MSVC, le informazioni di debug sono sempre scritte in un file .pdb separato, a prescindere da separate_debug_symbols.

Suggerimento

Utilizzare il comando strip <percorso/del/binario> per rimuovere i simboli di debug da un eseguibile già compilato.

Livello di ottimizzazione

È possibile scegliere tra numerosi livelli di ottimizzazione per il compilatore:

optimize=speed_trace (predefinito se si compila per piattaforme non Web): favorisce la velocità di esecuzione a scapito di un eseguibile più grande. Le ottimizzazioni possono talvolta avere un impatto negativo sull'utilizzo del debugger (gli stack trace potrebbero essere meno precisi). In tal caso, utilizzare optimize=debug.
optimize=speed: favorisce la velocità di esecuzione ancora di più, a scapito di un eseguibile ancora più grande rispetto a optimize=speed_trace. Ancora meno intuitivo per il debug rispetto a optimize=debug, poiché utilizza le ottimizzazioni più aggressive disponibili.
optimize=size (predefinito se si compila per piattaforma Web): favorisce eseguibili piccoli a scapito di una velocità di esecuzione più lenta.
optimize=size_extra: Favorisce eseguibili ancora più piccoli, a scapito di una velocità di esecuzione ancora più lenta rispetto a optimize=size.
optimize=debug: abilita solo le ottimizzazioni che non influiscono in alcun modo sul debug. Ciò produce eseguibili più veloci di optimize=none, ma più lenti di optimize=speed_trace.
optimize=none: Non effettua alcuna ottimizzazione. Questo fornisce tempi di compilazione più rapidi, ma tempi di esecuzione più lenti.
optimize=custom (solo per utenti avanzati): Non passare argomenti di ottimizzazione ai compilatori C/C++. Sarà necessario passare gli argomenti manualmente attraverso le opzioni SCons cflags, ccflags e cxxflags.

Architettura

L'opzione arch serve a controllare la versione della CPU o dell'OS su cui avviare gli eseguibili. È pensata principalmente per le piattaforme desktop e ignorata per ogni altra.

I valori supportati per l'opzione arch sono auto, x86_32, x86_64, arm32, arm64, rv64, ppc32, ppc64 e wasm32.

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

Questo flag aggiunge il valore arch agli eseguibili risultanti quando pertinente. Il valore predefinito arch=auto rileva l'architettura che corrisponde alla piattaforma host.

Moduli personalizzati

È possibile compilare moduli che risiedono fuori dall'albero di cartelle di Godot, insieme ai moduli integrati.

È possibile passare l'opzione di compilazione custom_modules alla riga di comando prima della compilazione. L'opzione rappresenta un elenco di percorsi di cartelle, separati da virgole, contenenti una raccolta di moduli C++ indipendenti che si possono considerare come pacchetti C++, proprio come la cartella integrata modules/.

Ad esempio, è possibile fornire percorsi relativi, assoluti e percorsi di cartelle utente contenenti tali moduli:

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

Nota

Se c'è un modulo personalizzato con lo stesso nome di cartella di un modulo integrato, il motore compilerà solo quello personalizzato. Questa logica si può utilizzare per sovrascrivere le implementazioni dei moduli integrati.

Vedi anche

Moduli personalizzati in C++

Pulizia dei file generati

A volte, è possibile riscontrare un errore dovuto alla presenza di file generati. Si possono rimuovere tramite scons --clean <options>, dove <options> è l'elenco delle opzioni di compilazione utilizzate precedentemente per compilare Godot.

In alternativa, si può usare git clean -fixd, il quale pulirà gli artefatti di compilazione per tutte le piattaforme e configurazioni. Attenzione, poiché questo rimuoverà tutti i file non tracciati e ignorati nel repository. Non eseguire questo comando se hai del lavoro non ancora committato!

Altre opzioni di compilazione

Esistono diverse altre opzioni di compilazione che si possono usare per configurare il modo in cui Godot dovrebbe essere compilato (compilatore, opzioni di debug, ecc.) nonché le funzionalità da includere/disabilitare.

Dare un'occhiata al risultato di scons --help per i dettagli su ciascuna opzione per la versione che si desidera compilare.

Sovrascrivere le opzioni di compilazione

Utilizzando un file

Il file custom.py predefinito può essere creato nella radice del codice sorgente di Godot Engine per inizializzare tutte le opzioni di compilazione SCons passate tramite la riga di comando:

custom.py

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

È anche possibile disabilitare alcuni moduli integrati prima di compilare il motore, risparmiando tempo. Consultare la pagina Ottimizzare una compilazione per dimensioni per maggiori dettagli.

Vedi anche

È possibile usare il generatore di opzioni di compilazione di Godot online per generare un file custom.py contenente le opzioni SCons. Si potrà quindi salvare questo file e posizionarlo nella cartella radice della sorgente di Godot.

Un altro file personalizzato si può specificare esplicitamente con l'opzione della riga di comando profile, entrambi sovrascrivendo la configurazione di compilazione predefinita:

scons profile=path/to/custom.py

Nota

È possibile sovrascrivere le opzioni di compilazione definite dal file tramite opzioni della riga di comando.

È anche possibile sovrascrivere le opzioni condizionalmente:

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

Utilizzare SCONSFLAGS

SCONSFLAGS è una variabile di ambiente utilizzata da SCons per impostare automaticamente le opzioni senza doverle fornire tramite la riga di comando.

Ad esempio, è possibile forzare un certo numero di thread della CPU con l'opzione -j menzionata in precedenza per tutte le compilazione future:

export SCONSFLAGS="-j4"

set SCONSFLAGS=-j4

$env:SCONSFLAGS="-j4"

Compilazione per SCU (unità di compilazione singola)

Le compilazioni regolari tendono a essere ostacolate a causa dell'inclusione di tantissimi header in ogni unità di traduzione di compilazione. Principalmente per velocizzare lo sviluppo (piuttosto che per le compilazioni di produzione), Godot offre una compilazione a "singola unità di compilazione" (detta anche compilazione "Unity / Jumbo").

Per le cartelle accelerate da questa opzione, vengono compilati più file .cpp in ogni unità di traduzione, quindi gli header si possono condividere tra più file, il che può ridurre drasticamente i tempi di compilazione.

Per creare una build SCU, usare l'opzione SCons scu_build=yes.

Nota

Quando si sviluppa una Pull Request utilizzando una build SCU, assicurarsi di creare una build regolare prima di inviare la PR. Questo perché le build SCU, per loro natura, includono gli header dei file .cpp precedenti nell'unità di traduzione, quindi non individueranno tutti gli include necessari in una build regolare. La CI individuerà questi errori, ma di solito sarà più veloce individuarli in una build locale sul computer.

Modelli di esportazione

I modelli di esportazione ufficiali si scaricano dal sito di Godot Engine: godotengine.org. Tuttavia, è possibile compilarli manualmente (nei casi in cui si desiderano di più recenti, si utilizzino moduli personalizzati o puramente non ci si fida della propria ombra).

Scaricando il pacchetto ufficiale dei modelli di esportazione e decomprimendolo, si noterà che la maggior parte dei file sono eseguibili o pacchetti ottimizzati per ciascuna piattaforma:

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

Per crearli autonomamente, seguire le istruzioni dettagliate per ciascuna piattaforma in questa stessa sezione del tutorial. Ogni piattaforma spiega come creare il proprio modello.

Il file version.txt dovrebbe contenere l'identificatore della versione corrispondente di Godot. Questo file è utilizzato per installare i modelli di esportazione in una cartella specifica alla versione, pur di evitare conflitti. Ad esempio, se si stanno creando modelli di esportazione per Godot 4.4.1, version.txt dovrebbe contenere 4.4.1.stable sulla prima riga (e nient'altro). Questo identificatore di versione si basa sulle righe major, minor, patch (se presente) e status del file version.py nel repository Git di Godot.

Se si sta sviluppando per più piattaforme, macOS è sicuramente la piattaforma host più comoda per la cross-compilazione, poiché è possibile cross-compilare per ogni destinazione. Linux e Windows si piazzano al secondo posto, ma Linux ha il vantaggio di essere la piattaforma più semplice da configurare.