Scheme: lényege, konfigurációja és futtatása az Xcode-ban

Mi az a Scheme az Xcode-ban?

A Scheme az Xcode-ban egy XML-fájl (.xcscheme kiterjesztéssel), amely leírja az akciók sorrendjét és azok paramétereit az alkalmazás építéséhez és elemzéséhez. Minden Scheme egy vagy több targethez kapcsolódik, és meghatározza, milyen konfigurációval (Debug, Release, AdHoc) hajtsuk végre az egyes akciókat. A Scheme a Build Variant analógja az Androidban, de rugalmasabb felépítéssel: egy séma különböző targeteket tartalmazhat a különböző akciókhoz.

Az Xcode automatikusan létrehoz egy sémát minden targethez a projekt első megnyitásakor. A séma alapértelmezett neve megegyezik a target nevével. Ha a projektben van teszttarget, az Xcode automatikusan hozzáadja a fő target sémájának Test akciójához. Többtargetes projekteknél (fő alkalmazás + watchOS + extension) az Xcode mindegyikhez külön sémát hoz létre, de létrehozható egyetlen séma is, amely egyszerre építi az összes targetet.

A sémák az xcshareddata/xcschemes/ könyvtárban (shared esetén) vagy az xcuserdata/<user>/xcschemes/ könyvtárban (private esetén) tárolódnak. A shared sémák bekerülnek a Git-be, és az egész csapat használja őket. A private sémák lokálisan tárolódnak, és nem szinkronizálódnak. A .xcscheme fájl XML-formátumú, gyökér eleme a <Scheme>. Belül minden akcióhoz található egy blokk: BuildAction, TestAction, LaunchAction, ProfileAction, AnalyzeAction, ArchiveAction.

A .xcscheme fájl felépítése

A .xcscheme egy XML-fájl, amely kézzel vagy az Xcode-on keresztül szerkeszthető. Fő elemek: <BuildAction> (az építendő targetek listája), <TestAction> (hivatkozások a teszttargetekre), <LaunchAction> (futtatási konfiguráció), <ProfileAction>, <AnalyzeAction>, <ArchiveAction>. Minden blokk tartalmazza a buildConfiguration attribútumot, amely meghatározza, milyen konfigurációt (Debug/Release) használjunk az adott akcióhoz.

A Scheme akciói: Build, Run, Test, Profile, Analyze, Archive

A Scheme hat akcióból áll, amelyek mindegyike önállóan konfigurálható. A Build Action meghatározza, mely targetek és milyen sorrendben épülnek. A Run Action — hogyan indul az alkalmazás: milyen argumentumokkal, környezeti változókkal és konfigurációval. A Test Action — mely tesztek futnak, és mely code coverage opciók vannak bekapcsolva. A Profile Action — indítás az Instruments eszközeivel a profilozáshoz. Az Analyze Action — a kód statikus elemzése a Clang Static Analyzerrel. Az Archive Action — build az App Store-ban történő publikáláshoz vagy AdHoc-terjesztéshez.

Minden akcióhoz külön build configuration állítható be. Általában a Run és Test esetén Debug-t, az Archive esetén Release-t használunk. A build configuration meghatározza a fordító flagjeit, az optimalizációkat és a hibakeresési információt. Az Xcode két standard konfigurációt kínál: Debug (optimalizáció nélkül, hibakeresési szimbólumokkal) és Release (optimalizációkkal, hibakeresési információ nélkül). A fejlesztő egyéni konfigurációkat adhat hozzá a project.xcconfig fájlon keresztül.

Az Archive akció különösen fontos — .xcarchive fájlt hoz létre, amelyet ezután .ipa fájlba exportálunk az App Store vagy az AdHoc számára. Az Archive Action alapértelmezés szerint a Release konfigurációt használja, de átváltható AdHoc vagy Distribution módra. Az Archive Action-ban a revealArchiveInOrganizer flag is elérhető — az archiválás befejezése után az Xcode megnyitja az Organisert az archívummal kapcsolatos további műveletekhez.

<!-- Példa .xcscheme iOS-alkalmazáshoz -->
<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>

A Scheme létrehozása és beállítása

Diagnosztikai sanitizerek

Az új séma létrehozása az Xcode menün keresztül történik: Product → Scheme → New Scheme vagy a „+“ gombbal a Scheme panelen (a Run gomb mellett). Létrehozáskor kiválasztjuk, melyik targethez készül a séma. Ha a séma „duplicate“ módban van kiválasztva, az Xcode automatikusan átmásolja a meglévő séma beállításait. Az új sémák alapértelmezés szerint private-ként tárolódnak — a csapatnak történő publikáláshoz be kell kapcsolni a Shared opciót a Manage Schemes-ben.

A Edit Scheme ablak (Product → Scheme → Edit Scheme) hat fület tartalmaz, az akciók számának megfelelően. Minden fülön módosítható a build configuration, az indítási argumentumok, a környezeti változók és a diagnosztikai flagek. A Run fülön a következő opciók érhetők el: executable (melyik bináris induljon), wait for executable to be launched (az indított folyamatok hibakereséséhez), debugger (LLDB vagy None), launch arguments, environment variables, valamint bővített opciók (Address Sanitizer, Thread Sanitizer, Main Thread Checker, Memory Management).

A diagnosztikához: Address Sanitizer (ASan) — észleli a tömbhatáron túli kilépést, a use-after-free hibákat és más memóriahibákat C/C++/ObjC kódban. Thread Sanitizer (TSan) — észleli az adatversenyeket (data races) a többszálú kódban. Undefined Behavior Sanitizer (UBSan) — feltárja a nem definiált viselkedést, például az előjeles int túlcsordulását. Ezek az opciók az Edit Scheme → Run → Diagnostics menüben érhetők el, és csak Debug-buildeknél működnek. Az összes sanitizer bekapcsolása 2-3-szorosára lassíthatja az indítást, ezért ajánlott szelektíven bekapcsolni őket.

A séma klónozása különböző környezetekhez

Jellemző gyakorlat — külön sémák létrehozása minden környezethez: Dev, Staging, Production. Minden séma ugyanazt a Build Configuration-t használja (Debug a Dev, Release a Production számára), de különböző indítási argumentumokat: -FIRAnalyticsDebugEnabled, -com.apple.CoreData.SQLDebug 1 a Dev-hez, és ezek hiányát a Production-höz. Az indítási argumentumok a UserDefaults-ba (ProcessInfo.processInfo.arguments) kerülnek, és az alkalmazás indulásakor olvashatók. Ez lehetővé teszi a szerver URL, a naplózási szint és a funkciók váltogatását kódmódosítás nélkül.

Shared és private sémák: kezelés Git-tel

A shared sémák a <project>.xcworkspace/xcshareddata/xcschemes/ vagy a <project>.xcodeproj/xcshareddata/xcschemes/ könyvtárban tárolódnak, és bekerülnek a Git-repozitóriumba. A csapat összes fejlesztője látja ezeket a sémákat az Xcode-ban. A shared sémák az egyetlen módja a sémák csapaton belüli terjesztésének. Ha egy fejlesztő létrehozott egy fontos sémát (például „Staging Archive“), de nem jelölte meg Shared-ként, a csapat többi tagja nem fogja látni, ami zavarhoz vezet: mindenki a saját sémáját készíti el a saját beállításaival.

A private sémák az xcuserdata/<user>/xcschemes/ könyvtárban tárolódnak, és nem kerülnek be a Git-be. Hasznosak a személyes konfigurációkhoz: például egy séma, amelyben minden sanitizer be van kapcsolva egy adott fejlesztő számára. A private sémák nem tartalmazhatnak kritikus beállításokat, amelyektől a projekt buildje függ — ha a fejlesztő elhagyja a projektet, a private sémái eltűnnek. Javaslat: minden sémát, amelyet a CI/CD-ben és legalább két fejlesztő használ, Shared-ként kell megjelölni.

A sémák kezelése a Manage Schemes menün keresztül történik (Product → Scheme → Manage Schemes). Az ablakban megjelenik a projekt összes sémája, azok állapota (Shared/Private), valamint a +/— gombok hozzáadáshoz/törléshez. A Shared jelölőnégyzet váltja át a séma láthatóságát a csapat számára. Git-konfliktus esetén (két fejlesztő .xcscheme-módosításai) körültekintően kell feloldani az egyesítést — az XML-fájlok különböző target-azonosítókat tartalmazhatnak. Javasolt a .xcscheme fájlt hozzáadni a merge-nél zárolt fájlokhoz (git lfs vagy .gitattributes).

Indítási argumentumok és környezeti változók

Az Arguments a Scheme-ben azok a karakterláncok, amelyeket az alkalmazás az indításkor kap (ProcessInfo.processInfo.arguments), valamint a környezeti változók (ProcessInfo.processInfo.environment). Az argumentumokat flagekhez használjuk: -AppleLanguages (ru), -AppleLocale ru_RU az orosz lokalizáció szimulálásához, vagy -FIRDebugEnabled a Firebase hibakeresés bekapcsolásához. A környezeti változókat konfigurációra alkalmazzuk: API_BASE_URL=http://localhost:3000, LOG_LEVEL=debug.

A funkciók kezeléséhez (feature flags) különböző környezetekben az Arguments + Build Configuration kombinációját használjuk. A Dev-sémában a -FeatureFlagNewOnboarding YES argumentumot állítjuk be, a Production-ban pedig a -FeatureFlagNewOnboarding NO értéket (vagy az argumentum hiányzik). A kódban az ellenőrzés: UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding"). Ez a megközelítés lehetővé teszi a funkciók fokozatos bekapcsolását a stagingben kódmódosítás és a production-értékek commitolása nélkül.

Fontos: a Scheme argumentumai és környezeti változói felülírják az Info.plist értékeit. Ha az Info.plist-ben API_URL van megadva, a Scheme-ben pedig API_URL=http://localhost a Run Action-höz, akkor az Xcode-ból való indításkor a Scheme értéke lesz használva. Az eszközről való indításkor (nem Xcode-ból) — az Info.plist értéke. Ez kényelmes a helyi fejlesztéshez, de ne feledjük, hogy a Scheme változói nem kerülnek be a buildbe — csak az Xcode-on keresztüli indításkor hatnak.

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")
    }
}

// Használat indításkor
let env = AppEnvironment()
NetworkConfig.shared.configure(baseURL: env.apiBaseURL)

A Scheme a CI/CD-ben: automatizálás xcodebuild-dal

A CI/CD-ben (GitHub Actions, Jenkins, GitLab CI) a Scheme-t az xcodebuild parancs fő argumentumaként használják. Példa: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos archive. A -scheme flag jelöli ki, melyik sémát használjuk. Az xcodebuild minden beállítást a .xcscheme fájlból olvas ki, beleértve a build configuration-t, a targeteket és az építési sorrendet. Ez garantálja, hogy a CI/CD ugyanazokkal a paraméterekkel építi az alkalmazást, mint a helyi IDE.

A CI/CD szempontjából kritikusak a shared sémák. Ha egy séma nem Shared, az xcodebuild nem találja meg a repozitóriumban, és a build a „Scheme not found“ hibával meghiúsul. Szabály: a CI/CD konfigurálása előtt győződj meg róla, hogy minden használt séma Shared-ként van megjelölve. Második szabály: a CI/CD-ben ne használj alapértelmezett sémát (az Xcode automatikusan az első sémát választja) — mindig explicit módon add át a séma nevét a -scheme flag segítségével.

Több séma párhuzamos építéséhez (például az alkalmazás és a watchOS-kiegészítő) az xcodebuild futtatható sorosan vagy párhuzamosan. A modern CI-rendszerek mátrix segítségével teszik lehetővé a különböző sémák építésének párhuzamosítását: az egyik job az iOS-alkalmazást építi, a másik — a watchOS-kiegészítőt. Ez két párhuzamos ágens esetén 15-ről 8 percre csökkenti a teljes építési időt. A végén az artefaktumokat egyetlen .xcarchive fájlba egyesítjük a xcodebuild -exportArchive paranccsal.

#!/bin/bash — CI/CD build az xcodebuild segítségével
# 1. Tisztítás és build
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álás IPA-ba
xcodebuild -exportArchive \
  -archivePath "build/MyApp.xcarchive" \
  -exportPath "build/ipa" \
  -exportOptionsPlist "ExportOptions.plist"