Drift bei Xcode-Build-Einstellungen prüfen

Derselbe Commit lässt sich auf einem Entwicklungsrechner problemlos archivieren, verwendet auf einem HexVM Cloud-Mac jedoch plötzlich ein anderes Deployment-Target oder baut eine Architektur nicht mehr mit. Die Ursache liegt häufig nicht im Quellcode, sondern in den Build-Einstellungen, die Xcode letztlich auflöst. Projektdateien, .xcconfig-Dateien, Umgebungsvariablen und Kommandozeilenargumente überschreiben sich schichtweise. Wer nur eine dieser Quellen prüft, kann daher kaum sicher feststellen, welche Konfiguration ein Target tatsächlich verwendet.

Eine solche Drift führt nicht zwangsläufig sofort zu einem Fehler. Sie kann zunächst nur das Build-Artefakt verändern und erst bei der Veröffentlichung auffallen. Robuster ist es, eine bereinigte Baseline der effektiven Einstellungen zu speichern und sie vor jedem Merge sowie vor jedem produktiven Archiv neu zu erzeugen und zu vergleichen.

Zu prüfende Konfigurationsoberfläche festlegen

Speichern Sie nicht einfach die vollständige Ausgabe von xcodebuild. Absolute Pfade, temporäre Verzeichnisse und Build-Nummern erzeugen zahlreiche bedeutungslose Unterschiede. Teilen Sie die Einstellungen zunächst in drei Kategorien ein.

Kategorie	Typische Schlüssel	Behandlung
Artefaktgrenzen	`PRODUCT_BUNDLE_IDENTIFIER`, `SUPPORTED_PLATFORMS`, `ARCHS`	Jede Änderung prüfen
Compilerverhalten	`SWIFT_VERSION`, `SWIFT_OPTIMIZATION_LEVEL`, `GCC_PREPROCESSOR_DEFINITIONS`	Jede Änderung prüfen
Knotenspezifisches Rauschen	`BUILD_DIR`, `TEMP_DIR`, `PROJECT_TEMP_DIR`	Entfernen oder normalisieren

Einstellungen für die Codesignierung gehören ebenfalls in die Baseline. Zertifikatsdateien, Inhalte privater Schlüssel und temporäre Zugangsdaten dürfen jedoch nicht im Repository gespeichert werden. Geprüft werden sollen Konfigurationsnamen, Signierungsmodi und Berechtigungsgrenzen—not sensible Materialien kopiert werden.

Eine Baseline ist keine Konfigurationsdatei, die sich „niemals ändern darf“. Sie beschreibt einen erwarteten Zustand, der einem Code-Review unterliegt: Änderungen sind zulässig, müssen aber sichtbar, nachvollziehbar und rückgängig zu machen sein.

Effektive Einstellungen des Targets exportieren

Legen Sie zunächst Projekt, Scheme, Build-Konfiguration und Zielplattform eindeutig fest. Ersetzen Sie bei einem Workspace-Projekt -project durch -workspace; alle übrigen Argumente bleiben unverändert.

mkdir -p .ci/build-settings

xcodebuild \
  -project App.xcodeproj \
  -scheme App \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -showBuildSettings \
  > .ci/build-settings/raw.txt

Prüfen Sie vor der Ausführung mit xcodebuild -list -project App.xcodeproj, ob das Scheme freigegeben ist. Übergibt die Pipeline zusätzliche Argumente, etwa Feature-Schalter oder ein benutzerdefiniertes SYMROOT, müssen beim Erzeugen der Baseline und beim eigentlichen Build dieselben Argumente verwendet werden. Andernfalls werden zwei unterschiedliche Kontexte miteinander verglichen.

Projekte mit mehreren Targets geben mehrere Gruppen gleichnamiger Schlüssel aus. Entfernen Sie Duplikate daher nicht pauschal. Behalten Sie die Target-Überschriften bei, oder legen Sie für jedes Scheme eine separate Datei an. App-, Erweiterungs- und Test-Targets können berechtigterweise unterschiedliche Deployment-Bereiche haben.

Pfadrauschen bereinigen und eine stabile Baseline erzeugen

Das folgende Skript extrahiert Zeilen im Format KEY = VALUE, entfernt Schlüssel für temporäre Verzeichnisse und ersetzt das Arbeits- sowie das Benutzerverzeichnis durch stabile Platzhalter. Es analysiert keine geheimen Schlüssel und gibt auch nicht den vollständigen Satz von Umgebungsvariablen aus.

from pathlib import Path
import os

source = Path(".ci/build-settings/raw.txt")
target = Path(".ci/build-settings/current.txt")

ignored = {
    "BUILD_DIR",
    "BUILD_ROOT",
    "CONFIGURATION_BUILD_DIR",
    "DERIVED_FILES_DIR",
    "PROJECT_TEMP_DIR",
    "TARGET_TEMP_DIR",
    "TEMP_DIR"
}

root = str(Path.cwd())
home = str(Path.home())
rows = []

for line in source.read_text().splitlines():
    stripped = line.strip()
    if " = " not in stripped:
        continue
    key, value = stripped.split(" = ", 1)
    if key in ignored:
        continue
    value = value.replace(root, "<ROOT>").replace(home, "<HOME>")
    rows.append(f"{key}={value}")

target.write_text("
".join(sorted(rows)) + "
")

Nachdem Sie das erste Ergebnis geprüft haben, kopieren Sie current.txt in eine nach ihrem Zweck benannte Baseline, beispielsweise release-ios.txt, und committen Sie diese in das Repository.

python3 .ci/normalize_build_settings.py
cp .ci/build-settings/current.txt \
   .ci/build-settings/release-ios.txt

Falls sich Abhängigkeitspfade weiterhin häufig ändern, prüfen Sie zuerst, ob sie die Compiler-Eingaben beeinflussen. Filtern Sie HEADER_SEARCH_PATHS, FRAMEWORK_SEARCH_PATHS oder OTHER_SWIFT_FLAGS nicht nur deshalb heraus, um ein Ergebnis „ohne Unterschiede“ zu erhalten. Änderungen an diesen Schlüsseln sind häufig genau die Probleme, die erkannt werden sollen.

Unterschiede als Pipeline-Gate durchsetzen

Die Prüfung sollte nach dem Auflösen der Abhängigkeiten, aber vor dem produktiven Archivieren ausgeführt werden. Dadurch stehen vollständige Suchpfade zur Verfügung, während eine fehlerhafte Konfiguration noch vor dem aufwendigen Archivierungsschritt gestoppt werden kann.

set -euo pipefail

xcodebuild \
  -project App.xcodeproj \
  -scheme App \
  -configuration Release \
  -destination 'generic/platform=iOS' \
  -showBuildSettings \
  > .ci/build-settings/raw.txt

python3 .ci/normalize_build_settings.py

diff -u \
  .ci/build-settings/release-ios.txt \
  .ci/build-settings/current.txt

Gibt diff einen Status ungleich null zurück, sollte die Pipeline angehalten und die Differenzausgabe aufbewahrt werden. Überschreiben Sie die Baseline nicht automatisch mit der neuen Datei, da das Gate sonst zu einem bloßen Protokollierungsmechanismus verkommt.

Positivliste für Einstellungen definieren

Teams können eine explizite Ignorierliste für nachweislich unbedenkliche Schlüssel pflegen. Diese Liste muss jedoch kurz bleiben und für jeden Eintrag eine Begründung enthalten. Die folgenden Änderungen sollten die Pipeline weiterhin blockieren:

IPHONEOS_DEPLOYMENT_TARGET und SUPPORTED_PLATFORMS
ARCHS, EXCLUDED_ARCHS und ONLY_ACTIVE_ARCH
SWIFT_VERSION und Optimierungsstufen
CODE_SIGN_STYLE und die Methode zur Auswahl der Signierungsidentität
PRODUCT_BUNDLE_IDENTIFIER und der Pfad zur Entitlements-Datei
DEBUG_INFORMATION_FORMAT und Linker-Argumente

Häufige Fehlalarme und echte Drift untersuchen

Wenn bei jeder Ausführung umfangreiche Pfadunterschiede auftreten, prüfen Sie zunächst, ob das Ersetzen des Stammverzeichnisses auch Pfade nach der Auflösung symbolischer Links erfasst. Zeichnen Sie zu Beginn des Jobs pwd -P auf, und lassen Sie das Skript sowohl den logischen als auch den physischen Pfad normalisieren.

Falls lokal keine Unterschiede auftreten, die Cloud-Ausführung jedoch fortlaufend Abweichungen meldet, prüfen Sie der Reihe nach: Wird dasselbe Scheme verwendet? Stimmen die Konfigurationsnamen überein? Werden Einstellungen über die Kommandozeile ergänzt? Ist die Auflösung der Abhängigkeiten abgeschlossen? Fließen Umgebungsvariablen in die Expansion der .xcconfig-Dateien ein? Ändern Sie nicht zuerst die Baseline, nur um sie an das Ergebnis anzupassen.

Wenn eine echte Änderung auftritt, ermitteln Sie zunächst ihre Quelle und aktualisieren Sie erst danach die Baseline:

Ermitteln Sie mit xcodebuild -showBuildSettings, zu welchem Target die Änderung gehört.
Suchen Sie in der Projektdatei, den .xcconfig-Dateien und den Pipeline-Argumenten nach dem entsprechenden Schlüssel.
Dokumentieren Sie den Zweck der Änderung und ihre Auswirkungen auf Debug und Release.
Validieren Sie die Änderung mit einem sauberen Build und einer Archivierung.
Nehmen Sie die Konfigurationsänderung und die Aktualisierung der Baseline in dasselbe Review auf.

Einen nachhaltigen Prüfzyklus etablieren

Teilen Sie Konfigurations-Baselines nach Scheme, Build-Konfiguration und Plattform auf, statt alle Szenarien mit einer einzigen Datei abzudecken. Bei alltäglichen Commits kann die Release-Baseline der Haupt-App geprüft werden. Führen Sie die entsprechenden Prüfungen zusätzlich aus, wenn Erweiterungen, Test-Bundles oder der Veröffentlichungsprozess betroffen sind.

Nach jeder Änderung der Xcode-Versionsstrategie sollten die Einstellungen neu erzeugt und einzeln geprüft werden, da sich Standardwerte geändert haben können. Entscheidend ist nicht die Anzahl der Unterschiede, sondern welche davon Compiler-Eingaben, Artefaktstruktur, Signierungsgrenzen oder Deployment-Targets verändern. Mit dieser Nachweiskette müssen Build-Fehler nicht mehr durch Vermutungen über die gesamte Maschine untersucht werden, und Konfigurationsänderungen lassen sich ebenso zuverlässig verfolgen wie Änderungen am Quellcode.

Häufig gestellte Fragen

Warum reicht ein Vergleich von Projektdatei und xcconfig nicht aus?

Beide zeigen nur Eingaben. Die Ausgabe von xcodebuild enthält zusätzlich Vererbung, bedingte Werte und Befehlszeilenüberschreibungen und bildet damit die wirksame Konfiguration ab.

Welche Änderungen sollten die Pipeline stoppen?

Änderungen an Deployment-Ziel, Architekturen, Swift-Version, Optimierungsstufe, Signierungsmodus und Produktkennung sollten in der Regel stoppen. Temporäre Pfade werden vorher normalisiert.