XGRIDSDokumentation

Entwicklungsanleitung für Kompilierung und Paketierung auf iOS-Geräten

Hintergrund

Das LCC Unity SDK wird in Form vorkompilierter DLLs veröffentlicht. Da die iOS-Plattform erfordert, dass native Plugins als statische Bibliotheken (__Internal) statt dynamisch (dlopen) geladen werden, müssen Sie die in diesem Dokument beschriebenen zusätzlichen Konfigurationsschritte abschließen, bevor Sie eine iOS-Anwendung erstellen. Beim Laden nativer Plugins gibt es einen grundlegenden Unterschied zwischen iOS und anderen Plattformen; andere Plattformen (Windows, macOS, Android, Linux) erfordern keine zusätzlichen Operationen.

Dieses SDK verwendet "libwebp" als P/Invoke-Ziel, wenn es in eine DLL kompiliert wird. Das eingebaute Skript Editor/RewriteWebpDllImport.cs des SDK schreibt es während iOS-Builds automatisch in "__Internal" um, wodurch sichergestellt wird, dass IL2CPP die korrekten direkten Symbolaufrufe erzeugt.

Hinweis:

Wenn Sie eine iOS-Geräteanwendung kompilieren, benennen Sie zuerst Editor/RewriteWebpDllImport.txt im SDK-Paket in Editor/RewriteWebpDllImport.cs um, damit das Skript wirksam wird. Alternativ können Sie direkt die Dateierweiterung des Skripts im SDK-Paket ändern und es in das Verzeichnis Assets/Editor/ des Projekts kopieren.

Voraussetzungen

Das Skript RewriteWebpDllImport.cs verwendet während des Builds die IL-Rewriting-Bibliothek Mono.Cecil, daher müssen Sie sie zuerst als Abhängigkeit zum Projekt hinzufügen. Es gibt zwei Möglichkeiten; wählen Sie eine davon.

Methode 1: Über den Package Manager hinzufügen (empfohlen)

Öffnen Sie die Unity-Menüleiste Window → Package Manager, klicken Sie auf die Schaltfläche + in der oberen linken Ecke, wählen Sie Add package by name..., geben Sie den Namen com.unity.nuget.mono-cecil ein, geben Sie die Version 1.11.5 ein, klicken Sie auf Add und warten Sie, bis der Package Manager die Installation abgeschlossen hat, wie unten dargestellt.

Die Mono.Cecil-Abhängigkeit im Package Manager nach Namen hinzufügen

com.unity.nuget.mono-cecil im Package Manager nach Namen hinzufügen

Methode 2: manifest.json manuell bearbeiten

Bearbeiten Sie direkt die Datei Packages/manifest.json des Projekts und fügen Sie unter dependencies eine Zeile hinzu:

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

Wechseln Sie nach dem Speichern zurück zu Unity; der Editor löst die Abhängigkeit automatisch auf und installiert sie.

Build-Ablauf

Führen Sie nach Abschluss der Voraussetzungskonfiguration den standardmäßigen iOS-Build-Ablauf aus; RewriteWebpDllImport greift während des Builds automatisch ein.

  1. Benennen Sie Editor/RewriteWebpDllImport.txt in Editor/RewriteWebpDllImport.cs um (falls nicht bereits umbenannt).
  2. Wählen Sie in der Unity-Menüleiste File → Build Settings, wählen Sie in der Plattformliste iOS und klicken Sie auf Switch Platform.
  3. Klicken Sie auf Build (oder Build And Run), wählen Sie ein Ausgabeverzeichnis und erzeugen Sie das Xcode-Projekt.
  4. Während des Builds schreibt das Skript automatisch alle DllImport-Einträge im SDK, die auf "libwebp" zielen, in "__Internal" um. Nach einem erfolgreichen Build gibt die Konsole ein Protokoll aus, das etwa so aussieht:
[RewriteWebpDllImport] 77 P/Invoke-Einträge von "libwebp" in "__Internal" umgeschrieben.
  1. Öffnen Sie das erzeugte Projekt mit Xcode und bestätigen Sie unter Build Phases → Link Binary With Libraries des Targets, dass libwebp.a, libwebpdemux.a und libsharpyuv.a verknüpft sind.
  2. Schließen Sie das iOS-Gerät an, signieren Sie und führen Sie es in Xcode aus.

Hinweis:

Wenn das Protokoll [RewriteWebpDllImport] nicht in der Konsole erscheint, bedeutet dies in der Regel, dass das Skript nicht wirksam wurde — bestätigen Sie, dass die Dateierweiterung von .txt in .cs geändert wurde und dass die Mono.Cecil-Abhängigkeit korrekt installiert ist.

Fehlerbehebung

FehlermeldungUrsacheLösung
Unable to load DLL 'libwebp'Das Skript wurde nicht wirksam, und DllImport zeigt weiterhin auf den Namen der dynamischen BibliothekBestätigen, dass RewriteWebpDllImport.txt in .cs umbenannt wurde, neu bauen und das Konsolenprotokoll prüfen
Cannot find LCCSDK.dll in staging areaDie Haupt-DLL des SDK wurde während des Builds nicht gefunden, und das Rewrite-Ziel fehltBestätigen, dass das SDK korrekt in das Projekt importiert wurde und die DLL nicht durch Exclude Platform von iOS ausgeschlossen ist
Mono.Cecil-bezogene Kompilierungsfehler (der Namespace Mono.Cecil kann nicht gefunden werden)Nicht installiert oder VersionskonfliktGemäß „Voraussetzungen“ com.unity.nuget.mono-cecil@1.11.5 hinzufügen und warten, bis der Compiler die Abhängigkeit erneut auflöst

Hinweise

  • Es wird empfohlen, Unity 2022.3 LTS oder höher (einschließlich Unity 6) zu verwenden; die Kompatibilität mit Mono.Cecil und IL2CPP kann bei zu alten Versionen nicht garantiert werden.
  • Wenn Sie auf dem iOS-Simulator ausführen müssen, bestätigen Sie, dass die verknüpfte statische Bibliothek den Architektur-Slice arm64-simulator enthält, andernfalls kann der Simulator nicht verknüpfen.
  • Die obige Konfiguration betrifft nur die iOS-Plattform. Die Build-Abläufe von Windows, macOS, Android und Linux sind überhaupt nicht betroffen, und es ist nicht erforderlich, das Skript umzubenennen oder die Mono.Cecil-Abhängigkeit hinzuzufügen.