XGRIDSDocumentation

Guide de développement de la compilation et du packageage sur appareil iOS

Contexte

Le LCC Unity SDK est publié sous forme de DLL précompilées. Comme la plateforme iOS exige que les plugins natifs soient liés en tant que bibliothèques statiques (__Internal) plutôt que chargés dynamiquement (dlopen), vous devez effectuer les étapes de configuration supplémentaires décrites dans ce document avant de compiler une application iOS. Il existe une différence fondamentale dans les mécanismes de chargement des plugins natifs entre iOS et les autres plateformes ; les autres plateformes (Windows, macOS, Android, Linux) ne nécessitent aucune opération supplémentaire.

Ce SDK utilise "libwebp" comme cible P/Invoke lorsqu'il est compilé en DLL. Le script intégré Editor/RewriteWebpDllImport.cs du SDK le réécrit automatiquement en "__Internal" lors des compilations iOS, garantissant qu'IL2CPP génère les bons appels de symbole directs.

Remarque :

Lors de la compilation d'une application pour appareil iOS, renommez d'abord Editor/RewriteWebpDllImport.txt dans le package SDK en Editor/RewriteWebpDllImport.cs pour que le script prenne effet. Vous pouvez également modifier directement le suffixe du script dans le package SDK et le copier dans le répertoire Assets/Editor/ du projet.

Prérequis

Le script RewriteWebpDllImport.cs utilise la bibliothèque de réécriture IL Mono.Cecil pendant la compilation, vous devez donc d'abord l'ajouter comme dépendance au projet. Il existe deux façons ; choisissez l'une ou l'autre.

Méthode 1 : Ajouter via le Package Manager (recommandé)

Ouvrez la barre de menus Unity Fenêtre → Package Manager, cliquez sur le bouton + dans le coin supérieur gauche, choisissez Add package by name..., saisissez le nom com.unity.nuget.mono-cecil, saisissez la version 1.11.5, cliquez sur Ajouter, et attendez que le Package Manager finisse l'installation, comme illustré ci-dessous.

Ajouter la dépendance Mono.Cecil par nom dans le Package Manager

Ajouter com.unity.nuget.mono-cecil par nom dans le Package Manager

Méthode 2 : Modifier manuellement manifest.json

Modifiez directement le Packages/manifest.json du projet et ajoutez une ligne sous dependencies :

{
  "dependencies": {
    "com.unity.nuget.mono-cecil": "1.11.5"
  }
}

Après l'enregistrement, revenez à Unity ; l'éditeur résoudra et installera automatiquement la dépendance.

Flux de travail de compilation

Après avoir terminé la configuration préalable, suivez le flux de travail de compilation iOS standard ; RewriteWebpDllImport interviendra automatiquement pendant la compilation.

  1. Renommez Editor/RewriteWebpDllImport.txt en Editor/RewriteWebpDllImport.cs (si ce n'est pas déjà fait).
  2. Dans la barre de menus Unity, sélectionnez Fichier → Paramètres de build, sélectionnez iOS dans la liste des plateformes, et cliquez sur Switch Platform.
  3. Cliquez sur Build (ou Build And Run), sélectionnez un répertoire de sortie, et générez le projet Xcode.
  4. Pendant la compilation, le script réécrit automatiquement toutes les entrées DllImport du SDK ciblant "libwebp" en "__Internal". Après une compilation réussie, la Console affiche un journal similaire à :
[RewriteWebpDllImport] Rewrote 77 P/Invoke entries from "libwebp" to "__Internal".
  1. Ouvrez le projet généré avec Xcode, et dans Build Phases → Link Binary With Libraries de la cible, confirmez que libwebp.a, libwebpdemux.a et libsharpyuv.a sont liés.
  2. Connectez l'appareil iOS, signez et exécutez dans Xcode.

Remarque :

Si le journal [RewriteWebpDllImport] n'apparaît pas dans la Console, cela signifie généralement que le script n'a pas pris effet — confirmez que le suffixe du fichier a été changé de .txt en .cs et que la dépendance Mono.Cecil est correctement installée.

Dépannage

Message d'erreurCauseSolution
Unable to load DLL 'libwebp'Le script n'a pas pris effet, et DllImport pointe toujours vers le nom de bibliothèque dynamiqueConfirmez que RewriteWebpDllImport.txt a été renommé en .cs, recompilez et vérifiez le journal de la Console
Cannot find LCCSDK.dll in staging areaLa DLL principale du SDK n'a pas été trouvée pendant la compilation, et la cible de réécriture est manquanteConfirmez que le SDK est correctement importé dans le projet et que la DLL n'est pas exclue d'iOS par Exclude Platform
Erreurs de compilation liées à Mono.Cecil (espace de noms Mono.Cecil introuvable)Non installé ou version incompatibleAjoutez com.unity.nuget.mono-cecil@1.11.5 selon les « Prérequis » et attendez que le compilateur résolve à nouveau

Remarques

  • Il est recommandé d'utiliser Unity 2022.3 LTS ou supérieur (y compris Unity 6) ; la compatibilité avec Mono.Cecil et IL2CPP ne peut pas être garantie sur des versions trop anciennes.
  • Si vous devez exécuter sur le simulateur iOS, confirmez que la bibliothèque statique liée contient la tranche d'architecture arm64-simulator, sinon le simulateur ne peut pas lier.
  • La configuration ci-dessus n'affecte que la plateforme iOS. Les flux de travail de compilation de Windows, macOS, Android et Linux ne sont pas du tout affectés, et il n'est pas nécessaire de renommer le script ni d'ajouter la dépendance Mono.Cecil.