.xcconfig — τι είναι, σύνταξη και μεταβλητές στο Xcode

Τι είναι το .xcconfig;

.xcconfig (Xcode Configuration File) — είναι ένα αρχείο απλού κειμένου που περιέχει Build Settings σε μορφή PARAMETER_NAME = value. Τα αρχεία .xcconfig χρησιμοποιούνται για κεντρική διαχείριση των διαμορφώσεων κατασκευής του Xcode: αντικαθιστούν τη μη αυτόματη επεξεργασία πεδίων στο UI Build Settings. Κάθε .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 de facto πρότυπο για τη διαχείριση διαμορφώσεων σε έργα 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 υπολογίζει την τιμή κατά το στάδιο κατασκευής, αντικαθιστώντας τις τρέχουσες τιμές των μεταβλητών. Το AGP υποστηρίζει επίσης συστημικές μεταβλητές: 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

Διαμορφώσεις σε επίπεδο έργου και στόχου

Η σύνδεση του .xcconfig με το έργο γίνεται στο Project Info → Configurations. Για κάθε Build Configuration (Debug, Release, AdHoc) στο αναπτυσσόμενο μενού “Based on Configuration File” επιλέγεται το αντίστοιχο .xcconfig. Αν η διαμόρφωση δεν είναι συνδεδεμένη με αρχείο, το Xcode χρησιμοποιεί τιμές από το project.pbxproj. Μετά την επιλογή .xcconfig, όλες οι παράμετροι από το αρχείο γίνονται ενεργές για αυτή τη διαμόρφωση.

Είναι σημαντικό να διακρίνετε τις διαμορφώσεις Project-level και Target-level. Το Project-level .xcconfig ορίζει προεπιλεγμένες παραμέτρους για όλους τους στόχους. Το Target-level .xcconfig τις παρακάμπτει για συγκεκριμένο στόχο. Αν μια παράμετρος δεν ορίζεται στο target-level .xcconfig, χρησιμοποιείται η τιμή από το project-level. Αν δεν ορίζεται ούτε εκεί — από το project.pbxproj. Πρακτικός κανόνας: στο project-level τοποθετήστε κοινές παραμέτρους (κατασκευή, εκδόσεις), στο target-level — ειδικότητα στόχου (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 πρέπει να είναι δημόσιες — καταλήγουν στο δυαδικό αρχείο και είναι ορατές σε απομεταγλωττισμένη εφαρμογή. Για μυστικές τιμές (tokens, κωδικοί) μη χρησιμοποιείτε .xcconfig — χρησιμοποιήστε υπηρεσίες όπως Firebase Remote Config, που εκτελούνται στον διακομιστή. Το .xcconfig για Info.plist είναι κατάλληλο για: URL διακομιστών, ονόματα οντοτήτων, αναγνωριστικά tracker, feature flags.

Πρόσβαση στις τιμές του Info.plist στον κώδικα: Bundle.main.object(forInfoDictionaryKey: “ApiBaseUrl”) για Objective-C/Swift. Αν η τιμή ορίζεται μέσω .xcconfig, θα αντικατασταθεί και θα είναι διαθέσιμη στο Bundle main.infoDictionary. Αυτή η μέθοδος είναι προτιμότερη από το BuildConfigField (όπως στο Android), καθώς το Info.plist είναι ο τυπικός μηχανισμός iOS και οι τιμές του είναι διαθέσιμες σε όλα τα στοιχεία του συστήματος, συμπεριλαμβανομένων extensions, widget και Siri Intents.