iOS-Asset-Kataloge auf einem Cloud-Mac mit actool vorprüfen

Ein einziger unbelegter Icon-Slot fällt oft erst auf, wenn die vollständige Archivierung beinahe abgeschlossen ist. In einer iOS-Pipeline auf einem Cloud-Mac wurden dann bereits Abhängigkeiten aufgelöst, Quellcode kompiliert und Tests ausgeführt, bevor der Vorgang wegen eines Metadatenfehlers in Assets.xcassets scheitert. Effizienter ist es, das intern von Xcode aufgerufene actool als eigenständige Vorprüfung auszuführen, damit Ressourcenfehler bereits zu Beginn der Pipeline erkannt werden.

Zuerst klären, was eine actool-Vorprüfung leisten kann

actool liest Asset-Kataloge ein und kompiliert deren Ressourcen anhand von Plattform, Deployment Target und Gerätetyp. Als eigenständiger Schritt erkennt es unter anderem ungültige Contents.json-Dateien, Bild-Slots mit fehlenden Dateien, unbekannte Attribute, doppelte Namen sowie AppIcon-Konfigurationen, die nicht zur Zielplattform passen.

Einen vollständigen Build ersetzt die Vorprüfung nicht. Verweise im Quellcode auf nicht vorhandene Ressourcennamen, unterschiedliche Asset-Kataloge für verschiedene Targets oder Build-Einstellungen, die den AppIcon-Namen überschreiben, werden möglicherweise weiterhin erst bei xcodebuild sichtbar. Eine sinnvolle Reihenfolge für die Pipeline ist:

Die Vorprüfung soll nicht Xcode vollständig nachbilden. Sie soll eindeutige Ressourcenfehler mit klar erkennbarem Lösungsweg möglichst früh abfangen.

Toolchain und Eingabeparameter fest vorgeben

Prüfen Sie zunächst, welche Xcode-Version der aktuelle Job tatsächlich verwendet. Gehen Sie nicht davon aus, dass ein interaktives Terminal und der CI-Prozess dasselbe Entwicklerverzeichnis nutzen.

xcode-select -p
xcodebuild -version
xcrun --find actool
xcrun actool --version

Wenn auf einem Knoten mehrere Xcode-Versionen installiert sind, sollte DEVELOPER_DIR am Einstiegspunkt des Jobs ausdrücklich gesetzt und die Ausgabe von xcodebuild -version in das Build-Protokoll geschrieben werden. Plattform, minimale Systemversion, Gerätetyp und AppIcon-Name im Skript müssen ebenfalls mit den Build-Einstellungen des Projekts übereinstimmen. Andernfalls belegt eine erfolgreiche Vorprüfung lediglich, dass der Katalog mit einem anderen Parametersatz kompiliert werden kann – nicht, dass er für das tatsächliche Target geeignet ist.

Prüfen Sie vor dem Aufruf von actool zusätzlich alle JSON-Dateien im Verzeichnis mit einem einfachen Lint-Schritt:

find App/Assets.xcassets -name Contents.json -print0 |
while IFS= read -r -d '' file; do
  plutil -lint "$file"
done

Damit lassen sich Überreste von Merge-Konflikten, überzählige Zeichen am Dateiende und beschädigte Dateien präzise dem jeweiligen Pfad zuordnen.

Ein direkt in CI ausführbares Skript erstellen

Das folgende Skript schreibt sämtliche Ausgaben nach .ci-artifacts/actool und bewahrt bei einem Fehler die vollständige Diagnose auf, sodass CI sie als Artefakt erfassen kann. Verzeichnis, Deployment Target und AppIcon-Name sollten als Parameter oder über die Projektkonfiguration übergeben werden. Vermeiden Sie mehrere separat gepflegte Kopien des Skripts.

#!/bin/bash
set -euo pipefail

CATALOG="${1:-App/Assets.xcassets}"
DEPLOYMENT_TARGET="${DEPLOYMENT_TARGET:-16.0}"
APP_ICON_NAME="${APP_ICON_NAME:-AppIcon}"
OUT=".ci-artifacts/actool"

rm -rf "$OUT"
mkdir -p "$OUT/compiled"
export LANG=en_US.UTF-8

if ! xcrun actool "$CATALOG" \
  --compile "$OUT/compiled" \
  --platform iphoneos \
  --minimum-deployment-target "$DEPLOYMENT_TARGET" \
  --target-device iphone \
  --app-icon "$APP_ICON_NAME" \
  --output-partial-info-plist "$OUT/partial-info.plist" \
  --notices --warnings --errors \
  >"$OUT/actool.log" 2>&1; then
  cat "$OUT/actool.log"
  exit 1
fi

cat "$OUT/actool.log"
plutil -lint "$OUT/partial-info.plist"

set -euo pipefail verhindert, dass die Pipeline nach einem fehlgeschlagenen Befehl weiterläuft. Das Protokoll wird zuerst in eine Datei geschrieben und anschließend ausgegeben, damit sowohl der Exit-Code als auch die Diagnose erhalten bleiben. Wird der Befehl direkt an eine komplexe Pipeline angehängt, besteht die Gefahr, versehentlich nur den Status des letzten Befehls auszuwerten.

Warnungen und typische Fehlinterpretationen behandeln

Nicht sofort jede Warnung als Fehler behandeln

Ältere Projekte enthalten möglicherweise nicht zugewiesene Gerätevarianten, ungenutzte Bildsets oder Hinweise zur Benennung. Bei der ersten Einführung sollte das Protokoll gespeichert und eine Ausgangsbasis erstellt werden. Erst danach sollten eindeutig reproduzierbare Probleme den Build blockieren. Wenn jede Zeile mit warning: sofort einen Fehler auslöst, wird das Team die Prüfung meist eher deaktivieren, als die Ressourcen zu bereinigen.

Ungültiges JSON, fehlende Ressourcendateien, fehlende erforderliche AppIcon-Slots und doppelte Namen sollten unmittelbar blockieren. Hinweise auf ungenutzte Ressourcen können zunächst gezählt werden. Nach einer festgelegten Bereinigungsfrist lassen sich die Regeln schrittweise verschärfen.

Simulator- und Geräteplattform unterscheiden

Eine erfolgreiche Vorprüfung ausschließlich mit iphonesimulator garantiert nicht, dass auch iphoneos akzeptiert wird. Geräteanforderungen, Icon-Regeln und Artefaktformen können zu unterschiedlichen Diagnosen führen. Wenn die Pipeline beide Zielarten baut, sollte die Prüfung zweimal mit getrennten Ausgabeverzeichnissen ausgeführt werden, damit der zweite Lauf die Ergebnisse des ersten nicht überschreibt.

Für Targets mit iPad-Unterstützung muss außerdem das entsprechende --target-device ipad ergänzt werden. Geben Sie nicht ausschließlich iphone an, nur damit die Prüfung erfolgreich ist. Die Geräteliste muss der tatsächlichen Konfiguration des Targets entsprechen.

In die Pipeline integrieren und das Ergebnis abnehmen

Die Vorprüfung muss nicht erst nach der Installation von Abhängigkeiten ausgeführt werden, da actool normalerweise nur Xcode und die im Repository enthaltenen Ressourcen benötigt. Besser ist eine Position direkt nach dem Checkout und vor der Auflösung von Abhängigkeiten. So werden Ressourcenfehler auch dann schnell gemeldet, wenn ein Paketverwaltungsdienst vorübergehend langsam reagiert.

Bereiten Sie für die erste Einführung drei Fehlerszenarien vor: Beschädigen Sie eine Contents.json, verschieben Sie vorübergehend eine referenzierte Icon-Datei und ändern Sie den AppIcon-Namen in einen nicht vorhandenen Wert. Prüfen Sie, dass jeder Job mit einem Status ungleich null endet, das Protokoll das konkrete Verzeichnis nennt und .ci-artifacts/actool vom System gespeichert wird. Stellen Sie anschließend die Dateien wieder her und verifizieren Sie, dass sowohl die Vorprüfung als auch der vollständige Build erfolgreich sind.

Enthält das Repository mehrere App-Targets, sollten Sie eine Liste aus „Target, Ressourcenverzeichnis, Plattform und AppIcon-Name“ pflegen und die Einträge einzeln durchlaufen. Übergeben Sie nicht sämtliche Verzeichnisse auf einmal an denselben Befehl. So lässt sich jede Fehlermeldung direkt dem zuständigen Modul zuordnen, und die Parameter eines Targets können Probleme in einem anderen Target nicht verdecken.

Behalten Sie letztlich zwei Prüfstufen bei: actool erkennt schnell eindeutige Fehler im Ressourcenverzeichnis, während der vollständige Xcode-Build die Target-Integration und das endgültige Artefakt validiert. Mit dieser klaren Aufgabenteilung werden Ressourcenprobleme früher sichtbar, und die Fehlerprotokolle verweisen genauer auf die tatsächlich zu korrigierende Stelle.

Häufig gestellte Fragen