.xcconfig — какво е това, синтаксис и променливи в Xcode

Шта је .xcconfig?

.xcconfig (Xcode Configuration File) — је текстуални фајл који садржи Build Settings в формат PARAMETER_NAME = value. .xcconfig датотеке се користе за централно управлявање Xcode конфигурацияма изградње: оне замењују ручно уређивање поља у Build Settings UI. Сваки .xcconfig је везан за Build Configuration (Debug, Release) или цеокупни пројекат и може да преиспише било коју build setting: SWIFT_VERSION, IPHONEOS_DEPLOYMENT_TARGET, PRODUCT_BUNDLE_IDENTIFIER, CODE_SIGN_STYLE, PROVISIONING_PROFILE_SPECIFIER.

Пре појаве .xcconfig-а, поставке изградње су се чувале само у project.pbxproj — бинарном/plist фајлу који је тешко читати у diff-овима и не може бити коментарисан. .xcconfig је решио овај проблем: програмисти могу да коментаришу параметри, групишу их по значењу, креирају верзиониване датотеке за различита окружења и наслеђују параметри между датотека. Ово је учинило .xcconfig де факто стандардом за управлявање конфигурацияма у iOS пројектима.

.xcconfig датотеке се налазе унутар проекта, обично у фајловској фасцикли Configurations/ или BuildConfig/. Свака датотека одговара једној Build Configuration: Debug.xcconfig, Release.xcconfig, Staging.xcconfig. Додатно се креира заједнички фајл Shared.xcconfig који се повезује са свим конфигурацияма путем #include. Ово омогућава дефинисање заједничких параметара једном и преисписивање специфичних у конфигурационим датотекама.

Предности у односу на UI Build Settings

Читљивост diff-ова: промене у .xcconfig-у су видљиве у Git diff-у као обични линије. За разлику од project.pbxproj, где због промене редоследа поља diff показује 50 линија промене при уређивању једног параметра. Коментари: у .xcconfig-у се може објаснити чему служи сваки параметар. Наслеђивање: може се креирати базна конфигурация са заједничким поставкама и преисписивати само потребне параметри за Debug и Release.

Синтакса и структура .xcconfig-а

Промељиве и замене

Синтакса .xcconfig-а је изузетно једноставна: сваки ред је параметар, назив и вредност након знака једнакости. Размаки око = се занемарују. Вредности могу садржавати променливи в формат $(VARIABLE_NAME) или ${VARIABLE_NAME}. Коментари почињу са // или # и трају до краја реда. Редови се настављају у следећем реду помоћу обрнуте косе \\ . Празни редови се занемарују.

Промељиве у .xcconfig-у могу да се позивају на друге променливи, стварајући зложне вредности. На пример: PRODUCT_NAME = MyApp, PRODUCT_BUNDLE_IDENTIFIER = com.example.$(PRODUCT_NAME). Xcode израчунава вредност у фази изградње, замењујући тренутне вредности промељивих. Системске променливи су такође подржане: ARCHS, SDK_NAME, CONFIGURATION, PLATFORM_NAME, које поставља окружење изградње.

За условну конфигурацију користе се директиве платформе у угластим заградама: PARAMETER[sdk=iphoneos*] = value. На пример, SUPPORTED_PLATFORMS[sdk=iphoneos*] = iphoneos поставља параметар само за iOS изградњу. Подржане су маске: * (било који знакови), ? (један знак). Условне директиве омогућавају да имате један .xcconfig за више платформи и поставите различите вредности за iOS и macOS у једној датотеци.

// Shared.xcconfig — общи настройки на проекта
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 16.0
SDKROOT = iphoneos
TARGETED_DEVICE_FAMILY = 1,2

// Bundle идентификатор — съставя се от префикс и име
BUNDLE_ID_PREFIX = com.example
PRODUCT_NAME = MyApp
PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)

// Условна настройка за macOS
SUPPORTED_PLATFORMS[sdk=macosx*] = macosx
PRODUCT_BUNDLE_IDENTIFIER[sdk=macosx*] = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).mac

// Версиониране
MARKETING_VERSION = 2.4.1
CURRENT_PROJECT_VERSION = 37

Наслеђивање конфигурация путем #include

#include — је директива препроцесора .xcconfig-а која укључује садржај друге .xcconfig датотеке. Директиве се могу угнездивати: Shared.xcconfig може #include „Base.xcconfig“, Debug.xcconfig — #include „Shared.xcconfig“. Ланац наслеђивања омогућава изградњу хијерархије конфигурация, где сваки ниво преисписује параметри претходног. #include ради по принципу последње записи: ако је исти параметар дефинисан и у укљученој и у главној датотеци, приоритет има вредност из главне.

Исправна хијерархија за типичан iOS пројекат: Base.xcconfig (најопштији параметри) → Shared.xcconfig (поставке проекта) → Debug.xcconfig или Release.xcconfig. Base.xcconfig дефинише стандарде (SWIFT_VERSION, DEPLOYMENT_TARGET), Shared.xcconfig — специфику проекта (PRODUCT_NAME, PREPROCESSOR_DEFINITIONS), Debug/Release — окружење (DEBUG_INFORMATION_FORMAT, OPTIMIZATION_CFLAGS). #include не дозвољава циклусе — Xcode ће пријавити грешку при откривању цикличне зависности.

Пример: Config/Base.xcconfig → Config/iOS/Shared.xcconfig → Config/iOS/Debug.xcconfig. Оваква структура омогућава поновно коришћење Base-а за iOS, macOS и tvOS пројекте, а Shared-а само за iOS. Пажња: #include користи назив датотеке или релативну путању од локације главног .xcconfig-а. Апсолутни путење се не препоручују — они ломе изградњу на другим машинама и у 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

Повезивање .xcconfig-а в Xcode пројекту

Конфигурације на нивоу проекта и target-а

Повезивање .xcconfig-а са пројектом се врши у Project Info → Configurations. За сваку Build Configuration (Debug, Release, AdHoc) у падајућој листи „Based on Configuration File“ бира се одговарајући .xcconfig. Ако конфигурация није везана за датотеку, Xcode користи вредности из project.pbxproj. Након избора .xcconfig-а, сви параметри из датотеке постају активни за ту конфигурацију.

Важно је разликовати конфигурације на нивоу Project-level и Target-level. .xcconfig на нивоу проекта поставља подразумеване параметри за све target-е. .xcconfig на нивоу target-а их преисписује за одређени target. Ако параметар није постављен у .xcconfig-у target-а, користи се вредност са нивоа проекта. Ако није постављен ни тамо — из project.pbxproj. Практично правило: у пројекат стављајте опште параметри (изградња, верзије), у target — специфику target-а (bundle identifier, provisioning).

У случају сукоба между .xcconfig-а и UI Build Settings-а, приоритет има вредност из UI-а (преисписује .xcconfig). Ово може довести до збуне: програмер мења Build Setting у UI-у, не знајући да је у .xcconfig-у наведена друга вредност. Препорукује се потпуно прећи на .xcconfig и не дирате UI Build Settings. Да бисте проверили који се параметар примењује, користите xcrun xcodebuild -showBuildSettings — наредба ће показати коначне вредности свих параметара након решавања свих нивоа.

Пример: окружења Dev, Staging, Production

Размотрићемо тронивооску конфигурацију: Dev (локални развој), Staging (тест сервер), Production (издање). За свако окружење се креира посебан .xcconfig који дефинише различите вредности API_URL-а, логовања и сертификата. Dev користи localhost, Staging — staging.api.example.com, Production — api.example.com. Све три наслеђују заједнички Shared.xcconfig путем #include.

Кључни параметар који разликује окружења је PRODUCT_BUNDLE_IDENTIFIER. За Dev: com.example.myapp.dev, за Staging: com.example.myapp.staging, за Production: com.example.myapp. Различити bundle ID-ови омогућавају инсталацију све три верзије на једном уређају истовремено. Такође се разликују CODE_SIGN_IDENTITY (Apple Development за Dev, Apple Distribution за Production) и PROVISIONING_PROFILE_SPECIFIER.

За преношење вредности у код користи се INFOPLIST_PREFIX_HEADER или OTHER_SWIFT_FLAGS са препроцесором -D. У Swift-у нема препроцесора, па се користе Active Compilation Conditions: SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEV. У коду: #if DEV; #elseif STAGING; #else; #endif. За Objective-C се користи GCC_PREPROCESSOR_DEFINITIONS. Ово омогућава компилирање различитог кода за различита окружења без измене изворног кода.

// --- 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 чрез Info.plist — стойността се замества
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 и Info.plist: преношење вредности

Вредности из .xcconfig-а се могу пренети у Info.plist путем промељивих $(PARAMETER_NAME). Ако је параметар дефинисан у .xcconfig-у (нпр. API_BASE_URL), може се користити у Info.plist-у: <key>ApiBaseUrl</key><string>$(API_BASE_URL)</string>. У фази изградње, Xcode замењује $(API_BASE_URL) вредношћу из .xcconfig-а. Ово омогућава конфигурисање апликације без измене кода — довољно је пребацити шему.

Параметри .xcconfig-а који се користе у Info.plist-у морају бити јавни — они доспевају у бинарни фајл и видљиви су у декомпилираној апликацији. За тајне вредности (токенови, лозинке) не користите .xcconfig — користите услуге као што је Firebase Remote Config које раде на серверу. .xcconfig за Info.plist је погоднан за: URL сервера, називе ентитета, идентификаторе трећера, feature flag-ове.

Приступ вредностима Info.plist-а у коду: Bundle.main.object(forInfoDictionaryKey: "ApiBaseUrl") за Objective-C/Swift. Ако је вредност постављена путем .xcconfig-а, биће замењена и доступна у Bundle main.infoDictionary. Овај метод је пожељан од BuildConfigField (као у Android-у), јер Info.plist је стандардни iOS механизам, а његове вредности су доступне свим компонентама система, укључујући extensions, widgetе и Siri Intents.