Scheme: Grundlagen, Konfiguration und Ausführung in Xcode

Was ist ein Scheme in Xcode?

Scheme in Xcode ist eine XML-Datei (mit der Erweiterung .xcscheme), die eine Abfolge von Aktionen und deren Parameter zum Erstellen und Analysieren einer App beschreibt. Jedes Scheme ist an ein oder mehrere Targets gebunden und legt fest, mit welcher Konfiguration (Debug, Release, AdHoc) jede Aktion ausgeführt wird. Scheme ist das Äquivalent zur Build Variant in Android, jedoch mit einer flexibleren Struktur: Ein Schema kann verschiedene Targets für verschiedene Aktionen enthalten.

Xcode erstellt automatisch ein Schema für jedes Target, wenn das Projekt zum ersten Mal geöffnet wird. Der Standardname des Schemas stimmt mit dem Namen des Targets überein. Wenn das Projekt ein Test-Target enthält, fügt Xcode es automatisch zur Test-Aktion des Schemas des Haupt-Targets hinzu. Bei Projekten mit mehreren Targets (Haupt-App + watchOS + Erweiterung) erstellt Xcode für jedes ein separates Schema, aber es kann auch ein Schema erstellt werden, das alle Targets gleichzeitig erstellt.

Schemata werden im Verzeichnis xcshareddata/xcschemes/ (für Shared) oder xcuserdata/<user>/xcschemes/ (für Private) gespeichert. Shared-Schemata gelangen in Git und werden vom gesamten Team verwendet. Private-Schemata werden lokal gespeichert und nicht synchronisiert. Die Datei .xcscheme hat ein XML-Format mit dem Wurzelelement <Scheme>. Im Inneren befinden sich Blöcke für jede Aktion: BuildAction, TestAction, LaunchAction, ProfileAction, AnalyzeAction, ArchiveAction.

Struktur der .xcscheme-Datei

.xcscheme ist eine XML-Datei, die manuell oder über Xcode bearbeitet werden kann. Die wichtigsten Elemente: <BuildAction> (Liste der zu erstellenden Targets), <TestAction> (Verweise auf Test-Targets), <LaunchAction> (Startkonfiguration), <ProfileAction>, <AnalyzeAction>, <ArchiveAction>. Jeder Block enthält das Attribut buildConfiguration, das festlegt, welche Konfiguration (Debug/Release) für die jeweilige Aktion verwendet wird.

Scheme-Aktionen: Build, Run, Test, Profile, Analyze, Archive

Scheme besteht aus sechs Aktionen, die jeweils unabhängig konfiguriert werden können. Die Build-Aktion legt fest, welche Targets in welcher Reihenfolge erstellt werden. Die Run-Aktion legt fest, wie die App gestartet wird: mit welchen Argumenten, Umgebungsvariablen und welcher Konfiguration. Die Test-Aktion legt fest, welche Tests ausgeführt und welche Code-Coverage-Optionen aktiviert werden. Die Profile-Aktion startet mit Instruments-Tools für das Profiling. Die Analyze-Aktion führt eine statische Code-Analyse mit dem Clang Static Analyzer durch. Die Archive-Aktion erstellt einen Build für die Veröffentlichung im App Store oder für die AdHoc-Verteilung.

Für jede Aktion kann eine separate Build Configuration festgelegt werden. Üblicherweise wird für Run und Test Debug und für Archive Release verwendet. Die Build Configuration definiert eine Reihe von Compiler-Flags, Optimierungen und Debug-Informationen. Xcode bietet zwei Standardkonfigurationen: Debug (ohne Optimierungen, mit Debug-Symbolen) und Release (mit Optimierungen, ohne Debug-Informationen). Der Entwickler kann über project.xcconfig eigene Konfigurationen hinzufügen.

Die Archive-Aktion ist besonders wichtig — sie erstellt ein .xcarchive, das anschließend in ein .ipa für den App Store oder AdHoc exportiert wird. Die Archive-Aktion verwendet standardmäßig die Release-Konfiguration, kann aber auf AdHoc oder Distribution umgestellt werden. In der Archive-Aktion ist auch das Flag revealArchiveInOrganizer verfügbar — nach Abschluss der Archivierung öffnet Xcode den Organizer für weitere Arbeiten mit dem Archiv.

<!-- Beispiel einer .xcscheme für eine iOS-App -->
<Scheme
  LastUpgradeVersion = "1500"
  version = "1.7">

  <BuildAction
    parallelizeBuildables = "YES"
    buildImplicitDependencies = "YES">
    <BuildActionEntries>
      <BuildActionEntry
        buildForTesting = "YES"
        buildForRunning = "YES"
        buildForProfiling = "YES"
        buildForArchiving = "YES"
        buildForAnalyzing = "YES">
        <BuildableReference
          BuildableIdentifier = "primary"
          BlueprintIdentifier = "ABCD1234"
          BuildableName = "MyApp.app"
          BlueprintName = "MyApp"
          ReferencedContainer = "container:MyApp.xcodeproj">
        </BuildableReference>
      </BuildActionEntry>
    </BuildActionEntries>
  </BuildAction>

  <LaunchAction
    buildConfiguration = "Debug"
    selectedDebuggerIdentifier = "Xcode.DebuggerFoundation.Debugger.LLDB"
    enableAddressSanitizer = "YES">
  </LaunchAction>
</Scheme>

Erstellen und Konfigurieren eines Schemes

Diagnose-Sanitizer

Ein neues Schema wird über das Xcode-Menü erstellt: Product → Scheme → New Scheme oder über die Schaltfläche "+" im Scheme-Panel (neben der Run-Schaltfläche). Beim Erstellen wird das Target ausgewählt, für das das Schema erstellt wird. Xcode kopiert automatisch die Einstellungen aus einem vorhandenen Schema, wenn es als "duplicate" ausgewählt wird. Neue Schemata werden standardmäßig als Private gespeichert — zur Veröffentlichung für das Team muss Shared in Manage Schemes aktiviert werden.

Das Fenster Edit Scheme (Product → Scheme → Edit Scheme) enthält sechs Registerkarten entsprechend der Anzahl der Aktionen. Auf jeder Registerkarte können Build Configuration, Startargumente, Umgebungsvariablen und Diagnose-Flags geändert werden. Auf der Run-Registerkarte stehen die Optionen zur Verfügung: executable (welches Binary gestartet wird), wait for executable to be launched (zum Debuggen gestarteter Prozesse), debugger (LLDB oder None), launch arguments, environment variables sowie erweiterte Optionen (Address Sanitizer, Thread Sanitizer, Main Thread Checker, Memory Management).

Für die Diagnose erkennt Address Sanitizer (ASan) Zugriffe außerhalb der Grenzen, Use-after-free und andere Speicherfehler in C/C++/ObjC-Code. Thread Sanitizer (TSan) erkennt Data Races in Multithread-Code. Undefined Behavior Sanitizer (UBSan) erkennt undefiniertes Verhalten, z. B. den Überlauf eines signed int. Diese Optionen sind unter Edit Scheme → Run → Diagnostics verfügbar und funktionieren nur für Debug-Builds. Das Aktivieren aller Sanitizer kann den Start um das 2- bis 3-Fache verlangsamen. Daher wird empfohlen, sie selektiv zu aktivieren.

Klonen des Schemas für verschiedene Umgebungen

Eine typische Praxis ist es, separate Schemata für jede Umgebung zu erstellen: Dev, Staging, Production. Jedes Schema verwendet dieselbe Build Configuration (Debug für Dev, Release für Production), aber unterschiedliche Startargumente: -FIRAnalyticsDebugEnabled, -com.apple.CoreData.SQLDebug 1 für Dev und deren Abwesenheit für Production. Die Startargumente werden an UserDefaults (ProcessInfo.processInfo.arguments) übergeben und sind beim App-Start lesbar. Dadurch können Server-URL, Logging-Level und Funktionen ohne Codeänderung umgeschaltet werden.

Shared- und Private-Schemata: Verwaltung über Git

Shared-Schemata werden in <project>.xcworkspace/xcshareddata/xcschemes/ oder <project>.xcodeproj/xcshareddata/xcschemes/ gespeichert und gelangen in das Git-Repository. Alle Entwickler des Teams sehen diese Schemata in Xcode. Shared-Schemata sind der einzige Weg, Schemata im Team zu verteilen. Wenn ein Entwickler ein wichtiges Schema erstellt hat (z. B. "Staging Archive"), es aber nicht als Shared markiert hat, sieht der Rest des Teams es nicht, was zu Verwirrung führt: Jeder erstellt sein eigenes Schema mit eigenen Einstellungen.

Private-Schemata werden in xcuserdata/<user>/xcschemes/ gespeichert und gelangen nicht in Git. Sie sind nützlich für persönliche Konfigurationen: zum Beispiel ein Schema mit allen aktivierten Sanitizern für einen bestimmten Entwickler. Private-Schemata sollten keine kritischen Einstellungen enthalten, von denen der Projekt-Build abhängt — wenn der Entwickler das Projekt verlässt, verschwinden seine Private-Schemata. Empfehlung: Alle Schemata, die in CI/CD verwendet und von mindestens zwei Entwicklern genutzt werden, sollten Shared sein.

Die Verwaltung der Schemata erfolgt über Manage Schemes (Product → Scheme → Manage Schemes). Das Fenster zeigt alle Schemata des Projekts, deren Status (Shared/Private) sowie Schaltflächen +/− zum Hinzufügen/Entfernen. Das Kontrollkästchen Shared schaltet die Sichtbarkeit des Schemas für das Team um. Bei einem Git-Konflikt (Änderungen an .xcscheme durch zwei Entwickler) muss der Merge sorgfältig aufgelöst werden — XML-Dateien können unterschiedliche Target-Identifikatoren enthalten. Empfohlen wird, .xcscheme zu den Dateien hinzuzufügen, die während des Merge gesperrt sind (git lfs oder .gitattributes).

Startargumente und Umgebungsvariablen

Arguments im Scheme sind Zeichenfolgen, die der App beim Start übergeben werden (ProcessInfo.processInfo.arguments) und Umgebungsvariablen (ProcessInfo.processInfo.environment). Argumente werden für Flags verwendet: -AppleLanguages (ru), -AppleLocale ru_RU zur Simulation des russischen Locale oder -FIRDebugEnabled zum Aktivieren des Firebase-Debuggings. Umgebungsvariablen werden für die Konfiguration verwendet: API_BASE_URL=http://localhost:3000, LOG_LEVEL=debug.

Zur Verwaltung von Funktionen (Feature Flags) in verschiedenen Umgebungen wird eine Kombination aus Arguments + Build Configuration verwendet. Im Dev-Schema wird das Argument -FeatureFlagNewOnboarding YES gesetzt, in Production — -FeatureFlagNewOnboarding NO (oder das Argument fehlt). Im Code lautet die Prüfung: UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding"). Dieser Ansatz ermöglicht es, Funktionen schrittweise auf Staging zu aktivieren, ohne Code zu ändern und ohne Produktionswerte zu committen.

Wichtig: Argumente und Umgebungsvariablen des Schemes überschreiben die Werte aus Info.plist. Wenn in Info.plist API_URL angegeben ist und im Scheme — API_URL=http://localhost für die Run-Aktion, wird beim Start aus Xcode der Wert aus dem Scheme verwendet. Beim Start auf einem Gerät (nicht aus Xcode) — der Wert aus Info.plist. Das ist praktisch für die lokale Entwicklung, aber man muss bedenken, dass Scheme-Variablen nicht in den Build gelangen — sie wirken nur beim Start über Xcode.

import Foundation

struct AppEnvironment {
    var apiBaseURL: String {
        ProcessInfo.processInfo.environment["API_BASE_URL"]
            ?? Bundle.main.object(forInfoDictionaryKey: "API_BASE_URL") as? String
            ?? "https://api.production.com"
    }

    var isDebugMode: Bool {
        ProcessInfo.processInfo.arguments.contains("-DebugModeEnabled")
    }

    var isNewOnboardingEnabled: Bool {
        UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding")
    }
}

// Verwendung beim Start
let env = AppEnvironment()
NetworkConfig.shared.configure(baseURL: env.apiBaseURL)

Scheme in CI/CD: Automatisierung über xcodebuild

In CI/CD (GitHub Actions, Jenkins, GitLab CI) wird Scheme als Hauptargument des Befehls xcodebuild verwendet. Beispiel: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos archive. Das Flag -scheme gibt an, welches Schema verwendet werden soll. xcodebuild liest alle Einstellungen aus der .xcscheme-Datei, einschließlich Build Configuration, Targets und Build-Reihenfolge. Dadurch wird sichergestellt, dass CI/CD die App mit denselben Parametern erstellt wie die lokale IDE.

Für CI/CD sind Shared-Schemata entscheidend. Wenn das Schema nicht Shared ist, findet xcodebuild es nicht im Repository, und der Build schlägt mit dem Fehler "Scheme not found" fehl. Regel: Stellen Sie vor der Einrichtung von CI/CD sicher, dass alle verwendeten Schemata als Shared markiert sind. Zweite Regel: Verwenden Sie in CI/CD nicht das Standardschema (Xcode wählt automatisch das erste Schema aus) — übergeben Sie den Schemanamen immer explizit über das Flag -scheme.

Für den parallelen Build mehrerer Schemata (z. B. App und watchOS-Erweiterung) kann xcodebuild sequenziell oder parallel ausgeführt werden. Moderne CI-Systeme ermöglichen es, den Build verschiedener Schemata über eine Matrix zu parallelisieren: Ein Job baut die iOS-App, ein zweiter die watchOS-Erweiterung. Dadurch reduziert sich die Gesamtbuildzeit mit zwei parallelen Agenten von 15 auf 8 Minuten. Am Ende werden die Artefakte mit xcodebuild -exportArchive zu einem einzigen .xcarchive zusammengeführt.

#!/bin/bash — CI/CD-Build mit xcodebuild
# 1. Bereinigen und Erstellen
xcodebuild clean archive \
  -workspace "MyApp.xcworkspace" \
  -scheme "MyApp Production" \
  -configuration Release \
  -sdk iphoneos \
  -archivePath "build/MyApp.xcarchive" \
  CODE_SIGN_STYLE="Manual" \
  PROVISIONING_PROFILE_SPECIFIER="match AppStore"

# 2. Export nach IPA
xcodebuild -exportArchive \
  -archivePath "build/MyApp.xcarchive" \
  -exportPath "build/ipa" \
  -exportOptionsPlist "ExportOptions.plist"