.xcconfig — nedir, sözdizimi ve Xcode'da değişkenler

.xcconfig nedir?

.xcconfig (Xcode Yapılandırma Dosyası), PARAMETER_NAME = value formatında Build Settings içeren düz bir metin dosyasıdır. .xcconfig dosyaları, Xcode derleme yapılandırmalarının merkezi yönetimi için kullanılır: Build Settings arayüzündeki alanların manuel düzenlemesinin yerini alırlar. Her .xcconfig, bir Build Configuration'a (Debug, Release) veya projenin tamamına bağlıdır ve herhangi bir build setting'i geçersiz kılabilir: SWIFT_VERSION, IPHONEOS_DEPLOYMENT_TARGET, PRODUCT_BUNDLE_IDENTIFIER, CODE_SIGN_STYLE, PROVISIONING_PROFILE_SPECIFIER.

.xcconfig ortaya çıkmadan önce, derleme ayarları yalnızca project.pbxproj'de saklanıyordu — diff'lerde okunması zor ve yorum yapılması imkansız olan ikili/plist bir dosya. .xcconfig bu sorunu çözdü: geliştiriciler parametrelere yorum ekleyebilir, bunları anlamlarına göre gruplayabilir, farklı ortamlar için sürümlenebilir dosyalar oluşturabilir ve dosyalar arasında parametreleri devralabilir. Bu, .xcconfig'i iOS projelerinde yapılandırma yönetimi için fiili standart haline getirdi.

.xcconfig dosyaları proje içinde, genellikle Configurations/ veya BuildConfig/ klasöründe bulunur. Her dosya bir Build Configuration'a karşılık gelir: Debug.xcconfig, Release.xcconfig, Staging.xcconfig. Ayrıca, #include aracılığıyla tüm yapılandırmalara dahil edilen ortak bir Shared.xcconfig dosyası oluşturulur. Bu, ortak parametrelerin bir kez tanımlanmasına ve yapılandırma dosyalarında belirli parametrelerin geçersiz kılınmasına olanak tanır.

Arayüz Build Settings'e göre avantajlar

Diff okunabilirliği: .xcconfig'deki değişiklikler Git diff'te normal satırlar olarak görünür. Alan sırasını değiştirmenin tek bir parametre düzenlemesi için 50 satır değişiklik gösterdiği project.pbxproj'in aksine. Yorumlar: .xcconfig'de her parametrenin neden gerekli olduğunu açıklayabilirsiniz. Devralma: ortak ayarlarla bir temel yapılandırma oluşturabilir ve yalnızca Debug ve Release için gerekli parametreleri geçersiz kılabilirsiniz.

.xcconfig sözdizimi ve yapısı

Değişkenler ve değiştirmeler

.xcconfig sözdizimi mümkün olduğunca basittir: her satır bir parametredir, ad ve değer eşit işaretiyle ayrılır. = etrafındaki boşluklar yok sayılır. Değerler $(VARIABLE_NAME) veya ${VARIABLE_NAME} formatında değişkenler içerebilir. Yorumlar // veya # ile başlar ve satır sonuna kadar geçerlidir. Satırlar, ters eğik \ kullanılarak bir sonraki satırda devam eder. Boş satırlar yok sayılır.

.xcconfig'deki değişkenler diğer değişkenlere başvurarak bileşik değerler oluşturabilir. Örneğin: PRODUCT_NAME = MyApp, PRODUCT_BUNDLE_IDENTIFIER = com.example.$(PRODUCT_NAME). Xcode, derleme zamanında değeri değerlendirir ve değişkenlerin gerçek değerlerini yerine koyar. AGP ayrıca derleme ortamı tarafından ayarlanan sistem değişkenlerini de destekler: ARCHS, SDK_NAME, CONFIGURATION, PLATFORM_NAME.

Koşullu yapılandırma için köşeli parantez içinde platform yönergeleri kullanılır: PARAMETER[sdk=iphoneos*] = value. Örneğin, SUPPORTED_PLATFORMS[sdk=iphoneos*] = iphoneos parametreyi yalnızca iOS derlemeleri için ayarlar. Joker karakterler desteklenir: * (herhangi bir karakter), ? (tek karakter). Koşullu yönergeler, birden çok platform için tek bir .xcconfig'e sahip olmayı ve tek bir dosyada iOS ve macOS için farklı değerler ayarlamayı sağlar.

// Shared.xcconfig — ortak proje ayarları
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 16.0
SDKROOT = iphoneos
TARGETED_DEVICE_FAMILY = 1,2

// Paket tanımlayıcısı — önek ve addan oluşturulur
BUNDLE_ID_PREFIX = com.example
PRODUCT_NAME = MyApp
PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)

// macOS için koşullu ayar
SUPPORTED_PLATFORMS[sdk=macosx*] = macosx
PRODUCT_BUNDLE_IDENTIFIER[sdk=macosx*] = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).mac

// Sürümleme
MARKETING_VERSION = 2.4.1
CURRENT_PROJECT_VERSION = 37

#include ile yapılandırma devralma

#include, başka bir .xcconfig dosyasının içeriğini dahil eden bir .xcconfig önişlemci yönergesidir. Yönergeler iç içe yerleştirilebilir: Shared.xcconfig, “Base.xcconfig” dosyasını #include edebilir, Debug.xcconfig, “Shared.xcconfig” dosyasını #include edebilir. Devralma zinciri, her düzeyin bir öncekinin parametrelerini geçersiz kıldığı bir yapılandırma hiyerarşisi oluşturmayı sağlar. #include, son yazma ilkesine göre çalışır: aynı parametre hem dahil edilen dosyada hem de ana dosyada tanımlanmışsa, ana dosyadaki değer önceliklidir.

Tipik bir iOS projesi için doğru hiyerarşi: Base.xcconfig (en yaygın parametreler) → Shared.xcconfig (proje ayarları) → Debug.xcconfig veya Release.xcconfig. Base.xcconfig standartları tanımlar (SWIFT_VERSION, DEPLOYMENT_TARGET), Shared.xcconfig — proje özelliklerini (PRODUCT_NAME, PREPROCESSOR_DEFINITIONS), Debug/Release — ortamı (DEBUG_INFORMATION_FORMAT, OPTIMIZATION_CFLAGS). #include döngülere izin vermez — döngüsel bir bağımlılık tespit edilirse Xcode hata verecektir.

Örnek: Config/Base.xcconfig → Config/iOS/Shared.xcconfig → Config/iOS/Debug.xcconfig. Bu yapı, Base'in iOS, macOS ve tvOS projeleri için ve Shared'in yalnızca iOS için yeniden kullanılmasına olanak tanır. Not: #include, kök .xcconfig'in konumundan bir dosya adı veya göreceli yol kullanır. Mutlak yollar önerilmez — diğer makinelerde ve CI/CD'de derlemeyi bozarlar.

// --- Config/Base.xcconfig ---
SWIFT_VERSION = 5.0
ENABLE_MODULE_VERIFIER = YES
CLANG_ENABLE_MODULES = YES

// --- Config/iOS/Shared.xcconfig ---
#include "../Base.xcconfig"
IPHONEOS_DEPLOYMENT_TARGET = 16.0
PRODUCT_BUNDLE_IDENTIFIER = com.example.myapp

// --- Config/iOS/Debug.xcconfig ---
#include "Shared.xcconfig"
OPTIMIZATION_CFLAGS = -O0
DEBUG_INFORMATION_FORMAT = dwarf
SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG
ENABLE_TESTABILITY = YES

// --- Config/iOS/Release.xcconfig ---
#include "Shared.xcconfig"
OPTIMIZATION_CFLAGS = -Osize
DEBUG_INFORMATION_FORMAT = dwarf-with-dsym
SWIFT_COMPILATION_MODE = wholemodule

Xcode projesinde .xcconfig bağlama

Proje düzeyi ve hedef düzeyi yapılandırmaları

.xcconfig'in bir projeye bağlanması Project Info → Configurations altında yapılır. Her Build Configuration (Debug, Release, AdHoc) için “Based on Configuration File” açılır menüsünden ilgili .xcconfig seçilir. Bir yapılandırma bir dosyaya bağlı değilse, Xcode project.pbxproj'deki değerleri kullanır. .xcconfig seçildikten sonra, dosyadaki tüm parametreler bu yapılandırma için etkin hale gelir.

Proje düzeyi ve hedef düzeyi yapılandırmaları arasında ayrım yapmak önemlidir. Proje düzeyindeki bir .xcconfig, tüm hedefler için varsayılan parametreleri ayarlar. Hedef düzeyindeki bir .xcconfig, bunları belirli bir hedef için geçersiz kılar. Hedef düzeyindeki .xcconfig'de bir parametre ayarlanmamışsa, proje düzeyindeki değer kullanılır. Orada da ayarlanmamışsa, project.pbxproj'deki değer kullanılır. Pratik kural: ortak parametreleri (derleme, sürümler) proje düzeyine, hedefe özgü ayarları (paket tanımlayıcısı, provisioning) hedef düzeyine koyun.

.xcconfig ile arayüz Build Settings arasında çakışma olması durumunda, arayüzdeki değer önceliklidir (.xcconfig'i geçersiz kılar). Bu karışıklığa yol açabilir: bir geliştirici, .xcconfig'in farklı bir değer belirttiğini bilmeden arayüzde bir Build Setting'i değiştirir. Tamamen .xcconfig'e geçilmesi ve arayüz Build Settings'e dokunulmaması önerilir. Hangi parametrenin uygulandığını kontrol etmek için xcrun xcodebuild -showBuildSettings kullanın — komut, tüm düzeyleri çözdükten sonra tüm parametrelerin nihai değerlerini gösterecektir.

Örnek: Dev, Staging, Production ortamları

Üç düzeyli bir yapılandırma düşünün: Dev (yerel geliştirme), Staging (test sunucusu), Production (sürüm). Her ortam için ayrı bir .xcconfig oluşturulur ve farklı API_URL, günlükleme ve sertifika değerleri tanımlanır. Dev localhost kullanır, Staging staging.api.example.com kullanır, Production api.example.com kullanır. Her üçü de #include aracılığıyla ortak Shared.xcconfig'i devralır.

Ortamlar arasında farklılık gösteren anahtar parametre PRODUCT_BUNDLE_IDENTIFIER'dır. Dev için: com.example.myapp.dev, Staging için: com.example.myapp.staging, Production için: com.example.myapp. Farklı paket ID'leri, üç sürümün de aynı cihaza aynı anda yüklenmesine olanak tanır. CODE_SIGN_IDENTITY (Dev için Apple Development, Production için Apple Distribution) ve PROVISIONING_PROFILE_SPECIFIER da farklılık gösterir.

Değerleri koda aktarmak için INFOPLIST_PREFIX_HEADER veya -D önişlemcisiyle OTHER_SWIFT_FLAGS kullanılır. Swift'te önişlemci yoktur, bu nedenle Active Compilation Conditions kullanılır: SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEV. Kodda: #if DEV; #elseif STAGING; #else; #endif. Objective-C için GCC_PREPROCESSOR_DEFINITIONS kullanılır. Bu, kaynak dosyaları değiştirmeden farklı ortamlar için farklı kod derlemeyi sağlar.

// --- Config/Dev.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).dev
CODE_SIGN_IDENTITY = Apple Development
PROVISIONING_PROFILE_SPECIFIER = Dev Profile

SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG DEV
OTHER_SWIFT_FLAGS = -D DEV

// Info.plist aracılığıyla API URL — değer değiştirilir
API_BASE_URL = http://localhost:3000/api

// --- Config/Staging.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).staging
CODE_SIGN_IDENTITY = Apple Development
PROVISIONING_PROFILE_SPECIFIER = Staging Profile

SWIFT_ACTIVE_COMPILATION_CONDITIONS = STAGING
OTHER_SWIFT_FLAGS = -D STAGING
API_BASE_URL = https://staging.api.example.com/v2

// --- Config/Production.xcconfig ---
#include "Shared.xcconfig"

PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)
CODE_SIGN_IDENTITY = Apple Distribution
PROVISIONING_PROFILE_SPECIFIER = AppStore Distribution

SWIFT_ACTIVE_COMPILATION_CONDITIONS = RELEASE
API_BASE_URL = https://api.example.com/v3

.xcconfig ve Info.plist: değer aktarma

.xcconfig'teki değerler, $(PARAMETER_NAME) değişkenleri aracılığıyla Info.plist'e aktarılabilir. .xcconfig'te bir parametre tanımlanmışsa (örneğin API_BASE_URL), Info.plist'te kullanılabilir: <key>ApiBaseUrl</key><string>$(API_BASE_URL)</string>. Derleme zamanında Xcode, $(API_BASE_URL) değerini .xcconfig'teki değerle değiştirir. Bu, kodu değiştirmeden uygulamayı yapılandırmayı sağlar — sadece şemayı değiştirin.

Info.plist'te kullanılan .xcconfig parametreleri herkese açık olmalıdır — ikili dosyaya girerler ve derlenmiş uygulamada görünürler. Gizli değerler (token'lar, şifreler) için .xcconfig kullanmayın — sunucuda çalışan Firebase Remote Config gibi hizmetleri kullanın. Info.plist için .xcconfig şunlar için uygundur: sunucu URL'leri, varlık adları, izleyici tanımlayıcıları, feature flag'ler.

Kodda Info.plist değerlerine erişim: Objective-C/Swift için Bundle.main.object(forInfoDictionaryKey: “ApiBaseUrl”). Değer .xcconfig aracılığıyla ayarlanmışsa, değiştirilecek ve Bundle main.infoDictionary'de kullanılabilir olacaktır. Bu yöntem, BuildConfigField'dan (Android'de olduğu gibi) daha çok tercih edilir, çünkü Info.plist standart bir iOS mekanizmasıdır ve değerleri extensions, widget'lar ve Siri Intents dahil tüm sistem bileşenleri tarafından kullanılabilir.