.xcconfig — bu nima, sintaksis va o'zgaruvchilar Xcode'da

.xcconfig nədir?

.xcconfig (Xcode Configuration File) — bu PARAMETER_NAME = value formatında Build Settings’ləri olan düz mətn faylıdır. .xcconfig faylları Xcode qurma konfiqurasiyalarının mərkəzləşdirilmiş idarə edilməsi üçün istifadə olunur: onlar Build Settings UI’da sahələrin əl ilə redaktəsini əvəz edir. Hər .xcconfig Build Configuration’a (Debug, Release) və ya bütöv layihəyə bağlanır və istənilən qurma parametrini ləğv edə bilər: SWIFT_VERSION, IPHONEOS_DEPLOYMENT_TARGET, PRODUCT_BUNDLE_IDENTIFIER, CODE_SIGN_STYLE, PROVISIONING_PROFILE_SPECIFIER.

.xcconfig’in yaranmasından əvvəl qurma parametrləri yalnız project.pbxproj’də saxlanılırdı — diff’lərdə oxumaq çətin olan və şərh etmək mümkün olmayan binar/plist faylı. .xcconfig bu problemi həll etdi: tərtibatçılar parametrləri şərh edə, mənaca görə qruplaşdıra, müxtəlif mühitlər üçün versiyalaşdırıla bilən fayllar yarada və fayllar arasında parametrləri miras ala bilərlər. Bu, .xcconfig’i iOS layihələrində konfiqurasiyaların idarə edilməsi üçün de facto standartına çevirdi.

.xcconfig faylları layihə daxilində, adətən Configurations/ və ya BuildConfig/ qovluğunda yerləşir. Hər fayl bir Build Configuration’a uyğurdur: Debug.xcconfig, Release.xcconfig, Staging.xcconfig. Əlavə olaraq #include vasitəsilə bütün konfiqurasiyalara qoşulan ümumi Shared.xcconfig faylı yaradılır. Bu, ümumi parametrləri bir dəfə təyin etməyə və konfiguratsiya fayllarinda spesifik olanları ləğv etməyə imkan verir.

UI Build Settings ilə müqayisədə üstünlüklər

Diff oxunaqlılığı: .xcconfig’dəki dəyişikliklər Git diff’də adi sətirlər kimi görünür. Project.pbxproj’dən fərqli olaraq, sahələrin sırasının dəyişməsi səbəbindən bir parametrin redaktəsində diff 50 sətir dəyişiklik göstərir. Şerhlər: .xcconfig’də hər parametrin nə üçün lazım olduğunu izah etmək olar. Miras: ümumi parametrlərlə baza konfiqurasiyası yaradıb, Debug və Release üçün yalnız lazımi parametrləri ləğv etmək olar.

.xcconfig sintaksisi və strukturu

Dəyişənlər və əvəzləmələr

.xcconfig sintaksisi son dərəcə sadədir: hər sətir parametr, ad və bərabər işərəsindən sonra dəyərdir. = ətrafındakı boşluqlar nəzərə alınmır. Dəyərlər $(VARIABLE_NAME) və ya ${VARIABLE_NAME} formatında dəyişənlər ehtiva edə bilər. Şerhlər // və ya # ilə başlayır və sətirin sonuna qədər davam edir. Sətirlər tərs kəsik \ vasitəsilə növbəti sətirdə davam etdirilir. Boş sətirlər nəzərə alınmır.

.xcconfig’dəki dəyişənlər digər dəyişənlərə istinad edərək mürəkkəb dəyərlər yarada bilər. Məsələn: PRODUCT_NAME = MyApp, PRODUCT_BUNDLE_IDENTIFIER = com.example.$(PRODUCT_NAME). Xcode qurma mərhələsində dəyişənlərin cari dəyərlərini əvəz edərək dəyəri hesablayır. Həmçinin qurma mühiti tərəfindən təyin olunan sistem dəyişənləri dəstəklənir: ARCHS, SDK_NAME, CONFIGURATION, PLATFORM_NAME.

Şərti konfiqurasiya üçün kvadrat mötərizələrdə platforma direktivləri istifadə olunur: PARAMETER[sdk=iphoneos*] = value. Məsələn, SUPPORTED_PLATFORMS[sdk=iphoneos*] = iphoneos parametri yalnız iOS qurması üçün təyin edir. Maskalar dəstəklənir: * (istənilən simvollar), ? (bir simvol). Şərti direktivlər bir .xcconfig’i bir neçə platforma üçün istifadə etməyə və bir faylda iOS və macOS üçün fərqli dəyərlər təyin etməyə imkan verir.

// Shared.xcconfig — loyihaning umumiy sozlamalari
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 16.0
SDKROOT = iphoneos
TARGETED_DEVICE_FAMILY = 1,2

// Bundle identifikatori — prefiks va nomdan yig'iladi
BUNDLE_ID_PREFIX = com.example
PRODUCT_NAME = MyApp
PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)

// macOS uchun shartli sozlama
SUPPORTED_PLATFORMS[sdk=macosx*] = macosx
PRODUCT_BUNDLE_IDENTIFIER[sdk=macosx*] = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).mac

// Versiyalash
MARKETING_VERSION = 2.4.1
CURRENT_PROJECT_VERSION = 37

#include vasitəsilə konfiqurasiyaların mirası

#include — bu .xcconfig preprosessor direktividir və başqa .xcconfig faylının məzmununu qoşur. Direktivlər iç-içə yerləşdirilə bilər: Shared.xcconfig #include “Base.xcconfig”, Debug.xcconfig — #include “Shared.xcconfig” edə bilər. Miras zənciri hər səviyyənin əvvəlkilərin parametrlərini ləğv etdiyi konfiqurasiya iyerarxiyası qurmağa imkan verir. #include son yazılma prinsipi ilə işləyir: eyni parametr həm qoşulmuş, həm də əsas faylda təyin edilmişsə, əsas fayldakı dəyər üstünlük təşkil edir.

Tipik iOS layihəsi üçün düzgün iyerarxiya: Base.xcconfig (ən ümumi parametrlər) → Shared.xcconfig (layihə parametrləri) → Debug.xcconfig və ya Release.xcconfig. Base.xcconfig standartları (SWIFT_VERSION, DEPLOYMENT_TARGET), Shared.xcconfig — layihənin spesifikasını (PRODUCT_NAME, PREPROCESSOR_DEFINITIONS), Debug/Release — mühiti (DEBUG_INFORMATION_FORMAT, OPTIMIZATION_CFLAGS) təyin edir. #include dövrlərə icazə vermir — Xcode tsiklik asılılıq aşkar edildikdə xəta bildirir.

Nümunə: Config/Base.xcconfig → Config/iOS/Shared.xcconfig → Config/iOS/Debug.xcconfig. Bu struktur Base-i iOS, macOS və tvOS layihələri üçün, Shared-i isə yalnız iOS üçün təkrar istifadə etməyə imkan verir. Diqqət: #include fayl adından və ya kök .xcconfig-in yerləşdiyi yerdən nisbi yol istifadə edir. Mütləq yollar tövsiyə edilmir — onlar digər maşınlarda və CI/CD-də qurmanı pozur.

// --- 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

.xcconfig’i Xcode layihəsində birləşdirmə

Layihə səviyyəli və target səviyyəli konfiqurasiyalar

.xcconfig’in layihəyə qoşulması Project Info → Configurations bölməsində həyata keçirilir. Hər Build Configuration (Debug, Release, AdHoc) üçün açılan siyahıda “Based on Configuration File” müvafiq .xcconfig seçilir. Konfiqurasiya fayla bağlı deyilsə, Xcode project.pbxproj-dən dəyərlərdən istifadə edir. .xcconfig seçildikdən sonra fayldakı bütün parametrlər həmin konfiqurasiya üçün aktivləşir.

Layihə səviyyəli və Target səviyyəli konfiqurasiyaları fərqləndirmək vacibdir. Layihə səviyyəli .xcconfig bütün targetlər üçün standart parametrlər təyin edir. Target səviyyəli .xcconfig onları müşyyən bir target üçün ləğv edir. Parametr target .xcconfig’ində təyin edilməyibsə, layihə səviyyəsindən dəyər istifadə olunur. Orada da təyin edilməyibsə — project.pbxproj-dəndir. Praktik qayda: layihə səviyyəsində ümumi parametrləri (qurma, versiyalar), target səviyyəsində isə targetin spesifikasını (bundle identifier, provisioning) yerləşdirin.

.xcconfig və UI Build Settings arasında ziddiyyət olduqda, UI dəyəri üstünlük təşkil edir (.xcconfig’i ləğv edir). Bu qarışıqlığa səbəb ola bilər: tərtibatçı UI’da Build Setting’i dəyişir, .xcconfig’də başqa dəyərin göstərildiyini bilmədən. .xcconfig’ə tam keçid və UI Build Settings’ə toxunmamaq tövsiyə olunur. Hansı parametrin tətbiq olunduğunu yoxlamaq üçün xcrun xcodebuild -showBuildSettings istifadə edin — bu əmr bütün səviyyələr həll edildikdən sonra bütün parametrlərin yekun dəyərlərini göstərəcək.

Nümunə: Dev, Staging, Production mühitləri

Üç səviyyəli konfiqurasiyanı ko'rib chiqamiz: Dev (lokal inkişaf), Staging (test serveri), Production (buraxılış). Hər mühit üçün fərqli API_URL, loglama və sertifikat dəyərlərini təyin edən ayrı .xcconfig yaradılır. Dev localhost, Staging staging.api.example.com, Production api.example.com istifadə edir. Hər üçü #include vasitəsilə ümumi Shared.xcconfig’i miras alır.

Mühitlər arasında fərqlənən əsas parametr PRODUCT_BUNDLE_IDENTIFIER-dır. Dev üçün: com.example.myapp.dev, Staging üçün: com.example.myapp.staging, Production üçün: com.example.myapp. Fərqli bundle ID’lər hər üç versiyanı eyni anda bir cihazda quraşdırmağa imkan verir. Həmçinin CODE_SIGN_IDENTITY (Dev üçün Apple Development, Production üçün Apple Distribution) və PROVISIONING_PROFILE_SPECIFIER fərqlənir.

Koda dəyərləri ötürmək üçün INFOPLIST_PREFIX_HEADER və ya -D preprosessorlu OTHER_SWIFT_FLAGS istifadə olunur. Swift’də preprosessor yoxdur, buna görə Active Compilation Conditions istifadə olunur: SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEV. Koddada: #if DEV; #elseif STAGING; #else; #endif. Objective-C üçün GCC_PREPROCESSOR_DEFINITIONS istifadə olunur. Bu, mənbələri dəyişmədən müxtəlif mühitlər üçün fərqli kod yığmağa imkan verir.

// --- 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 orqali API URL — qiymat almashtiriladi
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 və Info.plist: dəyərlərin ötürülməsi

.xcconfig-dən dəyərlər $(PARAMETER_NAME) dəyişənləri vasitəsilə Info.plist-ə ötürülə bilər. Parametr .xcconfig-də təyin edilmişsə (məs. API_BASE_URL), onu Info.plist-də istifadə etmək olar: <key>ApiBaseUrl</key><string>$(API_BASE_URL)</string>. Qurma mərhələsində Xcode $(API_BASE_URL)-i .xcconfig-dən dəyərlə əvəz edir. Bu, kodu dəyişmədən tətbiqi konfiqurasiya etməyə imkan verir — sadəcə sxemi dəyişmək kifayətdir.

Info.plist-də istifadə olunan .xcconfig parametrləri ictimai olmalıdır — onlar binar fayla daxil olur və dekompilyasiya edilmiş tətbiqdə görünür. Məxfi dəyərlər (tokenlər, şifrələr) üçün .xcconfig istifadə etməyin — serverdə işləyən Firebase Remote Config kimi xidmətlərdən istifadə edin. .xcconfig Info.plist üçün uyğundur: server URL-ləri, obyekt adları, tracker identifikatorları, feature flag-lar.

Koddada Info.plist dəyərlərinə çıxış: Objective-C/Swift üçün Bundle.main.object(forInfoDictionaryKey: "ApiBaseUrl"). Dəyər .xcconfig vasitəsilə təyin edilmişsə, əvəz ediləcək və Bundle main.infoDictionary-də mövcud olacaq. Bu üsul BuildConfigField-dan (Android-də olduğu kimi) üstün tutulur, çünki Info.plist iOS-un standart mexanizmidir və onun dəyərləri extensions, widget və Siri Intents daxil olmaqla sistemin bütün komponentləri üçün əlçatandır.