Compilation avec Mono

Pré-requis

  • Mono 5.12.0 ou plus
  • MSBuild
  • NuGet
  • Sur Linux/macOS seulement : pkg-config

Vous devrez peut-être importer les certificats nécessaires pour que NuGet puisse effectuer les requêtes HTTPS.

La méthode recommandée est d'utiliser l'ensemble de certificats CA (Certificate Authorities) de curl.

Exécutez les commandes suivantes pour le télécharger et l'importer. Sous Windows, vous pouvez l'exécuter à partir de l'invite de ligne de commande de Mono (ou de l'invite normale si vous avez ajouté le répertoire bin de Mono à votre variable d'environnement PATH) :

# If using PowerShell, replace `curl` with `curl.exe` below.
curl -LO https://curl.haxx.se/ca/cacert.pem
cert-sync --user cacert.pem

Vous pouvez également utiliser la commande suivante, bien qu'elle soit obsolète et qu'elle puisse ne pas fonctionner correctement :

mozroots --import --sync

Variables d'environnement

Par défaut, SCons essaiera de trouver Mono dans le registre Windows sur Windows ou via pkg-config sur d'autres plates-formes. Vous pouvez spécifier un répertoire d'installation différent en passant l'option de ligne de commande mono_prefix à SCons ; par exemple scons [...] mono_prefix=%ProgramFiles%/Mono.

C'est le répertoire qui contient les sous-répertoires include et lib.

Activer le module Mono

Par défaut, le module Mono est désactivé lors de la construction. Pour l'activer, ajoutez l'option module_mono_enabled=yes à la ligne de commande de SCons.

Générer glue

Les sources de Glue sont les fonctions d'emballage qui seront appelées par des méthodes gérées. Ces fichiers sources doivent être générés avant de construire vos binaires définitifs. Afin de les générer, vous devez d'abord construire un binaire Godot temporaire avec les options tools=yes et mono_glue=no :

scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=no

Une fois la compilation terminée, vous devez lancer l'exécutable compilé avec le paramètre --generate-mono-glue suivi du chemin vers un répertoire de sortie. Ce chemin doit être modules/mono/glue dans le répertoire Godot :

<godot_binary> --generate-mono-glue modules/mono/glue

Cette commande indiquera à Godot de générer le fichier modules/mono/glue/mono_glue.gen.cpp et la solution C# pour l'API Godot dans modules/mono/glue/Managed/Generated. Une fois que ces fichiers sont générés, vous pouvez construire Godot pour toutes les cibles souhaitées sans avoir à répéter ce processus.

<godot_binary> fait référence au binaire d'outils que vous avez compilé ci-dessus avec le module Mono activé. Son nom exact variera en fonction de votre système et de votre configuration, mais il devrait être de la forme bin/godot.<platform>.tools.<bits>.mono, par exemple bin/godot.x11.tools.64.mono ou bin/godot.windows.tools.64.exe. Faites particulièrement attention au suffixe .mono ! Si vous avez déjà compilé Godot sans le support Mono, vous avez peut-être nommé des binaires de façon similaire sans ce suffixe. Ces binaires ne peuvent pas être utilisés pour générer Mono glue.

Notes

  • Ne construisez pas vos binaires finaux avec mono_glue=no. Cela désactive le scripting C#. Cette option ne doit être utilisée que pour le binaire temporaire qui générera glue. Godot affichera un avertissement au démarrage s'il a été construit sans les sources de glue.
  • Les sources de glue doivent être régénérées chaque fois que l'API enregistrée dans la ClassDB change. C'est le cas, par exemple, lorsqu'une nouvelle méthode est enregistrée dans l'API de scripting ou que l'un des paramètres d'une telle méthode change. Godot imprimera une erreur au démarrage s'il y a une discordance d'API entre la ClassDB et les sources glue.

Reconstruire avec Mono glue

Une fois que vous avez généré Mono glue, vous pouvez construire le binaire final avec mono_glue=yes. C'est la valeur par défaut de mono_glue, donc vous pouvez aussi l'omettre. Pour construire un éditeur avec Mono activé :

scons p=<platform> tools=yes module_mono_enabled=yes mono_glue=yes

Et des modèles d'exportation activés pour Mono :

scons p=<platform> tools=no module_mono_enabled=yes mono_glue=yes

Si tout s’est bien passé, mis à part la sortie normale, SCons aurait dû créer les fichiers suivants dans le répertoire bin :

  • Si vous ne liez pas le runtime Mono statiquement, le script de compilation placera la bibliothèque partagée du runtime Mono (monosgen-2.0) à côté du binaire Godot dans le répertoire de sortie. Assurez-vous d'inclure cette bibliothèque lorsque vous distribuez Godot. Lorsque vous ciblez Android, aucune étape supplémentaire n'est nécessaire car cette bibliothèque est automatiquement copiée sur #platform/android/java/libs et Gradle s'occupe du reste.
  • Contrairement aux compilations Godot «classiques», lors de la compilation avec le module Mono activé (et en fonction de la plateforme cible), un répertoire de données peut être créé à la fois pour l'éditeur et pour les modèles d'exportation. Ce répertoire est important pour un bon fonctionnement et doit être distribué avec Godot. Plus de détails sur ce répertoire dans  Data directory.

Exemples

Exemple (Windows)

# Build temporary binary
scons p=windows tools=yes module_mono_enabled=yes mono_glue=no
# Generate glue sources
bin\godot.windows.tools.64.mono --generate-mono-glue modules/mono/glue

### Build binaries normally
# Editor
scons p=windows target=release_debug tools=yes module_mono_enabled=yes
# Export templates
scons p=windows target=release_debug tools=no module_mono_enabled=yes
scons p=windows target=release tools=no module_mono_enabled=yes

Exemple (X11)

# Build temporary binary
scons p=x11 tools=yes module_mono_enabled=yes mono_glue=no
# Generate glue sources
bin/godot.x11.tools.64.mono --generate-mono-glue modules/mono/glue

### Build binaries normally
# Editor
scons p=x11 target=release_debug tools=yes module_mono_enabled=yes
# Export templates
scons p=x11 target=release_debug tools=no module_mono_enabled=yes
scons p=x11 target=release tools=no module_mono_enabled=yes

Répertoire de données

Le répertoire de données est une dépendance pour les binaires Godot construits avec le module Mono activé. Il contient des fichiers importants pour le bon fonctionnement de Godot. Il doit être distribué avec l'exécutable Godot.

Note

Les informations ci-dessous ne s'appliquent pas à Android, iOS et WASM, car il n'existe pas de répertoire de données pour ces plates-formes.

Exporter des modèles

Le nom du répertoire de données d'un modèle d'exportation diffère selon la configuration avec laquelle il a été créé. Le format est data.mono.<platform>.<bits>.<target>, par ex. data.mono.x11.32.release_debug ou data.mono.windows.64.release.

Ce répertoire doit être placé avec son nom d'origine à côté des modèles d'exportation Godot. Lors de l'exportation d'un projet, Godot copiera également ce répertoire avec l'exécutable du jeu mais le nom sera changé en data_<APPNAME>, où <APPNAME> est le nom de l'application tel que spécifié dans le paramètre du projet application/config/name.

Dans le cas de macOS, où le modèle d'exportation est compressé sous forme d'archive ZIP, le contenu du répertoire de données peut être placé dans les emplacements suivants à l'intérieur de l'archive ZIP :

bin/data.mono.<platform>.<bits>.<target>/Mono/lib /osx_template.app/Contents/Frameworks/GodotSharp/Mono/lib
bin/data.mono.<platform>.<bits>.<target>/Mono/etc /osx_template.app/Contents/Resources/GodotSharp/Mono/etc

Éditeur

Le nom du répertoire de données de l'éditeur Godot sera toujours GodotSharp. Le contenu de ce répertoire est le suivant :

  • Api
  • Mono (facultatif)
  • Tools

Le sous-répertoire Api contient les assemblies de l'API de Godot. Sous macOS, si l'éditeur Godot est distribué sous forme de paquet, le contenu du répertoire de données peut être placé dans les emplacements suivants :

bin/data.mono.<platform>.<bits>.<target>/Api <nom_du paquet>.app/Contents/Frameworks/GodotSharp/Api
bin/data.mono.<platform>.<bits>.<target>/Mono/lib <nom_du paquet>.app/Contents/Frameworks/GodotSharp/Mono/lib
bin/data.mono.<platform>.<bits>.<target>/Mono/etc <nom_du paquet>.app/Contents/Resources/GodotSharp/Mono/etc
bin/data.mono.<platform>.<bits>.<target>/Tools <nom_du paquet>.app/Contents/Frameworks/GodotSharp/Tools

Le sous-répertoire Mono est facultatif. Il sera nécessaire lors de la distribution de l'éditeur, car des problèmes peuvent survenir lorsque la version Mono installée par l'utilisateur n'est pas identique à celle avec laquelle l'éditeur Godot a été construit. Passez le paramètre copy_mono_root=yes à SCons lors de la compilation de l'éditeur afin de créer ce dossier et son contenu.

Le sous-répertoire Tools contient les outils requis par l'éditeur, comme les assemblies GodotTools et ses dépendances.

Construction du runtime Mono

Lorsque vous compilez Godot pour le bureau, vous utiliserez probablement le runtime Mono pré-construit qui est installé sur votre système. Ce ne sera probablement pas le cas lorsque vous visez d'autres plateformes comme Android, iOS et WebAssembly. Vous devrez construire vous-même le runtime Mono pour ces plates-formes.

Nous vous recommandons d'utiliser ces scripts de construction. Ils simplifient ce processus mais incluent également certains correctifs nécessaires au bon fonctionnement de Godot. Consultez le README sur le lien ci-dessus pour savoir comment utiliser les scripts.

Cibler Android

La compilation des modèles d'exportation Android avec Mono est un peu plus simple que pour les plateformes de bureau, car aucune étape supplémentaire n'est nécessaire après la compilation. Il n'est pas nécessaire de se soucier des dépendances telles que le répertoire de données ou la bibliothèque partagée (lors de la liaison dynamique) car ceux-ci sont automatiquement ajoutés au projet Gradle.

Une fois que vous avez compilé Mono, vous pouvez procéder à la compilation de Godot avec les instructions décrites dans cette page et la page Compiling for Android. Assurez-vous d'indiquer à SCons l'emplacement du runtime Mono que vous venez de construire : scons [...] mono_prefix="$HOME/mono-installs/android-armeabi-v7a-release" (Ce chemin peut être différent sur votre système).

Cibler iOS

Une fois que vous avez compilé Mono, vous pouvez procéder à la compilation de Godot avec les instructions décrites dans cette page et la page Compiling for iOS. Assurez-vous d'indiquer à SCons l'emplacement du runtime Mono que vous venez de construire : scons [...] mono_prefix="$HOME/mono-installs/ios-arm64-release" (Ce chemin peut être différent sur votre système).

Après avoir compilé Godot pour chaque architecture, vous remarquerez que SCons a copié les bibliothèques Mono pour chacune d'entre elles dans le répertoire de sortie :

#bin/libmono-native.iphone.<arch>.a
#bin/libmonosgen-2.0.iphone.<arch>.a
#bin/libmonoprofiler-log.iphone.<arch>.a

#bin/libmono-ilgen.iphone.<arch>.a
#bin/libmono-ee-interp.iphone.<arch>.a
#bin/libmono-icall-table.iphone.<arch>.a

Les trois derniers sont uniquement destinés aux appareils iOS et ne sont pas disponibles pour le simulateur iOS.

Ces bibliothèques doivent être mises dans des fichiers "gras" universels (multi-architecture) pour être distribuées avec les modèles d'exportation.

Le script bash suivant va créer les bibliothèques "fat" dans le répertoire #bin/ios/iphone-mono-libs :

mkdir -p bin/ios
mkdir -p bin/ios/iphone-mono-libs

lipo -create bin/libmonosgen-2.0.iphone.arm64.a bin/libmonosgen-2.0.iphone.x86_64.a -output bin/ios/iphone-mono-libs/libmonosgen-2.0.iphone.fat.a
lipo -create bin/libmono-native.iphone.arm64.a bin/libmono-native.iphone.x86_64.a -output bin/ios/iphone-mono-libs/libmono-native.iphone.fat.a
lipo -create bin/libmono-profiler-log.iphone.arm64.a bin/libmono-profiler-log.iphone.x86_64.a -output bin/ios/iphone-mono-libs/libmono-profiler-log.iphone.fat.a

# The Mono libraries for the interpreter are not available for simulator builds
lipo -create bin/libmono-ee-interp.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ee-interp.iphone.fat.a
lipo -create bin/libmono-icall-table.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-icall-table.iphone.fat.a
lipo -create bin/libmono-ilgen.iphone.arm64.a -output bin/ios/iphone-mono-libs/libmono-ilgen.iphone.fat.a

Le dossier iphone-mono-libs doit être distribué avec les modèles d'exportation. L'éditeur Godot cherchera les bibliothèques dans <templates>/iphone-mono-libs/lib<name>.iphone.fat.a.

Cibler WebAssembly

La compilation pour le WebAssembly implique actuellement le même processus, que le module Mono soit activé ou non.

Une fois que vous avez compilé Mono, vous pouvez procéder à la compilation de Godot avec les instructions décrites dans cette page et la page Compiling for the Web. Assurez-vous d'indiquer à SCons l'emplacement du runtime Mono que vous venez de construire : scons [...] mono_prefix="$HOME/mono-installs/wasm-runtime-release" (Ce chemin peut être différent sur votre système).

Bibliothèque de classe de base

Les modèles d'exportation doivent également inclure la BCL (Base Class Library) pour chaque plate-forme cible. Godot recherche le dossier BCL dans <templates>/bcl/<target_platform>, où <target_platform> est le même nom transmis à l'option SCons platform, par exemple : <templates>/bcl/windows, <templates>/bcl/javascript.

Sinon, Godot les recherchera aux endroits suivants :

Android <templates>/bcl/monodroid
iOS <templates>/bcl/monotouch
WebAssembly <templates>/bcl/wasm
Linux et macOS <templates>/bcl/net_4_x
Windows <templates>/bcl/net_4_x_win

Pour l'instant, nous supposons que le même profil BCL peut être utilisé pour Linux et MacOS, mais cela pourrait changer à l'avenir car il n'est pas garanti qu'ils soient identiques (comme c'est le cas avec le BCL de Windows).

Si la plate-forme cible est la même que la plate-forme de l'éditeur Godot, alors l'éditeur utilisera le BCL sur lequel il s'exécute (<data_folder>/Mono/lib/mono/4.5) s'il ne trouve pas le BCL dans le modèles d'exportation.

Compilateurs croisés AOT

Pour effectuer une compilation anticipée (AOT) pour d'autres plates-formes, Godot doit avoir accès aux compilateurs croisés Mono pour cette plate-forme et cette architecture.

Godot cherchera l'exécutable cross-compiler dans le dossier des compilateurs AOT. L'emplacement de ce dossier est <data_folder>/Tools/aot-compilers.

Afin de construire les compilateurs croisés, nous recommandons d'utiliser ces scripts de construction.

Après les avoir compilé, copiez l'exécutable dans le répertoire des compilateurs Godot AOT. Le nom de l'exécutable est <triple>-mono-sgen, par exemple aarch64-apple-darwin-mono-sgen.

Options de ligne de commande

Voici la liste des options de la ligne de commande disponibles lors de la construction avec le module Mono :

  • module_mono_enabled=yes | no
    • Construire Godot avec le module Mono activé.
  • mono_glue=yes | no
    • S'il faut inclure les fichiers source de glue dans la compilation et définir MONO_GLUE_DISABLED comme macro de préprocesseur.
  • mono_prefix=path
    • Chemin d'accès au répertoire d'installation de Mono pour la plate-forme et l'architecture cibles.
  • xbuild_fallback=yes | no
    • S'il faut se rabattre sur xbuild si MSBuild n'est pas disponible.
  • mono_static=yes | no
    • S'il faut lier statiquement le runtime Mono.
    • La valeur par défaut est yes pour iOS et WASM, et no pour les autres plateformes.
  • copy_mono_root=yes | no
    • Indique s'il faut copier les assemblies du framework Mono et les fichiers de configuration requis par l'éditeur Godot.