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 secondario: lavorare con CMake

Vedi anche

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

Oltre al sistema di compilazione basato su SCons, godot-cpp fornisce anche un file CMakeLists.txt per supportare gli utenti che preferiscono utilizzare CMake anziché SCons per il loro sistema di compilazione.

Sebbene attivamente supportato, il sistema CMake è considerato secondario rispetto al sistema di compilazione SCons. Ciò significa che potrebbe non avere alcune funzionalità disponibili nei progetti che utilizzano SCons.

Introduzione

La possibilità di compilare godot-cpp indipendentemente da un progetto di estensione è concepita principalmente agli sviluppatori di godot-cpp, ai manutentori dei pacchetti e ai sistemi di CI/CD.

Esempi di come utilizzare CMake per integrare la libreria godot-cpp come parte di un progetto di estensione:

• godot-cpp-template

• godot_roguelite

• godot-orchestrator

In fondo alla pagina sono elencati alcuni esempi di configurazione di godot-cpp, molti dei quali potrebbero essere utili per configurare il proprio progetto.

Debug di CMake vs. template_debug di Godot

Un problema emerso in molte discussioni è la confusione tra la compilazione di codice sorgente C++ con simboli di debug abilitati, e la compilazione di un'estensione di Godot con funzionalità di debug abilitate. I due concetti non si escludono a vicenda.

Funzionalità di debug

Enables a pre-processor definition to selectively compile code to help users of a Godot extension with their own project.

Le funzionalità di debug sono abilitate nelle build editor e template_debug, che si possono specificare durante la fase di configurazione come segue:

cmake -S godot-cpp -B cmake-build -DGODOTCPP_TARGET=<target choice>

Debug

Imposta i flag del compilatore in modo che siano generati simboli di debug per aiutare gli sviluppatori di estensioni Godot a risolvere eventuali problemi delle loro estensioni.

Debug è il tipo di build predefinito per i progetti CMake; il modo per selezionarne un altro dipende dal generatore utilizzato:

• Per i generatori di configurazione singola, aggiungere -DCMAKE_BUILD_TYPE=<tipo> al comando configure.

• Per i generatori multi-configurazione, aggiungere --config <tipo> al comando di compilazione.

Dove <tipo> è uno tra Debug, Release, RelWithDebInfo e MinSizeRel.

Deviazioni da SCons

Non tutto il codice del sistema SCons può essere rappresentato perfettamente in CMake; ecco le differenze principali:

• debug_symbols

  Non è più un'opzione esplicita ed è abilitata quando si utilizzano le configurazioni di compilazione CMake: Debug, RelWithDebInfo.

• dev_build

  Non definisce NDEBUG quando disabilitato, NDEBUG è impostato quando si utilizzano le configurazioni di compilazione CMake; Release, MinSizeRel.

• arch

  CMake definisce l'architettura tramite i file della toolchain, mentre l'architettura universale di macOS è controllata tramite la proprietà CMAKE_OSX_ARCHITECTURES, che viene copiata nei target quando questi sono definiti.

• debug_crt

  CMake controlla il collegamento alle librerie di runtime di Windows copiando il valore di CMAKE_MSVC_RUNTIME_LIBRARIES nei target man mano che sono definiti. godot-cpp imposterà questa variabile se non è già impostata. Pertanto, è opportuno includerla prima delle altre dipendenze affinché il valore si propaghi tra i progetti.

Procedura di base

Clona il repository git

git clone https://github.com/godotengine/godot-cpp.git
Cloning into 'godot-cpp'...
...

Configura la compilazione

cmake -S godot-cpp -B cmake-build -G Ninja

• -S specifica la cartella sorgente come godot-cpp

• -B specifica la cartella di compilazione come cmake-build

• -G specifica il generatore come Ninja

In questo esempio, la cartella sorgente è la cartella principale del repository godot-cpp appena clonato. CMake interpreterà il primo percorso specificato nel comando come percorso sorgente oppure, se è specificato un percorso di compilazione esistente, lo dedurrà dalla cache di compilazione.

I seguenti tre comandi sono equivalenti:

# Current working directory is the godot-cpp source root.
cmake . -B build-dir

# Current working directory is an empty godot-cpp/build-dir.
cmake ../

# Current working directory is an existing build path.
cmake .

The build directory is specified so that generated files do not clutter the source tree with build artifacts.

CMake non compila il codice, bensì genera i file utilizzati da uno strumento di compilazione; in questo caso, il generatore Ninja crea i file di compilazione Ninja.

Per visualizzare l'elenco dei generatori eseguire cmake --help.

Opzioni di compilazione

Per visualizzare l'elenco delle opzioni disponibili, utilizzare i flag di comando -L[AH]. A indica le opzioni avanzate, mentre H indica le stringhe di aiuto:

cmake -S godot-cpp -LH

Le opzioni sono specificate sulla riga di comando durante la configurazione, ad esempio:

cmake -S godot-cpp -DGODOTCPP_USE_HOT_RELOAD:BOOL=ON \
    -DGODOTCPP_PRECISION:STRING=double \
    -DCMAKE_BUILD_TYPE:STRING=Debug

Consultare le sezioni setting-build-variables e build-configurations per ulteriori informazioni.

Un elenco non esaustivo di opzioni:

// Path to a custom GDExtension API JSON file.
// (takes precedence over GODOTCPP_GDEXTENSION_DIR)
// ( /path/to/custom_api_file )
GODOTCPP_CUSTOM_API_FILE:FILEPATH=

// Force disabling exception handling code. (ON|OFF)
GODOTCPP_DISABLE_EXCEPTIONS:BOOL=ON

// Path to a custom directory containing the GDExtension interface
// header and API JSON file. ( /path/to/gdextension_dir )
GODOTCPP_GDEXTENSION_DIR:PATH=gdextension

// Set the floating-point precision level. (single|double)
GODOTCPP_PRECISION:STRING=single

// Enable the extra accounting required to support hot reload. (ON|OFF)
GODOTCPP_USE_HOT_RELOAD:BOOL=

Compilazione

Indica a CMake di richiamare il sistema di compilazione generato nella cartella specificata. Il target predefinito è template_debug e la configurazione di compilazione predefinita è Debug.

cmake --build cmake-build

Esempi

Questi esempi, sebbene pensati per gli sviluppatori di godot-cpp, i manutentori di pacchetti e i team di CI/CD, possono essere utili per configurare il proprio progetto di estensione.

Esempi pratici su come utilizzare la libreria godot-cpp come parte di un progetto di estensione sono elencati nell'Introduzione.

Abilitare i test di integrazione

Il target di test godot-cpp-test è protetto da GODOTCPP_ENABLE_TESTING, che è normalmente disabilitato.

Per configurare e compilare il progetto godot-cpp in modo da abilitare i target di test di integrazione, il comando sarà simile al seguente:

cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
cmake --build cmake-build --target godot-cpp-test

Windows e MSVC - Release

Fintanto che CMake è installato dalla pagina CMake Downloads e si trova nel PATH, e che Microsoft Visual Studio è installato con il supporto per C++, CMake rileverà il compilatore MSVC.

Si noti che Visual Studio è un generatore di configurazioni multiple, quindi la configurazione di compilazione deve essere specificata in fase di compilazione, ad esempio, --config Release.

cmake -S godot-cpp -B cmake-build -DGODOTCPP_ENABLE_TESTING=YES
cmake --build cmake-build -t godot-cpp-test --config Release

MSys2/clang64, "Ninja" - Debug

Si presume che la toolchain ming-w64-clang-x86_64 sia installata.

Si noti che Ninja è un generatore a configurazione singola, quindi il tipo di build deve essere specificato in fase di configurazione.

Utilizzando la shell msys2/clang64:

cmake -S godot-cpp -B cmake-build -G"Ninja" \
    -DGODOTCPP_ENABLE_TESTING=YES -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build -t godot-cpp-test

MSys2/clang64, "Ninja Multi-Config" - dev_build, Simboli di debug

Si presume che la toolchain ming-w64-clang-x86_64 sia installata.

Questa volta scegliamo il generatore 'Ninja Multi-Config', quindi il tipo di build è specificato in fase di compilazione.

Utilizzando la shell msys2/clang64:

cmake -S godot-cpp -B cmake-build -G"Ninja Multi-Config" \
    -DGODOTCPP_ENABLE_TESTING=YES -DGODOTCPP_DEV_BUILD:BOOL=ON
cmake --build cmake-build -t godot-cpp-test --config Debug

Emscripten per la piattaforma web

Finora è stato testato solo su Windows. Si può utilizzare questa procedura come esempio:

• Clona e installa gli strumenti Emscripten più recenti nella cartella c:\emsdk.

• Utilizzare il comando C:\emsdk\emsdk.ps1 activate latest per abilitare l'ambiente da PowerShell nella shell attuale.

• L'utility emcmake.bat aggiunge la toolchain Emscripten al comando CMake. Si può aggiungere manualmente; il percorso è specificato all'interno del file emcmake.bat

C:\emsdk\emsdk.ps1 activate latest
emcmake.bat cmake -S godot-cpp -B cmake-build-web -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build-web

Android Cross Compile from Windows

Esistono due percorsi distinti tra cui scegliere durante la configurazione per Android.

Utilizzare le variabili CMAKE_ANDROID_* specificate sulla riga di comando o nel proprio file toolchain, come indicato nella documentazione di cmake-toolchains.

Oppure utilizzare la toolchain e gli script forniti dall'Android SDK e apportare le modifiche utilizzando le variabili ANDROID_* elencate lì. Dove <version> indica la versione dell'NDK installata (testato con 28.1.13356709) e <platform> indica la piattaforma dell'SDK Android (testato con android-29).

Avvertimento

Il website dell'SDK di Android dichiara esplicitamente di non supportare l'utilizzo del metodo integrato in CMake e raccomanda di attenersi ai file della loro toolchain.

Utilizzare il proprio file toolchain

Come descritto nella documentazione di CMake:

cmake -S godot-cpp -B cmake-build --toolchain my_toolchain.cmake
cmake --build cmake-build -t template_release

Facendo l'equivalente tramite solo la riga di comando:

cmake -S godot-cpp -B cmake-build \
    -DCMAKE_SYSTEM_NAME=Android \
    -DCMAKE_SYSTEM_VERSION=<platform> \
    -DCMAKE_ANDROID_ARCH_ABI=<arch> \
    -DCMAKE_ANDROID_NDK=/path/to/android-ndk
cmake --build cmake-build

Using the Android SDK toolchain file

This defaults to the minimum supported version and armv7-a:

cmake -S godot-cpp -B cmake-build \
    --toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake
cmake --build cmake-build

Specificare la piattaforma Android e ABI:

cmake -S godot-cpp -B cmake-build \
    --toolchain $ANDROID_HOME/ndk/<version>/build/cmake/android.toolchain.cmake \
    -DANDROID_PLATFORM:STRING=android-29 \
    -DANDROID_ABI:STRING=armeabi-v7a
cmake --build cmake-build