.xcconfig — o que é, sintaxe e variáveis no Xcode

O que é .xcconfig?

.xcconfig (Arquivo de Configuração do Xcode) é um arquivo de texto simples que contém Build Settings no formato PARAMETER_NAME = value. Os arquivos .xcconfig são usados para gerenciamento centralizado das configurações de compilação do Xcode: eles substituem a edição manual de campos na interface Build Settings. Cada .xcconfig está vinculado a uma Build Configuration (Debug, Release) ou ao projeto como um todo e pode sobrescrever qualquer build setting: SWIFT_VERSION, IPHONEOS_DEPLOYMENT_TARGET, PRODUCT_BUNDLE_IDENTIFIER, CODE_SIGN_STYLE, PROVISIONING_PROFILE_SPECIFIER.

Antes do .xcconfig, as configurações de compilação eram armazenadas apenas em project.pbxproj — um arquivo binário/plist difícil de ler em diffs e impossível de comentar. O .xcconfig resolveu esse problema: os desenvolvedores podem comentar os parâmetros, agrupá-los por significado, criar arquivos versionáveis para diferentes ambientes e herdar parâmetros entre arquivos. Isso tornou o .xcconfig o padrão de facto para gerenciamento de configurações em projetos iOS.

Os arquivos .xcconfig estão localizados dentro do projeto, geralmente na pasta Configurations/ ou BuildConfig/. Cada arquivo corresponde a uma Build Configuration: Debug.xcconfig, Release.xcconfig, Staging.xcconfig. Além disso, um arquivo Shared.xcconfig comum é criado, incluído em todas as configurações via #include. Isso permite definir parâmetros comuns uma vez e sobrescrever os específicos nos arquivos de configuração.

Vantagens sobre os Build Settings da interface

Legibilidade em diff: as alterações no .xcconfig são visíveis no Git diff como linhas normais. Ao contrário do project.pbxproj, onde alterar a ordem dos campos resulta em 50 linhas de alterações para uma edição de parâmetro. Comentários: no .xcconfig você pode explicar por que cada parâmetro é necessário. Herança: você pode criar uma configuração base com configurações comuns e sobrescrever apenas os parâmetros necessários para Debug e Release.

Sintaxe e estrutura do .xcconfig

Variáveis e substituições

A sintaxe do .xcconfig é a mais simples possível: cada linha é um parâmetro, nome e valor separados por um sinal de igual. Espaços ao redor de = são ignorados. Os valores podem conter variáveis nos formatos $(VARIABLE_NAME) ou ${VARIABLE_NAME}. Os comentários começam com // ou # e se aplicam até o final da linha. As linhas continuam na próxima linha usando uma barra invertida \. Linhas vazias são ignoradas.

Variáveis no .xcconfig podem referenciar outras variáveis, criando valores compostos. Por exemplo: PRODUCT_NAME = MyApp, PRODUCT_BUNDLE_IDENTIFIER = com.example.$(PRODUCT_NAME). O Xcode avalia o valor no momento da compilação, substituindo os valores reais das variáveis. O AGP também suporta variáveis do sistema: ARCHS, SDK_NAME, CONFIGURATION, PLATFORM_NAME, definidas pelo ambiente de compilação.

Para configuração condicional, são usadas diretivas de plataforma entre colchetes: PARAMETER[sdk=iphoneos*] = value. Por exemplo, SUPPORTED_PLATFORMS[sdk=iphoneos*] = iphoneos define o parâmetro apenas para compilações iOS. Caracteres curinga são suportados: * (qualquer caractere), ? (um caractere). Diretivas condicionais permitem ter um .xcconfig para várias plataformas e definir valores diferentes para iOS e macOS em um único arquivo.

// Shared.xcconfig — configurações comuns do projeto
SWIFT_VERSION = 5.0
IPHONEOS_DEPLOYMENT_TARGET = 16.0
SDKROOT = iphoneos
TARGETED_DEVICE_FAMILY = 1,2

// Identificador de bundle — montado a partir do prefixo e nome
BUNDLE_ID_PREFIX = com.example
PRODUCT_NAME = MyApp
PRODUCT_BUNDLE_IDENTIFIER = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME)

// Configuração condicional para macOS
SUPPORTED_PLATFORMS[sdk=macosx*] = macosx
PRODUCT_BUNDLE_IDENTIFIER[sdk=macosx*] = $(BUNDLE_ID_PREFIX).$(PRODUCT_NAME).mac

// Versionamento
MARKETING_VERSION = 2.4.1
CURRENT_PROJECT_VERSION = 37

Herança de configurações via #include

#include é uma diretiva de pré-processador do .xcconfig que inclui o conteúdo de outro arquivo .xcconfig. As diretivas podem ser aninhadas: Shared.xcconfig pode #include “Base.xcconfig”, Debug.xcconfig pode #include “Shared.xcconfig”. A cadeia de herança permite construir uma hierarquia de configurações, onde cada nível sobrescreve os parâmetros do anterior. O #include funciona pelo princípio da última escrita: se o mesmo parâmetro estiver definido tanto no arquivo incluído quanto no principal, o valor do principal tem prioridade.

A hierarquia correta para um projeto iOS típico: Base.xcconfig (parâmetros mais comuns) → Shared.xcconfig (configurações do projeto) → Debug.xcconfig ou Release.xcconfig. Base.xcconfig define padrões (SWIFT_VERSION, DEPLOYMENT_TARGET), Shared.xcconfig — especificidades do projeto (PRODUCT_NAME, PREPROCESSOR_DEFINITIONS), Debug/Release — ambiente (DEBUG_INFORMATION_FORMAT, OPTIMIZATION_CFLAGS). O #include não permite ciclos — o Xcode emitirá um erro se uma dependência circular for detectada.

Exemplo: Config/Base.xcconfig → Config/iOS/Shared.xcconfig → Config/iOS/Debug.xcconfig. Essa estrutura permite reutilizar Base para projetos iOS, macOS e tvOS, e Shared apenas para iOS. Nota: #include usa um nome de arquivo ou caminho relativo a partir da localização do .xcconfig raiz. Caminhos absolutos não são recomendados — eles quebram a compilação em outras máquinas e em 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

Conexão do .xcconfig no projeto Xcode

Configurações em nível de projeto e de target

A conexão do .xcconfig a um projeto é feita em Project Info → Configurations. Para cada Build Configuration (Debug, Release, AdHoc), o .xcconfig correspondente é selecionado no menu suspenso “Based on Configuration File”. Se uma configuração não estiver vinculada a um arquivo, o Xcode usa os valores de project.pbxproj. Após selecionar o .xcconfig, todos os parâmetros do arquivo se tornam ativos para essa configuração.

É importante distinguir entre configurações em nível de projeto e em nível de target. Um .xcconfig em nível de projeto define parâmetros padrão para todos os targets. Um .xcconfig em nível de target os sobrescreve para um target específico. Se um parâmetro não estiver definido no .xcconfig de nível de target, o valor do nível de projeto é usado. Se também não estiver definido lá, o valor de project.pbxproj é usado. Regra prática: coloque parâmetros comuns (compilação, versões) no nível de projeto, e especificidades do target (identificador de bundle, provisionamento) no nível de target.

Em caso de conflito entre .xcconfig e Build Settings da interface, o valor da interface tem prioridade (sobrescreve .xcconfig). Isso pode causar confusão: um desenvolvedor altera uma Build Setting na interface sem saber que o .xcconfig especifica um valor diferente. Recomenda-se migrar completamente para .xcconfig e não tocar nas Build Settings da interface. Para verificar qual parâmetro está sendo aplicado, use xcrun xcodebuild -showBuildSettings — o comando mostrará os valores finais de todos os parâmetros após resolver todos os níveis.

Exemplo: ambientes Dev, Staging, Production

Considere uma configuração de três níveis: Dev (desenvolvimento local), Staging (servidor de teste), Production (lançamento). Um .xcconfig separado é criado para cada ambiente, definindo diferentes valores de API_URL, registro e certificados. Dev usa localhost, Staging usa staging.api.example.com, Production usa api.example.com. Todos os três herdam o Shared.xcconfig comum via #include.

O parâmetro chave que difere entre ambientes é PRODUCT_BUNDLE_IDENTIFIER. Para Dev: com.example.myapp.dev, para Staging: com.example.myapp.staging, para Production: com.example.myapp. Diferentes bundle IDs permitem instalar as três versões em um único dispositivo simultaneamente. Também diferem CODE_SIGN_IDENTITY (Apple Development para Dev, Apple Distribution para Production) e PROVISIONING_PROFILE_SPECIFIER.

Para passar valores para o código, são usados INFOPLIST_PREFIX_HEADER ou OTHER_SWIFT_FLAGS com pré-processador -D. Swift não possui pré-processador, então são usadas Active Compilation Conditions: SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEV. No código: #if DEV; #elseif STAGING; #else; #endif. Para Objective-C, usa-se GCC_PREPROCESSOR_DEFINITIONS. Isso permite compilar código diferente para ambientes diferentes sem alterar os arquivos fonte.

// --- 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 da API via Info.plist — o valor é substituído
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 e Info.plist: transferência de valores

Valores do .xcconfig podem ser passados para o Info.plist através de variáveis $(PARAMETER_NAME). Se um parâmetro estiver definido no .xcconfig (por exemplo, API_BASE_URL), ele pode ser usado no Info.plist: <key>ApiBaseUrl</key><string>$(API_BASE_URL)</string>. No momento da compilação, o Xcode substitui $(API_BASE_URL) pelo valor do .xcconfig. Isso permite configurar o aplicativo sem alterar o código — basta mudar o esquema.

Os parâmetros do .xcconfig usados no Info.plist devem ser públicos — eles vão para o binário e são visíveis no aplicativo descompilado. Não use .xcconfig para valores secretos (tokens, senhas) — use serviços como Firebase Remote Config, executados no servidor. .xcconfig para Info.plist é adequado para: URLs de servidores, nomes de entidades, identificadores de rastreadores, feature flags.

Acesso aos valores do Info.plist no código: Bundle.main.object(forInfoDictionaryKey: “ApiBaseUrl”) para Objective-C/Swift. Se o valor for definido via .xcconfig, ele será substituído e estará disponível em Bundle main.infoDictionary. Este método é preferível ao BuildConfigField (como no Android), pois o Info.plist é um mecanismo padrão do iOS e seus valores estão disponíveis para todos os componentes do sistema, incluindo extensions, widgets e Siri Intents.