.xcconfig — vad är det, syntax och variabler i Xcode

Ce este .xcconfig?

.xcconfig (Xcode Configuration File) — este un fișier text care conține Build Settings în formatul PARAMETER_NAME = value. Fișierele .xcconfig sunt utilizate pentru gestionarea centralizată a configurațiilor de build Xcode: ele înlocuiesc editarea manuală a câmpurilor în Build Settings UI. Fiecare .xcconfig este atașat unei Build Configuration (Debug, Release) sau întregului proiect și poate suprascrie orice setare de build: SWIFT_VERSION, IPHONEOS_DEPLOYMENT_TARGET, PRODUCT_BUNDLE_IDENTIFIER, CODE_SIGN_STYLE, PROVISIONING_PROFILE_SPECIFIER.

Înainte de apariția .xcconfig, setările de build erau stocate doar în project.pbxproj — un fișier binar/plist care este greu de citit în diff-uri și nu poate fi comentat. .xcconfig a rezolvat această problemă: dezvoltatorii pot comenta parametrii, îi pot grupa după sens, pot crea fișiere versionabile pentru diferite medii și pot moșteni parametri între fișiere. Aceasta a făcut din .xcconfig un standard de facto pentru gestionarea configurațiilor în proiectele iOS.

Fișierele .xcconfig se află în interiorul proiectului, de obicei în folderul Configurations/ sau BuildConfig/. Fiecare fișier corespunde unei Build Configuration: Debug.xcconfig, Release.xcconfig, Staging.xcconfig. În plus, se creează un fișier comun Shared.xcconfig care este atașat la toate configurațiile prin #include. Aceasta permite definirea parametrilor comuni o dată și suprascrierea celor specifici în fișierele de configurare.

Avantaje față de UI Build Settings

Lizibilitatea diff-urilor: modificările .xcconfig sunt vizibile în Git diff ca linii obișnuite. Spre deosebire de project.pbxproj, unde din cauza schimbării ordinii câmpurilor diff-ul arată 50 de linii de modificări la editarea unui singur parametru. Comentarii: în .xcconfig se poate explica de ce este necesar fiecare parametru. Moștenire: se poate crea o configurare de bază cu setări comune și suprascrie doar parametrii necesari pentru Debug și Release.

Sintaxa și structura .xcconfig

Variabile și substituiri

Sintaxa .xcconfig este extrem de simplă: fiecare linie este un parametru, numele și valoarea după semnul egal. Spațiile în jurul lui = sunt ignorate. Valorile pot conține variabile în formatul $(VARIABLE_NAME) sau ${VARIABLE_NAME}. Comentariile încep cu // sau # și sunt valabile până la sfârșitul liniei. Liniile continuă pe linia următoare cu ajutorul barei oblice inverse \. Liniile goale sunt ignorate.

Variabilele în .xcconfig pot face referire la alte variabile, creând valori compozite. De exemplu: PRODUCT_NAME = MyApp, PRODUCT_BUNDLE_IDENTIFIER = com.example.$(PRODUCT_NAME). Xcode calculează valoarea în etapa de build, substituind valorile curente ale variabilelor. Sunt suportate și variabilele de sistem: ARCHS, SDK_NAME, CONFIGURATION, PLATFORM_NAME, care sunt setate de mediul de build.

Pentru configurarea condițională se utilizează directive de platformă în paranteze pătrate: PARAMETER[sdk=iphoneos*] = value. De exemplu, SUPPORTED_PLATFORMS[sdk=iphoneos*] = iphoneos setează parametrul doar pentru build-ul iOS. Sunt suportate măștile: * (orice caractere), ? (un caracter). Directivele condiționale permit să aveți un singur .xcconfig pentru mai multe platforme și să setați valori diferite pentru iOS și macOS în același fișier.

// Shared.xcconfig — allmänna projektinställningar
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 16.0
SDKROOT = iphoneos
TARGETED_DEVICE_FAMILY = 1,2

// Bundle-identifierare — sammansatt av prefix och namn
BUNDLE_ID_PREFIX = com.example
PRODUCT_NAME = MyApp
PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)

// Villkorlig inställning för macOS
SUPPORTED_PLATFORMS[sdk=macosx*] = macosx
PRODUCT_BUNDLE_IDENTIFIER[sdk=macosx*] = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).mac

// Versionshantering
MARKETING_VERSION = 2.4.1
CURRENT_PROJECT_VERSION = 37

Moștenirea configurațiilor prin #include

#include — este o directivă a preprocesorului .xcconfig care include conținutul altui fișier .xcconfig. Directivele pot fi imbricate: Shared.xcconfig poate #include „Base.xcconfig”, Debug.xcconfig — #include „Shared.xcconfig”. Lanțul de moștenire permite construirea unei ierarhii de configurații, unde fiecare nivel suprascrie parametrii celui anterior. #include funcționează pe principiul ultimei înregistrări: dacă același parametru este definit atât în fișierul inclus, cât și în cel principal, valoarea din fișierul principal are prioritate.

Ierarhia corectă pentru un proiect iOS tipic: Base.xcconfig (cei mai generali parametri) → Shared.xcconfig (setările proiectului) → Debug.xcconfig sau Release.xcconfig. Base.xcconfig definește standardele (SWIFT_VERSION, DEPLOYMENT_TARGET), Shared.xcconfig — specificul proiectului (PRODUCT_NAME, PREPROCESSOR_DEFINITIONS), Debug/Release — mediul (DEBUG_INFORMATION_FORMAT, OPTIMIZATION_CFLAGS). #include nu permite cicluri — Xcode va raporta o eroare la detectarea unei dependențe ciclice.

Exemplu: Config/Base.xcconfig → Config/iOS/Shared.xcconfig → Config/iOS/Debug.xcconfig. Această structură permite reutilizarea Base pentru proiecte iOS, macOS și tvOS, iar Shared — doar pentru iOS. Atenție: #include utilizează numele fișierului sau calea relativă față de locația .xcconfig-ului principal. Căile absolute nu sunt recomandate — ele strică build-ul pe alte mașini și în CI/CD.

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

Conectarea .xcconfig în proiectul Xcode

Configurații la nivel de proiect și de target

Conectarea .xcconfig la proiect se realizează în Project Info → Configurations. Pentru fiecare Build Configuration (Debug, Release, AdHoc) în lista derulantă „Based on Configuration File” se selectează .xcconfig-ul corespunzător. Dacă configurația nu este asociată unui fișier, Xcode utilizează valorile din project.pbxproj. După selectarea .xcconfig, toți parametrii din fișier devin activi pentru acea configurație.

Este important să distingem configurațiile la nivel de Project-level și Target-level. .xcconfig la nivel de proiect setează parametrii impliciți pentru toate target-urile. .xcconfig la nivel de target îi suprascrie pentru un anumit target. Dacă un parametru nu este setat în .xcconfig-ul target-ului, se utilizează valoarea de la nivelul proiectului. Dacă nici acolo nu este setat — din project.pbxproj. Regula practică: în proiect plasați parametrii generali (build, versiuni), în target — specificul target-ului (bundle identifier, provisioning).

În caz de conflict între .xcconfig și UI Build Settings, valoarea din UI are prioritate (suprascrie .xcconfig). Aceasta poate duce la confuzii: dezvoltatorul modifică Build Setting în UI, neștiind că în .xcconfig este specificată o altă valoare. Se recomandă trecerea completă la .xcconfig și să nu atingeți UI Build Settings. Pentru a verifica ce parametru se aplică, utilizați xcrun xcodebuild -showBuildSettings — comanda va afișa valorile finale ale tuturor parametrilor după rezolvarea tuturor nivelurilor.

Exemplu: medii Dev, Staging, Production

Să analizăm o configurare pe trei niveluri: Dev (dezvoltare locală), Staging (server de testare), Production (lansare). Pentru fiecare mediu se creează un .xcconfig separat, care definește valori diferite pentru API_URL, logare și certificate. Dev utilizează localhost, Staging — staging.api.example.com, Production — api.example.com. Toate trei moștenesc Shared.xcconfig comun prin #include.

Parametrul cheie care diferențiază mediile este PRODUCT_BUNDLE_IDENTIFIER. Pentru Dev: com.example.myapp.dev, pentru Staging: com.example.myapp.staging, pentru Production: com.example.myapp. Diferitele bundle ID permit instalarea tuturor celor trei versiuni pe același dispozitiv simultan. De asemenea, diferă CODE_SIGN_IDENTITY (Apple Development pentru Dev, Apple Distribution pentru Production) și PROVISIONING_PROFILE_SPECIFIER.

Pentru transmiterea valorilor în cod se utilizează INFOPLIST_PREFIX_HEADER sau OTHER_SWIFT_FLAGS cu preprocesorul -D. În Swift nu există preprocesor, de aceea se utilizează Active Compilation Conditions: SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEV. În cod: #if DEV; #elseif STAGING; #else; #endif. Pentru Objective-C se utilizează GCC_PREPROCESSOR_DEFINITIONS. Aceasta permite compilarea de cod diferit pentru diferite medii fără modificarea surselor.

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

// API-URL via Info.plist — värdet ersätts
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 și Info.plist: transmiterea valorilor

Valorile din .xcconfig pot fi transmise în Info.plist prin variabilele $(PARAMETER_NAME). Dacă parametrul este definit în .xcconfig (de exemplu, API_BASE_URL), acesta poate fi utilizat în Info.plist: <key>ApiBaseUrl</key><string>$(API_BASE_URL)</string>. În etapa de build, Xcode înlocuiește $(API_BASE_URL) cu valoarea din .xcconfig. Aceasta permite configurarea aplicației fără modificarea codului — este suficient să schimbați schema.

Parametrii .xcconfig utilizați în Info.plist trebuie să fie publici — ei ajung în fișierul binar și sunt vizibili în aplicația decompilată. Pentru valori secrete (tokenuri, parole) nu utilizați .xcconfig — utilizați servicii precum Firebase Remote Config, care rulează pe server. .xcconfig pentru Info.plist este potrivit pentru: URL-uri de servere, nume de entități, identificatori de trackere, feature flags.

Accesul la valorile Info.plist în cod: Bundle.main.object(forInfoDictionaryKey: "ApiBaseUrl") pentru Objective-C/Swift. Dacă valoarea este setată prin .xcconfig, aceasta va fi substituită și disponibilă în Bundle main.infoDictionary. Această metodă este preferată față de BuildConfigField (ca în Android), deoarece Info.plist este un mecanism standard iOS, iar valorile sale sunt accesibile tuturor componentelor sistemului, inclusiv extensiilor, widget-urilor și Siri Intents.