.xcconfig — définition, syntaxe et variables dans Xcode

Qu’est-ce que .xcconfig ?

.xcconfig (fichier de configuration Xcode) est un fichier texte brut qui contient les Build Settings au format PARAMETER_NAME = value. Les fichiers .xcconfig sont utilisés pour la gestion centralisée des configurations de compilation Xcode : ils remplacent la modification manuelle des champs dans l’interface Build Settings. Chaque .xcconfig est lié à une Build Configuration (Debug, Release) ou au projet dans son ensemble et peut remplacer n’importe quel build setting : SWIFT_VERSION, IPHONEOS_DEPLOYMENT_TARGET, PRODUCT_BUNDLE_IDENTIFIER, CODE_SIGN_STYLE, PROVISIONING_PROFILE_SPECIFIER.

Avant l’apparition de .xcconfig, les paramètres de compilation étaient stockés uniquement dans project.pbxproj — un fichier binaire/plist difficile à lire dans les diff et impossible à commenter. .xcconfig a résolu ce problème : les développeurs peuvent commenter les paramètres, les regrouper par signification, créer des fichiers versionnables pour différents environnements et hériter des paramètres entre fichiers. Cela a fait de .xcconfig le standard de facto pour la gestion de configuration dans les projets iOS.

Les fichiers .xcconfig se trouvent dans le projet, généralement dans le dossier Configurations/ ou BuildConfig/. Chaque fichier correspond à une Build Configuration : Debug.xcconfig, Release.xcconfig, Staging.xcconfig. De plus, un fichier Shared.xcconfig commun est créé, inclus dans toutes les configurations via #include. Cela permet de définir les paramètres communs une seule fois et de remplacer les paramètres spécifiques dans les fichiers de configuration.

Avantages par rapport aux Build Settings de l’interface

Lisibilité des diff : les modifications dans .xcconfig sont visibles dans Git diff comme des lignes normales. Contrairement à project.pbxproj, où le changement de l’ordre des champs affiche 50 lignes de modifications pour une seule modification de paramètre. Commentaires : dans .xcconfig, vous pouvez expliquer pourquoi chaque paramètre est nécessaire. Héritage : vous pouvez créer une configuration de base avec des paramètres communs et ne remplacer que les paramètres nécessaires pour Debug et Release.

Syntaxe et structure de .xcconfig

Variables et substitutions

La syntaxe de .xcconfig est aussi simple que possible : chaque ligne est un paramètre, nom et valeur séparés par un signe égal. Les espaces autour de = sont ignorés. Les valeurs peuvent contenir des variables au format $(VARIABLE_NAME) ou ${VARIABLE_NAME}. Les commentaires commencent par // ou # et s’appliquent jusqu’à la fin de la ligne. Les lignes se poursuivent sur la ligne suivante à l’aide d’une barre oblique inversée \. Les lignes vides sont ignorées.

Les variables dans .xcconfig peuvent référencer d’autres variables, créant des valeurs composites. Par exemple : PRODUCT_NAME = MyApp, PRODUCT_BUNDLE_IDENTIFIER = com.example.$(PRODUCT_NAME). Xcode évalue la valeur au moment de la compilation, en substituant les valeurs réelles des variables. AGP prend également en charge les variables système : ARCHS, SDK_NAME, CONFIGURATION, PLATFORM_NAME, définies par l’environnement de compilation.

Pour la configuration conditionnelle, des directives de plateforme entre crochets sont utilisées : PARAMETER[sdk=iphoneos*] = value. Par exemple, SUPPORTED_PLATFORMS[sdk=iphoneos*] = iphoneos définit le paramètre uniquement pour les compilations iOS. Les caractères génériques sont pris en charge : * (n’importe quel caractère), ? (un seul caractère). Les directives conditionnelles permettent d’avoir un seul .xcconfig pour plusieurs plateformes et de définir des valeurs différentes pour iOS et macOS dans un même fichier.

// Shared.xcconfig — paramètres communs du projet
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 16.0
SDKROOT = iphoneos
TARGETED_DEVICE_FAMILY = 1,2

// Identifiant de bundle — composé à partir du préfixe et du nom
BUNDLE_ID_PREFIX = com.example
PRODUCT_NAME = MyApp
PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)

// Configuration conditionnelle pour macOS
SUPPORTED_PLATFORMS[sdk=macosx*] = macosx
PRODUCT_BUNDLE_IDENTIFIER[sdk=macosx*] = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).mac

// Versionnage
MARKETING_VERSION = 2.4.1
CURRENT_PROJECT_VERSION = 37

Héritage des configurations via #include

#include est une directive de préprocesseur .xcconfig qui inclut le contenu d’un autre fichier .xcconfig. Les directives peuvent être imbriquées : Shared.xcconfig peut #include « Base.xcconfig », Debug.xcconfig peut #include « Shared.xcconfig ». La chaîne d’héritage permet de construire une hiérarchie de configurations, où chaque niveau remplace les paramètres du précédent. #include fonctionne sur le principe de la dernière écriture : si le même paramètre est défini à la fois dans le fichier inclus et dans le fichier principal, la valeur du fichier principal a priorité.

La hiérarchie correcte pour un projet iOS typique : Base.xcconfig (paramètres les plus courants) → Shared.xcconfig (paramètres du projet) → Debug.xcconfig ou Release.xcconfig. Base.xcconfig définit les normes (SWIFT_VERSION, DEPLOYMENT_TARGET), Shared.xcconfig — les spécificités du projet (PRODUCT_NAME, PREPROCESSOR_DEFINITIONS), Debug/Release — l’environnement (DEBUG_INFORMATION_FORMAT, OPTIMIZATION_CFLAGS). #include n’autorise pas les cycles — Xcode génère une erreur si une dépendance circulaire est détectée.

Exemple : Config/Base.xcconfig → Config/iOS/Shared.xcconfig → Config/iOS/Debug.xcconfig. Cette structure permet de réutiliser Base pour les projets iOS, macOS et tvOS, et Shared uniquement pour iOS. Remarque : #include utilise un nom de fichier ou un chemin relatif à partir de l’emplacement du .xcconfig racine. Les chemins absolus ne sont pas recommandés — ils cassent la compilation sur d’autres machines et dans 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

Connexion de .xcconfig dans un projet Xcode

Configurations au niveau projet et au niveau target

La connexion de .xcconfig à un projet se fait dans Project Info → Configurations. Pour chaque Build Configuration (Debug, Release, AdHoc), le .xcconfig correspondant est sélectionné dans le menu déroulant « Based on Configuration File ». Si une configuration n’est pas liée à un fichier, Xcode utilise les valeurs de project.pbxproj. Après avoir sélectionné .xcconfig, tous les paramètres du fichier deviennent actifs pour cette configuration.

Il est important de distinguer les configurations au niveau projet et au niveau target. Un .xcconfig au niveau projet définit les paramètres par défaut pour toutes les targets. Un .xcconfig au niveau target les remplace pour une target spécifique. Si un paramètre n’est pas défini dans le .xcconfig au niveau target, la valeur du niveau projet est utilisée. S’il n’est pas non plus défini là, la valeur de project.pbxproj est utilisée. Règle pratique : placez les paramètres communs (compilation, versions) au niveau projet, et les spécificités de la target (identifiant de bundle, provisionnement) au niveau target.

En cas de conflit entre .xcconfig et les Build Settings de l’interface, la valeur de l’interface a priorité (elle remplace .xcconfig). Cela peut prêter à confusion : un développeur modifie un Build Setting dans l’interface sans savoir que .xcconfig spécifie une valeur différente. Il est recommandé de migrer complètement vers .xcconfig et de ne pas toucher aux Build Settings de l’interface. Pour vérifier quel paramètre est appliqué, utilisez xcrun xcodebuild -showBuildSettings — la commande affichera les valeurs finales de tous les paramètres après résolution de tous les niveaux.

Exemple : environnements Dev, Staging, Production

Considérons une configuration à trois niveaux : Dev (développement local), Staging (serveur de test), Production (sortie). Un .xcconfig séparé est créé pour chaque environnement, définissant des valeurs différentes d’API_URL, de journalisation et de certificats. Dev utilise localhost, Staging utilise staging.api.example.com, Production utilise api.example.com. Les trois héritent du Shared.xcconfig commun via #include.

Le paramètre clé qui diffère entre les environnements est PRODUCT_BUNDLE_IDENTIFIER. Pour Dev : com.example.myapp.dev, pour Staging : com.example.myapp.staging, pour Production : com.example.myapp. Des bundle IDs différents permettent d’installer les trois versions sur un même appareil simultanément. Également différents : CODE_SIGN_IDENTITY (Apple Development pour Dev, Apple Distribution pour Production) et PROVISIONING_PROFILE_SPECIFIER.

Pour transmettre des valeurs au code, on utilise INFOPLIST_PREFIX_HEADER ou OTHER_SWIFT_FLAGS avec le préprocesseur -D. Swift n’a pas de préprocesseur, donc on utilise Active Compilation Conditions : SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEV. Dans le code : #if DEV; #elseif STAGING; #else; #endif. Pour Objective-C, on utilise GCC_PREPROCESSOR_DEFINITIONS. Cela permet de compiler un code différent pour différents environnements sans modifier les fichiers sources.

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

// URL de l’API via Info.plist — la valeur est substituée
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 et Info.plist : transfert de valeurs

Les valeurs de .xcconfig peuvent être transmises à Info.plist via des variables $(PARAMETER_NAME). Si un paramètre est défini dans .xcconfig (par exemple, API_BASE_URL), il peut être utilisé dans Info.plist : <key>ApiBaseUrl</key><string>$(API_BASE_URL)</string>. Au moment de la compilation, Xcode remplace $(API_BASE_URL) par la valeur de .xcconfig. Cela permet de configurer l’application sans modifier le code — il suffit de changer le schéma.

Les paramètres .xcconfig utilisés dans Info.plist doivent être publics — ils se retrouvent dans le binaire et sont visibles dans l’application décompilée. N’utilisez pas .xcconfig pour les valeurs secrètes (jetons, mots de passe) — utilisez des services comme Firebase Remote Config, exécutés sur le serveur. .xcconfig pour Info.plist convient pour : les URL des serveurs, les noms d’entités, les identifiants de traqueurs, les feature flags.

Accès aux valeurs Info.plist dans le code : Bundle.main.object(forInfoDictionaryKey: « ApiBaseUrl ») pour Objective-C/Swift. Si la valeur est définie via .xcconfig, elle sera substituée et disponible dans Bundle main.infoDictionary. Cette méthode est préférable à BuildConfigField (comme dans Android), car Info.plist est un mécanisme standard d’iOS et ses valeurs sont disponibles pour tous les composants système, y compris les extensions, les widgets et Siri Intents.