Scheme: суть, конфігурація та запуск у Xcode

Що таке Scheme у Xcode?

Scheme у Xcode — це XML-файл (розширення .xcscheme), який описує послідовність дій та їхні параметри для збірки й аналізу застосунку. Кожна Scheme прив'язана до одного або кількох таргетів і визначає, з якою конфігурацією (Debug, Release, AdHoc) виконувати кожну дію. Scheme — аналог Build Variant в Android, але з гнучкішою структурою: одна схема може містити різні таргети для різних дій.

Xcode автоматично створює схему для кожного таргета під час першого відкриття проєкту. Ім'я схеми за замовчуванням збігається з іменем таргета. Якщо в проєкті є тестовий таргет, Xcode автоматично додає його до Test-дії схеми основного таргета. Для проєктів із кількома таргетами (основний застосунок + watchOS + extension) Xcode створює окрему схему для кожного, але можна створити одну схему, яка збирає всі таргети одразу.

Схеми зберігаються в каталозі xcshareddata/xcschemes/ (для shared) або xcuserdata/<user>/xcschemes/ (для private). Shared схеми потрапляють у Git і використовуються всією командою. Private схеми зберігаються локально й не синхронізуються. Файл .xcscheme має XML-формат із кореневим елементом <Scheme>. Усередині — блоки для кожної дії: BuildAction, TestAction, LaunchAction, ProfileAction, AnalyzeAction, ArchiveAction.

Структура .xcscheme файлу

.xcscheme — це XML-файл, який можна редагувати вручну або через Xcode. Основні елементи: <BuildAction> (список таргетів, що збираються), <TestAction> (посилання на тестові таргети), <LaunchAction> (конфігурація запуску), <ProfileAction>, <AnalyzeAction>, <ArchiveAction>. Кожен блок містить атрибут buildConfiguration, який визначає, яку конфігурацію (Debug/Release) використовувати для цієї дії.

Дії Scheme: Build, Run, Test, Profile, Analyze, Archive

Scheme складається із шести дій, кожну з яких можна налаштувати незалежно. Build-дія визначає, які таргети збираються й у якому порядку. Run-дія — як запускається застосунок: з якими аргументами, змінними середовища та якою конфігурацією. Test-дія — які тести виконуються та які опції code coverage увімкнено. Profile-дія — запуск з інструментами Instruments для профілювання. Analyze-дія — статичний аналіз коду за допомогою Clang Static Analyzer. Archive-дія — збірка для публікації в App Store або AdHoc-розповсюдження.

Для кожної дії можна задати окрему build configuration. Зазвичай для Run і Test використовується Debug, для Archive — Release. Build configuration визначає набір прапорців компілятора, оптимізації та налагоджувальну інформацію. Xcode надає дві стандартні конфігурації: Debug (без оптимізацій, із символами налагодження) і Release (з оптимізаціями, без налагоджувальної інформації). Розробник може додавати кастомні конфігурації через project.xcconfig.

Дія Archive особливо важлива — вона створює .xcarchive, який потім експортується в .ipa для App Store або AdHoc. Archive-дія за замовчуванням використовує Release-конфігурацію, але можна перемкнути на AdHoc або Distribution. В Archive-дії також доступний прапорець revealArchiveInOrganizer — після завершення архівування Xcode відкриває Organizer для подальших дій з архівом.

<!-- Пример .xcscheme для iOS приложения -->
<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>

Створення та налаштування Scheme

Діагностичні санітайзери

Створення нової схеми виконується через меню Xcode: Product → Scheme → New Scheme або кнопкою "+" на панелі Scheme (поруч із кнопкою Run). Під час створення вибирається таргет, для якого створюється схема. Xcode автоматично копіює налаштування з наявної схеми, якщо її обрано як "duplicate". Нові схеми за замовчуванням зберігаються як private — для публікації команді потрібно увімкнути Shared у Manage Schemes.

Вікно Edit Scheme (Product → Scheme → Edit Scheme) містить шість вкладок за кількістю дій. На кожній вкладці можна змінити build configuration, аргументи запуску, змінні середовища, діагностичні прапорці. На вкладці Run доступні опції: executable (який бінарник запускати), wait for executable to be launched (для налагодження запущених процесів), debugger (LLDB або None), launch arguments, environment variables та розширені опції (Address Sanitizer, Thread Sanitizer, Main Thread Checker, Memory Management).

Для діагностики Address Sanitizer (ASan) виявляє вихід за межі масиву, use-after-free та інші помилки пам'яті в C/C++/ObjC-коді. Thread Sanitizer (TSan) виявляє стани гонки (data races) у багатопотоковому коді. Undefined Behavior Sanitizer (UBSan) виявляє невизначену поведінку, наприклад переповнення знакового int. Ці опції доступні в Edit Scheme → Run → Diagnostics і працюють лише для Debug-збірок. Увімкнення всіх санітайзерів може сповільнити запуск у 2-3 рази, тому рекомендується вмикати їх вибірково.

Клонування схеми для різних середовищ

Типова практика — створювати окремі схеми для кожного середовища: Dev, Staging, Production. Кожна схема використовує одні й ті самі Build Configuration (Debug для Dev, Release для Production), але різні аргументи запуску: -FIRAnalyticsDebugEnabled, -com.apple.CoreData.SQLDebug 1 для Dev та їхня відсутність для Production. Аргументи запуску передаються в UserDefaults (ProcessInfo.processInfo.arguments) і доступні для читання на старті застосунку. Це дозволяє перемикати URL сервера, рівень логування та фічі без зміни коду.

Shared і Private схеми: керування через Git

Shared схеми зберігаються в <project>.xcworkspace/xcshareddata/xcschemes/ або <project>.xcodeproj/xcshareddata/xcschemes/ і потрапляють у репозиторій Git. Усі розробники команди бачать ці схеми у Xcode. Shared схеми — єдиний спосіб поширювати схеми в команді. Якщо розробник створив важливу схему (наприклад, "Staging Archive"), але не позначив її як Shared, решта команди її не побачить, що призводить до плутанини: кожен створюватиме свою схему зі своїми налаштуваннями.

Private схеми зберігаються в xcuserdata/<user>/xcschemes/ і не потрапляють у Git. Вони корисні для персональних конфігурацій: наприклад, схема з увімкненими всіма санітайзерами для конкретного розробника. Private схеми не повинні містити критичних налаштувань, від яких залежить збірка проєкту — якщо розробник покине проєкт, його private схеми зникнуть. Рекомендація: усі схеми, що використовуються в CI/CD і щонайменше двома розробниками, робити Shared.

Керування схемами виконується через Manage Schemes (Product → Scheme → Manage Schemes). У вікні відображаються всі схеми проєкту, їхній статус (Shared/Private) та кнопки +/− для додавання/видалення. Прапорець Shared перемикає видимість схеми для команди. Під час конфлікту Git (зміни в .xcscheme від двох розробників) потрібно акуратно розв'язувати злиття — XML-файли можуть містити різні ідентифікатори таргетів. Рекомендується додавати .xcscheme до файлів, що блокуються під час merge (git lfs або .gitattributes).

Аргументи запуску та змінні середовища

Arguments у Scheme — це рядки, які передаються застосунку під час запуску (ProcessInfo.processInfo.arguments) та змінні середовища (ProcessInfo.processInfo.environment). Аргументи використовуються для прапорців: -AppleLanguages (ru), -AppleLocale ru_RU для симуляції російської локалі, або -FIRDebugEnabled для ввімкнення налагодження Firebase. Змінні середовища застосовуються для конфігурації: API_BASE_URL=http://localhost:3000, LOG_LEVEL=debug.

Для керування фічами (feature flags) у різних середовищах використовується комбінація Arguments + Build Configuration. У Dev-схемі встановлюється аргумент -FeatureFlagNewOnboarding YES, а в Production — -FeatureFlagNewOnboarding NO (або аргумент відсутній). У коді перевірка: UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding"). Цей підхід дозволяє поступово вмикати фічі на staging без зміни коду та без коміту production-значень.

Важливо: аргументи та змінні середовища Scheme перевизначають значення з Info.plist. Якщо в Info.plist вказано API_URL, а в Scheme — API_URL=http://localhost для Run-дії, під час запуску з Xcode буде використано значення зі Scheme. Під час запуску на пристрої (не з Xcode) — значення з Info.plist. Це зручно для локальної розробки, але потрібно пам'ятати, що змінні Scheme не потрапляють у збірку — вони діють лише під час запуску через 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")
    }
}

// Використання під час старту
let env = AppEnvironment()
NetworkConfig.shared.configure(baseURL: env.apiBaseURL)

Scheme у CI/CD: автоматизація через xcodebuild

У CI/CD (GitHub Actions, Jenkins, GitLab CI) Scheme використовується як основний аргумент команди xcodebuild. Приклад: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos archive. Прапорець -scheme вказує, яку схему використовувати. xcodebuild читає всі налаштування з файлу .xcscheme, включно з build configuration, таргетами та порядком збірки. Це гарантує, що CI/CD збирає застосунок із тими самими параметрами, що й локальна IDE.

Для CI/CD критичні Shared схеми. Якщо схема не Shared, xcodebuild не знайде її в репозиторії, і збірка впаде з помилкою "Scheme not found". Правило: перед налаштуванням CI/CD переконайтеся, що всі використовувані схеми позначені як Shared. Друге правило: у CI/CD не використовуйте default scheme (Xcode автоматично вибирає першу схему) — завжди передавайте ім'я схеми явно через прапорець -scheme.

Для паралельної збірки кількох схем (наприклад, застосунку та watchOS-розширення) можна запускати xcodebuild послідовно або паралельно. Сучасні CI-системи дозволяють розпаралелити збірку різних схем через матрицю: одна джоба збирає iOS-застосунок, друга — watchOS-розширення. Це скорочує загальний час збірки з 15 до 8 хвилин за двох паралельних агентів. Наприкінці артефакти об'єднуються в єдиний .xcarchive за допомогою xcodebuild -exportArchive.

#!/bin/bash — CI/CD сборка с xcodebuild
# 1. Очищення та збірка
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. Експорт в IPA
xcodebuild -exportArchive \
  -archivePath "build/MyApp.xcarchive" \
  -exportPath "build/ipa" \
  -exportOptionsPlist "ExportOptions.plist"