Compiling for Android

Vedi anche

Questa pagina descrive come compilare i binari dei modelli di esportazione Android dal codice sorgente. Se invece si desidera esportare il proprio progetto su Android, consultare Esportazione per Android.

Nota

In most cases, using the built-in deployer and export templates is good enough. Compiling the Android APK manually is mostly useful for custom builds or custom packages for the deployer.

Inoltre, è comunque necessario seguire i passaggi indicati nel tutorial Esportazione per Android prima di provare a creare un modello di esportazione personalizzato.

Requisiti

Per compilare su Windows, Linux o macOS, è necessario quanto segue:

  • Python 3.8+.

  • Sistema di compilazione SCons 4.0+.

  • Android SDK (gli strumenti a riga di comando sono sufficienti).

    • I componenti SDK necessari saranno installati automaticamente.

    • Su Linux, non utilizzare un SDK di Android fornito dai repository della propria distribuzione perché spesso risulta obsoleto.

    • Su macOS, non utilizzare un SDK di Android fornito da Homebrew poiché non sarà installato in una posizione unificata.

  • Gradle (sarà scaricato e installato automaticamente se manca).

  • JDK 17 (OpenJDK o Oracle JDK).

    • È possibile scaricare una build da Adoptium.

Vedi anche

Per ottenere il codice sorgente di Godot per la compilazione, consultare Getting the source.

Per una panoramica generale sull'utilizzo di SCons per Godot, consultare Introduction to the buildsystem.

Setting up the buildsystem

  • Impostare la variabile d'ambiente ANDROID_HOME in modo che punti all'SDK di Android. Se sono già stati scaricati gli strumenti da riga di comando di Android, questa sarà la cartella in cui è stato estratto il contenuto dell'archivio ZIP.

    • Windows: Press Windows + R, type "control system", then click on Advanced system settings in the left pane, then click on Environment variables on the window that appears.

    • Linux o macOS: aggiungere il testo export ANDROID_HOME="/path/to/android-sdk" al proprio file .bashrc o .zshrc dove /path/to/android-sdk punta alla radice delle cartelle dell'SDK.

  • Installare i componenti necessari dell'SDK in questa cartella:

    • Accettare le licenze dei componenti SDK eseguendo il seguente comando, dove android_sdk_path è il percorso all'SDK di Android, quindi rispondere a tutti i messaggi con y:

    cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> --licenses

    • Completare la configurazione eseguendo il seguente comando, dove android_sdk_path è il percorso all'SDK di Android.

    cmdline-tools/latest/bin/sdkmanager --sdk_root=<android_sdk_path> "platform-tools" "build-tools;34.0.0" "platforms;android-34" "cmdline-tools;latest" "cmake;3.10.2.4988404" "ndk;23.2.8568313"

  • Dopo aver configurato l'SDK e le variabili d'ambiente, assicurarsi di riavviare il terminale per applicare le modifiche. Se si utilizza un IDE con terminale integrato, è necessario riavviarlo.

  • Esegui scons platform=android. Se questo fallisce, tornare indietro e controllare i passaggi. Se la configurazione è stata completata correttamente, il download dell'NDK inizierà. Se si sta provando a compilare GDExtension, è necessario prima compilare il motore per scaricare l'NDK, dopodiché sarà possibile compilare GDExtension.

Building the export templates

Godot necessita di tre modelli di esportazione per Android: il modello di "rilascio" ottimizzato (android_release.apk), il modello di debug (android_debug.apk) e il modello di build Gradle (android_source.zip). Poiché Google richiede che tutti gli APK includano librerie ARMv8 (64 bit) da agosto 2019, i comandi seguenti creano modelli di build contenenti sia librerie ARMv7 sia ARMv8.

La compilazione dei modelli di esportazione standard è eseguita chiamando SCons dalla cartella radice di Godot con i seguenti argomenti:

  • Modello di rilascio (utilizzato durante l'esportazione con l'opzione Debug abilitato deselezionata)

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64 generate_apk=yes

  • Modello di debug (utilizzato durante l'esportazione con Debug abilitato selezionato)

scons platform=android target=template_debug arch=arm32
scons platform=android target=template_debug arch=arm64 generate_apk=yes

  • (Facoltativo) Modello di sviluppo (utilizzato per risolvere problemi)

scons platform=android target=template_debug arch=arm32 dev_build=yes
scons platform=android target=template_debug arch=arm64 dev_build=yes generate_apk=yes

I modelli risultanti saranno inseriti nella cartella bin:

  • bin/android_release.apk per il modello di rilascio

  • bin/android_debug.apk per il modello di debug

  • bin/android_dev.apk per il modello di sviluppo

  • bin/android_source.zip per il modello di build Gradle

Nota

  • If you are changing the list of architectures you're building, remember to add generate_apk=yes to the last architecture you're building, so that the template files are generated after the build.

  • Per includere i simboli di debug nei modelli generati, aggiungere il parametro debug_symbols=yes al comando SCons.

Vedi anche

If you want to enable Vulkan validation layers, see Vulkan validation layers on Android.

Aggiungere supporto per i dispositivi x86

Se si desidera includere anche il supporto per dispositivi x86 e x86_64, eseguire il comando SCons una terza e una quarta volta con gli argomenti arch=x86_32 e arch=x86_64 prima di compilare l'APK con Gradle. Ad esempio, per il modello di rilascio:

scons platform=android target=template_release arch=arm32
scons platform=android target=template_release arch=arm64
scons platform=android target=template_release arch=x86_32
scons platform=android target=template_release arch=x86_64 generate_apk=yes

This will create template binaries that works on all platforms. The final binary size of exported projects will depend on the platforms you choose to support when exporting; in other words, unused platforms will be removed from the binary.

Pulizia dei modelli di esportazione generati

È possibile utilizzare i seguenti comandi per rimuovere i modelli di esportazione generati:

cd platform/android/java
# On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

Utilizzare i modelli di esportazione

Godot needs release and debug binaries that were compiled against the same version/commit as the editor. If you are using official binaries for the editor, make sure to install the matching export templates, or build your own from the same version.

Quando viene esportato il proprio gioco, Godot usa i modelli come base e ne aggiorna il contenuto secondo le necessità.

Installare i modelli

I modelli nuovamente compilati (android_debug.apk, android_release.apk e android_source.zip) si devono copiare nella cartella dei modelli di Godot con i rispettivi nomi. La cartella dei modelli si trova in:

  • Windows: %APPDATA%\Godot\export_templates\<version>\

  • Linux: $HOME/.local/share/godot/export_templates/<version>/

  • macOS: $HOME/Library/Application Support/Godot/export_templates/<version>/

<version> ha il formato major.minor[.patch].status e utilizza i valori di version.py nel proprio repository sorgente di Godot (ad esempio 4.1.3.stable o 4.2.dev). È necessario anche scrivere la stessa stringa di versione in un file version.txt situato accanto ai propri modelli di esportazione.

However, if you are writing your custom modules or custom C++ code, you might instead want to configure your template binaries as custom export templates here:

../../../_images/andtemplates.png

You don't even need to copy them, you can just reference the resulting file in the bin\ directory of your Godot source folder, so that the next time you build you will automatically have the custom templates referenced.

Compilare l'editor di Godot

La compilazione dell'editor avviene chiamando SCons dalla cartella radice di Godot con i seguenti argomenti:

scons platform=android arch=arm32 production=yes target=editor
scons platform=android arch=arm64 production=yes target=editor
scons platform=android arch=x86_32 production=yes target=editor
scons platform=android arch=x86_64 production=yes target=editor generate_apk=yes

  • È possibile aggiungere il parametro dev_build=yes per generare una compilazione di sviluppo dell'editor Godot.

  • È possibile aggiungere il parametro debug_symbols=yes per includere i simboli di debug nella build generata.

  • È possibile ignorare determinate architetture, a seconda del dispositivo di destinazione, per velocizzare la compilazione.

Ricorda di aggiungere generate_apk=yes all'ultima architettura che si sta creando, in modo che i file binari vengano generati dopo la build.

I file binari risultanti si troveranno in bin/android_editor_builds/.

Rimuovere i binari dell'editor

Puoi utilizzare i seguenti comandi per rimuovere gli eseguibili generati dell'editor:

 cd platform/android/java
 # On Windows
.\gradlew clean
# On Linux and macOS
./gradlew clean

Installare l'APK dell'editor di Godot

Con un dispositivo Android con le Opzioni per sviluppatori abilitate, collegare il dispositivo Android al computer tramite il cavo di ricarica a una porta USB/USB-C. Aprire un terminale o un prompt dei comandi e, dalla cartella principale, eseguire i seguenti comandi con i seguenti argomenti:

adb install ./bin/android_editor_builds/android_editor-release.apk

Risoluzione dei problemi

La piattaforma non appare in SCons

Verificare di aver impostato la variabile d'ambiente ANDROID_HOME. Questo è necessario affinché la piattaforma appaia nell'elenco delle piattaforme rilevate da SCons. Consultare Configurazione del buildsystem per ulteriori informazioni.

Applicazione non installata

Android potrebbe segnalare che l'applicazione non è installata correttamente. In tal caso:

  • Verificare che il keystore di debug sia generato correttamente.

  • Verificare che l'eseguibile jarsigner provenga da JDK 8.

Se il problema persiste, aprire una riga di comando ed eseguire logcat:

adb logcat

Successivamente controlla l'output durante l'installazione dell'applicazione; il messaggio di errore dovrebbe apparire lì. Chiedere aiuto se non si capisce.

L'applicazione si ferma immediatamente

Se l'applicazione viene eseguita ma termina immediatamente, ciò potrebbe essere dovuto a una delle seguenti ragioni:

  • Assicurarsi di utilizzare modelli di esportazione che corrispondano alla versione del proprio editor; se si utilizza una nuova versione di Godot, è necessario aggiornare anche i modelli.

  • libgodot_android.so non si trova in libs/<arch>/ dove <arch> è l'architettura del dispositivo.

  • L'architettura del dispositivo non corrisponde a quella esportata. Assicurarsi che i modelli siano stati creati per l'architettura di quel dispositivo e che le impostazioni di esportazione includano il supporto per quell'architettura.

In qualunque caso, adb logcat dovrebbe mostrare anche la causa dell'errore.