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

Compilare per macOS

Nota

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

Requisiti

Per compilare su macOS, è necessario quanto segue:

  • Python 3.9+.

  • Sistema di compilazione SCons 4.4+.

  • Xcode (o i più leggeri strumenti da riga di comando per Xcode).

  • Vulkan SDK per MoltenVK (macOS non supporta Vulkan di suo). È possibile installare rapidamente l'ultima versione di Vulkan SDK eseguendo misc/scripts/install_vulkan_sdk_macos.sh all'interno del repository sorgente di Godot.

Nota

Se Homebrew è stato installato, è possibile facilmente installare SCons tramite il seguente comando:

brew install scons

Installando Homebrew verranno recuperati automaticamente anche gli strumenti da riga di comando per Xcode, se non li si ha già.

Similmente, se MacPorts è stato installato, è possibile facilmente installare SCons tramite il seguente comando:

sudo port install scons

Vedi anche

Per ottenere il codice sorgente di Godot per la compilazione, consultare Ottenere il codice sorgente.

Per una panoramica generale sull'utilizzo di SCons per Godot, consultare Introduzione al sistema di compilazione.

Compilazione

Avviare un terminale, andare alla cartella radice del codice sorgente del motore.

Per compilare per Mac con processori Intel (x86-64), utilizzare:

scons platform=macos arch=x86_64

Per compilare per Mac con processori Apply Silicon(ARM64), utilizzare:

scons platform=macos arch=arm64

Suggerimento

Se si sta compilando Godot per apportare modifiche o contribuire al motore, si consiglia di usare le opzioni di SCons dev_build=yes o dev_mode=yes. Consultare Alias di sviluppo e produzione per maggiori informazioni.

Se tutto va bene, il file binario eseguibile risultante verrà inserito nella sottocartella bin/. Questo file eseguibile contiene l'intero motore e funziona senza alcuna dipendenza. Eseguirlo farà apparire il Gestore dei progetti.

Nota

Non è raccomandato utilizzare un eseguibile autonomo dell'editor; è sempre consigliabile inserirlo in un pacchetto .app per evitare problemi di attivazione dell'interfaccia utente.

Nota

Se si vogliono usare impostazioni separate dell'editor per le proprie build di Godot e le versioni ufficiali, è possibile abilitare Modalità autonoma creando un file chiamato ._sc_ o _sc_ nella cartella bin/.

Compilare con supporto AccessKit

AccessKit offre supporto per i lettori dello schermo.

La compilazione con AccessKit richiede di installare ulteriori dipendenze. Se si desidera saltare questo passaggio, è possibile usare l'opzione SCons accesskit=no.

È possibile installare le dipendenze richieste eseguendo python misc/scripts/install_accesskit.py nel repository sorgente di Godot. Dopo aver eseguito questo script, compilare Godot come al solito.

Nota

Facoltativamente, è possibile compilare autonomamente le librerie godot-accesskit-static seguendo i seguenti passaggi:

  1. Clonare la cartella godot-accesskit-c-static e accedervi.

  2. Eseguire il seguente comando:

cd accesskit-c
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
cmake --install build

La libreria statica AccessKit deve essere compilata attraverso lo stesso compilatore che si sta usando per compilare Godot.

Per compilare Godot con una build personalizzata di AccessKit, aggiungere accesskit_sdk_path={percorso} per indicare a SCons dove cercare le librerie AccessKit:

scons platform=macos accesskit_sdk_path=<...>

Compilare con supporto ANGLE

ANGLE fornisce un livello di traduzione da OpenGL ES 3.x a Metal e si può utilizzare per migliorare il supporto per il renderer Compatibilità su alcune vecchie GPU con driver OpenGL obsoleti.

La compilazione con ANGLE richiede di installare ulteriori dipendenze. Se si desidera saltare questo passaggio, è possibile usare l'opzione SCons angle=no.

È possibile installare le dipendenze richieste eseguendo python misc/scripts/install_angle.py nel repository sorgente di Godot. Dopo aver eseguito questo script, compilare Godot come al solito.

Nota

Facoltativamente, è possibile compilare autonomamente le librerie godot-angle-static seguendo i seguenti passaggi:

  1. Clonare la cartella godot-angle-static e accedervi.

  2. Eseguire il seguente comando:

git submodule update --init
./update_angle.sh
scons

È inoltre possibile specificare l'architettura di compilazione usando arch={architecture}.

La libreria statica ANGLE deve essere compilata attraverso lo stesso compilatore che si sta usando per compilare Godot.

Per compilare Godot con una build personalizzata di ANGLE, aggiungere angle_libs={percorso} per indicare a SCons dove cercare le librerie ANGLE:

scons platform=macos angle_libs=<...>

Creazione automatica di pacchetto .app

Per creare automaticamente un pacchetto .app come nelle build ufficiali, utilizzare l'opzione generate_bundle=yes sull'ultimo comando di SCons utilizzato per compilare l'editor:

scons platform=macos arch=x86_64
scons platform=macos arch=arm64 generate_bundle=yes

Creazione manuale del pacchetto .app

Per supportare entrambe le architetture in un singolo file binario "Universal 2", eseguire i due comandi precedenti e poi utilizzare lipo per impacchettarli insieme:

lipo -create bin/godot.macos.editor.x86_64 bin/godot.macos.editor.arm64 -output bin/godot.macos.editor.universal

Per creare un pacchetto .app, è necessario utilizzare il modello che si trova in misc/dist/macos_tools.app. In genere, per un binario dell'editor ottimizzato, compilato con dev_build=yes:

cp -r misc/dist/macos_tools.app ./bin/Godot.app
mkdir -p bin/Godot.app/Contents/MacOS
cp bin/godot.macos.editor.universal bin/Godot.app/Contents/MacOS/Godot
chmod +x bin/Godot.app/Contents/MacOS/Godot
codesign --force --timestamp --options=runtime --entitlements misc/dist/macos/editor.entitlements -s - bin/Godot.app

Nota

Se si sta compilando il ramo master, è necessario anche includere il supporto per la libreria di portabilità MoltenVK Vulkan. Di norma, verrà collegata staticamente dall'installazione dell'SDK Vulkan per macOS. È possibile anche scegliere di collegarla dinamicamente passando use_volk=yes e includendo la libreria dinamica nel pacchetto .app:

mkdir -p <Godot bundle name>.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/lib/libMoltenVK.dylib <Godot bundle name>.app/Contents/Frameworks/libMoltenVK.dylib

Eseguire una compilazione headless/server

Per eseguire in modalità headless, che fornisce funzionalità dell'editor per esportare progetti in maniera automatica, utilizzare la build normale:

scons platform=macos target=editor

E poi usa l'argomento della riga di comando --headless:

./bin/godot.macos.editor.x86_64 --headless

Per compilare una build di server di debug che si può utilizzare con strumenti di debug remoto, utilizzare:

scons platform=macos target=template_debug

Per compilare una build di server di rilascio ottimizzata per eseguire server di gioco dedicati, utilizzare:

scons platform=macos target=template_release production=yes

Compilare modelli di esportazione

Per creare modelli di esportazione per macOS, è necessario compilare tramite le destinazioni senza l'editor: target=template_release (modello di rilascio) e target=template_debug.

I modelli ufficiali sono file binari Universal 2 che supportano entrambe le architetture ARM64 e Intel x86_64.

  • Per supportare ARM64 (Apple Silicon) + Intel x86_64:

    scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64
scons platform=macos target=template_debug arch=x86_64
scons platform=macos target=template_release arch=x86_64 generate_bundle=yes

  • Per supportare solo ARM64 (Apple Silicon) (file di dimensioni inferiori, ma meno compatibile con hardware più vecchio):

    scons platform=macos target=template_debug arch=arm64
scons platform=macos target=template_release arch=arm64 generate_bundle=yes

Per creare un pacchetto .app come nelle build ufficiali, è necessario utilizzare il modello disponibile in misc/dist/macos_template.app. È possibile automatizzare questo processo attraverso l'opzione generate_bundle=yes nell'ultimo comando di SCons utilizzato per creare i modelli di esportazione (affinché si possano includere tutti i binari). Questo creerà un file godot_macos.zip in bin/ e si occuperà anche di chiamare lipo per creare un file binario Universal 2 da due file binari separati per ARM64 e x86_64 (se entrambi sono stati compilati in precedenza).

Nota

È inoltre necessario includere il supporto per la libreria di portabilità MoltenVK Vulkan. Di norma, verrà collegata staticamente dall'installazione dell'SDK Vulkan per macOS. È anche possibile scegliere di collegarla dinamicamente passando use_volk=yes e includendo la libreria dinamica nel pacchetto .app:

mkdir -p macos_template.app/Contents/Frameworks
cp <Vulkan SDK path>/macOS/libs/libMoltenVK.dylib macos_template.app/Contents/Frameworks/libMoltenVK.dylib

Nella maggior parte dei casi, è preferibile il collegamento statico, in quanto rende più facile la distribuzione. Il vantaggio principale del collegamento dinamico è che consente di aggiornare MoltenVK senza dover ricompilare i modelli di esportazione.

Se l'app è stata creata manualmente, si può comprimere la cartella macos_template.app per riprodurre il modello macos.zip dalla distribuzione ufficiale di Godot:

zip -r9 macos.zip macos_template.app

Per utilizzare i propri modelli di esportazione personalizzati, è possibile selezionare il file godot_macos.zip nelle opzioni avanzate delle preimpostazioni di esportazione:

../../../_images/mactemplates.webp

In alternativa, se si desidera che tutte le preimpostazioni usino il modello di esportazione personalizzato, è possibile rinominare il file godot_macos.zip in macos.zip e spostarlo nella posizione predefinita per i modelli di esportazione:

::

~/Library/Application Support/Godot/export_templates/<VERSIONE_GODOT>/macos.zip

Cross-compilazione per macOS da Linux

È possibile compilare per macOS in un ambiente Linux (e forse anche in Windows attraverso il sottosistema Windows per Linux). Per farlo, è necessario installare OSXCross per poter utilizzare macOS come destinazione. Prima di tutto, seguire le istruzioni per installarlo:

Clonare il repository OSXCross da qualche parte sul computer (oppure scaricare un file ZIP ed estrarlo da qualche parte), ad esempio:

git clone --depth=1 https://github.com/tpoechtrager/osxcross.git "$HOME/osxcross"

  1. Seguire le istruzioni per impacchettare l'SDK: https://github.com/tpoechtrager/osxcross#packaging-the-sdk

  2. Seguire le istruzioni per installare OSXCross: https://github.com/tpoechtrager/osxcross#installation

Dopodiché, si dovrà definire OSXCROSS_ROOT come percorso per l'installazione di OSXCross (lo stesso posto in cui è stato clonato il repository/estratto lo zip), ad esempio:

export OSXCROSS_ROOT="$HOME/osxcross"

Ora si può compilare con SCons come si farebbe normalmente:

scons platform=macos

Se si dispone di una versione di OSXCross SDK diversa da quella prevista dal buildsystem SCons, è possibile specificarne una personalizzata con l'argomento osxcross_sdk:

scons platform=macos osxcross_sdk=darwin15

Risoluzione dei problemi

Fatal error: 'cstdint' file not found

Se all'inizio si verifica un errore di compilazione di questo tipo, è probabile che sia necessario riparare l'installazione degli strumenti della riga di comando di Xcode dopo un aggiornamento di macOS o Xcode:

./core/typedefs.h:45:10: fatal error: 'cstdint' file not found
45 | #include <cstdint>
   |          ^~~~~~~~~

Eseguire questi due comandi per reinstallare gli strumenti della riga di comando di Xcode (inserire la password di amministratore se necessario):

sudo rm -rf /Library/Developer/CommandLineTools
sudo xcode-select --install

Se non funziona ancora, provare ad aggiornare Xcode dal Mac App Store e riprovare.