Scheme: nedir, yapılandırma ve Xcode'da çalıştırma

Xcode'da Scheme nedir?

Xcode'daki Scheme, bir uygulamayı derlemek ve analiz etmek için eylem sırasını ve bunların parametrelerini açıklayan bir XML dosyasıdır (.xcscheme uzantılı). Her Scheme bir veya daha fazla hedefe bağlıdır ve her eylemin hangi yapılandırmayla (Debug, Release, AdHoc) çalıştırılacağını belirler. Scheme, Android'deki Build Variant'ın karşılığıdır, ancak daha esnek bir yapıya sahiptir: tek bir şema farklı eylemler için farklı hedefler içerebilir.

Xcode, proje ilk açıldığında her hedef için otomatik olarak bir şema oluşturur. Şemanın varsayılan adı hedefin adıyla aynıdır. Projede test hedefi varsa, Xcode onu ana hedefin şemasının Test eylemine otomatik olarak ekler. Birden çok hedefli projelerde (ana uygulama + watchOS + uzantı), Xcode her biri için ayrı bir şema oluşturur, ancak tüm hedefleri aynı anda derleyen tek bir şema da oluşturulabilir.

Şemalar xcshareddata/xcschemes/ dizininde (shared için) veya xcuserdata/<user>/xcschemes/ dizininde (private için) saklanır. Shared şemalar Git'e gider ve tüm ekip tarafından kullanılır. Private şemalar yerel olarak saklanır ve senkronize edilmez. .xcscheme dosyası, kök öğesi <Scheme> olan XML formatındadır. İçinde her eylem için bloklar bulunur: BuildAction, TestAction, LaunchAction, ProfileAction, AnalyzeAction, ArchiveAction.

.xcscheme dosyasının yapısı

.xcscheme, manuel olarak veya Xcode aracılığıyla düzenlenebilen bir XML dosyasıdır. Ana öğeler: <BuildAction> (derlenecek hedeflerin listesi), <TestAction> (test hedeflerine bağlantılar), <LaunchAction> (başlatma yapılandırması), <ProfileAction>, <AnalyzeAction>, <ArchiveAction>. Her blok, söz konusu eylem için hangi yapılandırmanın (Debug/Release) kullanılacağını belirleyen buildConfiguration özniteliğini içerir.

Scheme eylemleri: Build, Run, Test, Profile, Analyze, Archive

Scheme altı eylemden oluşur ve her biri bağımsız olarak yapılandırılabilir. Build eylemi, hangi hedeflerin hangi sırayla derleneceğini belirler. Run eylemi, uygulamanın hangi bağımsız değişkenler, ortam değişkenleri ve hangi yapılandırmayla başlatılacağını belirler. Test eylemi, hangi testlerin çalıştırılacağını ve hangi kod kapsamı seçeneklerinin etkinleştirileceğini belirler. Profile eylemi, profil çıkarmak için Instruments araçlarıyla başlatır. Analyze eylemi, Clang Static Analyzer ile statik kod analizi yapar. Archive eylemi, App Store'da yayınlamak veya AdHoc dağıtımı için derleme yapar.

Her eylem için ayrı bir build configuration ayarlanabilir. Genellikle Run ve Test için Debug, Archive için Release kullanılır. build configuration, derleyici bayrakları, optimizasyonlar ve hata ayıklama bilgileri kümesini tanımlar. Xcode iki standart yapılandırma sunar: Debug (optimizasyon yok, hata ayıklama sembolleriyle) ve Release (optimizasyonlu, hata ayıklama bilgisi yok). Geliştirici, project.xcconfig aracılığıyla özel yapılandırmalar ekleyebilir.

Archive eylemi özellikle önemlidir: bir .xcarchive oluşturur ve bu daha sonra App Store veya AdHoc için .ipa'ya dışa aktarılır. Archive eylemi varsayılan olarak Release yapılandırmasını kullanır, ancak AdHoc veya Distribution'a geçilebilir. Archive eyleminde revealArchiveInOrganizer bayrağı da vardır: arşivleme tamamlandığında Xcode, arşivle ilgili daha fazla işlem için Organizer'ı açar.

<!-- iOS uygulaması için .xcscheme örneği -->
<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 oluşturma ve yapılandırma

Tanılama temizleyicileri (sanitizer)

Yeni bir şema oluşturmak Xcode menüsünden yapılır: Product → Scheme → New Scheme veya Scheme panelindeki (Run düğmesinin yanındaki) "+" düğmesiyle. Oluştururken şemanın oluşturulacağı hedef seçilir. Mevcut bir şema "duplicate" olarak seçilirse, Xcode ayarlarını otomatik olarak kopyalar. Yeni şemalar varsayılan olarak private olarak kaydedilir; ekiple paylaşmak için Manage Schemes'te Shared'ı etkinleştirmek gerekir.

Edit Scheme penceresi (Product → Scheme → Edit Scheme), eylem sayısına karşılık gelen altı sekme içerir. Her sekmede build configuration, başlatma bağımsız değişkenleri, ortam değişkenleri ve tanılama bayrakları değiştirilebilir. Run sekmesinde şu seçenekler bulunur: executable (hangi ikili dosyanın başlatılacağı), wait for executable to be launched (başlatılan işlemleri hata ayıklamak için), debugger (LLDB veya None), launch arguments, environment variables ve genişletilmiş seçenekler (Address Sanitizer, Thread Sanitizer, Main Thread Checker, Memory Management).

Tanılama için Address Sanitizer (ASan), C/C++/ObjC kodunda sınır dışı erişimleri, use-after-free ve diğer bellek hatalarını algılar. Thread Sanitizer (TSan), çok iş parçacıklı kodda veri yarışlarını algılar. Undefined Behavior Sanitizer (UBSan), işaretli int taşması gibi tanımsız davranışları algılar. Bu seçenekler Edit Scheme → Run → Diagnostics altında mevcuttur ve yalnızca Debug derlemelerinde çalışır. Tüm sanitizer'ları etkinleştirmek başlatmayı 2-3 kat yavaşlatabilir, bu nedenle seçici olarak etkinleştirilmesi önerilir.

Farklı ortamlar için şemayı klonlama

Yaygın bir uygulama, her ortam için ayrı şemalar oluşturmaktır: Dev, Staging, Production. Her şema aynı Build Configuration'ı kullanır (Dev için Debug, Production için Release), ancak farklı başlatma bağımsız değişkenleri kullanır: Dev için -FIRAnalyticsDebugEnabled, -com.apple.CoreData.SQLDebug 1 ve Production için bunların olmaması. Başlatma bağımsız değişkenleri UserDefaults'a (ProcessInfo.processInfo.arguments) iletilir ve uygulama başlangıcında okunabilir. Bu, kod değiştirmeden sunucu URL'sini, günlük düzeyini ve özellikleri değiştirmeyi sağlar.

Shared ve Private şemalar: Git ile yönetim

Shared şemalar <project>.xcworkspace/xcshareddata/xcschemes/ veya <project>.xcodeproj/xcshareddata/xcschemes/ dizininde saklanır ve Git deposuna girer. Takımdaki tüm geliştiriciler bu şemaları Xcode'da görür. Shared şemalar, şemaları takım içinde dağıtmanın tek yoludur. Bir geliştirici önemli bir şema (örneğin "Staging Archive") oluşturduysa ancak Shared olarak işaretlemediyse, ekibin geri kalanı onu göremez ve bu da karışıklığa yol açar: herkes kendi ayarlarıyla kendi şemasını oluşturur.

Private şemalar xcuserdata/<user>/xcschemes/ dizininde saklanır ve Git'e girmez. Kişisel yapılandırmalar için kullanışlıdırlar: örneğin, belirli bir geliştirici için tüm sanitizer'ların etkinleştirildiği bir şema. Private şemalar, projenin derlenmesinin bağlı olduğu kritik ayarları içermemelidir; geliştirici projeden ayrılırsa private şemaları kaybolur. Öneri: CI/CD'de ve en az iki geliştirici tarafından kullanılan tüm şemaları Shared yapın.

Şema yönetimi Manage Schemes (Product → Scheme → Manage Schemes) aracılığıyla yapılır. Pencere, projedeki tüm şemaları, durumlarını (Shared/Private) ve ekleme/silme için +/− düğmelerini gösterir. Shared onay kutusu, şemanın ekip için görünürlüğünü değiştirir. Git çakışması durumunda (iki geliştiricinin .xcscheme değişikliği), birleştirme dikkatle çözülmelidir: XML dosyaları farklı hedef tanımlayıcıları içerebilir. .xcscheme'nin birleştirme sırasında kilitlenen dosyalara eklenmesi önerilir (git lfs veya .gitattributes).

Başlatma bağımsız değişkenleri ve ortam değişkenleri

Bağımsız değişkenler (arguments), Scheme'de başlatma sırasında uygulamaya iletilen dizelerdir (ProcessInfo.processInfo.arguments) ve ortam değişkenleri (ProcessInfo.processInfo.environment). Bağımsız değişkenler bayraklar için kullanılır: -AppleLanguages (ru), -AppleLocale ru_RU Rusça yerel ayarını simüle etmek için veya -FIRDebugEnabled Firebase hata ayıklamasını etkinleştirmek için. Ortam değişkenleri yapılandırma için kullanılır: API_BASE_URL=http://localhost:3000, LOG_LEVEL=debug.

Farklı ortamlarda özellikleri (feature flags) yönetmek için Arguments + Build Configuration kombinasyonu kullanılır. Dev şemasında -FeatureFlagNewOnboarding YES bağımsız değişkeni ayarlanır, Production'da ise -FeatureFlagNewOnboarding NO (veya bağımsız değişken yoktur). Kodda kontrol: UserDefaults.standard.bool(forKey: "FeatureFlagNewOnboarding"). Bu yaklaşım, kodu değiştirmeden ve üretim değerlerini commit etmeden staging'de özellikleri kademeli olarak etkinleştirmeyi sağlar.

Önemli: Scheme'nin bağımsız değişkenleri ve ortam değişkenleri Info.plist değerlerini geçersiz kılar. Info.plist'te API_URL belirtilmişse ve Scheme'de Run eylemi için API_URL=http://localhost varsa, Xcode'dan başlatıldığında Scheme'deki değer kullanılır. Bir cihazda başlatıldığında (Xcode'dan değil) — Info.plist'teki değer. Bu, yerel geliştirme için uygundur, ancak Scheme değişkenlerinin derlemeye girmediğini unutmamak gerekir: yalnızca Xcode aracılığıyla başlatıldığında etki ederler.

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

// Başlangıçta kullanım
let env = AppEnvironment()
NetworkConfig.shared.configure(baseURL: env.apiBaseURL)

CI/CD'de Scheme: xcodebuild ile otomasyon

CI/CD'de (GitHub Actions, Jenkins, GitLab CI) Scheme, xcodebuild komutunun ana bağımsız değişkeni olarak kullanılır. Örnek: xcodebuild -workspace MyApp.xcworkspace -scheme MyApp -configuration Release -sdk iphoneos archive. -scheme bayrağı hangi şemanın kullanılacağını belirtir. xcodebuild, build configuration, hedefler ve derleme sırası dahil tüm ayarları .xcscheme dosyasından okur. Bu, CI/CD'nin uygulamayı yerel IDE ile aynı parametrelerle derlemesini garanti eder.

CI/CD için shared şemalar kritiktir. Şema Shared değilse, xcodebuild onu depoda bulamaz ve derleme "Scheme not found" hatasıyla başarısız olur. Kural: CI/CD'yi yapılandırmadan önce kullanılan tüm şemaların Shared olarak işaretlendiğinden emin olun. İkinci kural: CI/CD'de varsayılan şemayı kullanmayın (Xcode otomatik olarak ilk şemayı seçer) — şema adını her zaman -scheme bayrağıyla açıkça iletin.

Birden çok şemayı paralel derlemek için (örneğin uygulama ve watchOS uzantısı), xcodebuild sıralı veya paralel çalıştırılabilir. Modern CI sistemleri, farklı şemaların derlenmesini bir matris aracılığıyla paralelleştirmeye olanak tanır: bir iş iOS uygulamasını, ikincisi watchOS uzantısını derler. Bu, iki paralel ajanla toplam derleme süresini 15 dakikadan 8 dakikaya düşürür. Sonunda ürünler xcodebuild -exportArchive ile tek bir .xcarchive'de birleştirilir.

#!/bin/bash — xcodebuild ile CI/CD derlemesi
# 1. Temizleme ve derleme
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'ya dışa aktarma
xcodebuild -exportArchive \
  -archivePath "build/MyApp.xcarchive" \
  -exportPath "build/ipa" \
  -exportOptionsPlist "ExportOptions.plist"