.xcconfig — 정의, 구문 및 Xcode 변수

.xcconfig란?

.xcconfig(Xcode 구성 파일)는 PARAMETER_NAME = value 형식으로 Build Settings를 포함하는 일반 텍스트 파일입니다. .xcconfig 파일은 Xcode 빌드 구성을 중앙에서 관리하는 데 사용됩니다. Build Settings UI에서 필드를 수동으로 편집하는 것을 대체합니다. 각 .xcconfig는 Build Configuration(Debug, Release) 또는 프로젝트 전체에 연결되며 SWIFT_VERSION, IPHONEOS_DEPLOYMENT_TARGET, PRODUCT_BUNDLE_IDENTIFIER, CODE_SIGN_STYLE, PROVISIONING_PROFILE_SPECIFIER 등 모든 build setting을 재정의할 수 있습니다.

.xcconfig가 등장하기 전에는 빌드 설정이 project.pbxproj(바이너리/plist 파일)에만 저장되어 diff에서 읽기가 어렵고 주석을 달 수 없었습니다. .xcconfig는 이 문제를 해결했습니다. 개발자는 매개변수에 주석을 달고, 의미별로 그룹화하고, 다양한 환경에 대해 버전 관리 가능한 파일을 만들고, 파일 간에 매개변수를 상속할 수 있습니다. 이로 인해 .xcconfig는 iOS 프로젝트에서 구성 관리의 사실상 표준이 되었습니다.

.xcconfig 파일은 프로젝트 내부, 일반적으로 Configurations/ 또는 BuildConfig/ 폴더에 있습니다. 각 파일은 Debug.xcconfig, Release.xcconfig, Staging.xcconfig와 같은 하나의 Build Configuration에 해당합니다. 또한 #include를 통해 모든 구성에 포함되는 공통 Shared.xcconfig 파일이 생성됩니다. 이를 통해 공통 매개변수를 한 번 정의하고 구성 파일에서 특정 매개변수를 재정의할 수 있습니다.

UI Build Settings 대비 장점

Diff 가독성: .xcconfig의 변경 사항은 Git diff에서 일반 줄로 표시됩니다. 필드 순서 변경 시 단일 매개변수 편집에 50줄의 변경 사항이 표시되는 project.pbxproj와 대조적입니다. 주석: .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_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는 “Base.xcconfig”를 #include할 수 있고, Debug.xcconfig는 “Shared.xcconfig”를 #include할 수 있습니다. 상속 체인을 통해 각 수준이 이전 수준의 매개변수를 재정의하는 구성 계층 구조를 구축할 수 있습니다. #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

Xcode 프로젝트에서 .xcconfig 연결

프로젝트 수준 및 타겟 수준 구성

.xcconfig를 프로젝트에 연결하는 것은 Project Info → Configurations에서 수행됩니다. 각 Build Configuration(Debug, Release, AdHoc)에 대해 “Based on Configuration File” 드롭다운에서 해당 .xcconfig를 선택합니다. 구성이 파일에 연결되지 않은 경우 Xcode는 project.pbxproj의 값을 사용합니다. .xcconfig를 선택하면 파일의 모든 매개변수가 해당 구성에 대해 활성화됩니다.

프로젝트 수준과 타겟 수준 구성을 구분하는 것이 중요합니다. 프로젝트 수준 .xcconfig는 모든 타겟에 대한 기본 매개변수를 설정합니다. 타겟 수준 .xcconfig는 특정 타겟에 대해 이를 재정의합니다. 타겟 수준 .xcconfig에 매개변수가 설정되지 않은 경우 프로젝트 수준의 값이 사용됩니다. 거기에도 설정되지 않은 경우 project.pbxproj의 값이 사용됩니다. 실용적인 규칙: 공통 매개변수(빌드, 버전)는 프로젝트 수준에 배치하고, 타겟 고유 사항(번들 식별자, 프로비저닝)은 타겟 수준에 배치합니다.

.xcconfig와 UI Build Settings 간에 충돌이 있는 경우 UI의 값이 우선합니다(.xcconfig를 재정의). 이로 인해 혼란이 발생할 수 있습니다. 개발자는 .xcconfig가 다른 값을 지정하고 있다는 것을 모른 채 UI에서 Build Setting을 변경합니다. .xcconfig로 완전히 전환하고 UI Build Settings를 건드리지 않는 것이 좋습니다. 어떤 매개변수가 적용되고 있는지 확인하려면 xcrun xcodebuild -showBuildSettings를 사용하세요. 이 명령은 모든 수준을 해결한 후 모든 매개변수의 최종 값을 표시합니다.

예: Dev, Staging, Production 환경

3단계 구성을 고려해 보겠습니다: Dev(로컬 개발), Staging(테스트 서버), Production(릴리스). 각 환경에 대해 별도의 .xcconfig가 생성되며, 서로 다른 API_URL, 로깅 및 인증서 값을 정의합니다. Dev는 localhost를 사용하고, Staging은 staging.api.example.com을 사용하며, Production은 api.example.com을 사용합니다. 세 가지 모두 #include를 통해 공통 Shared.xcconfig를 상속합니다.

환경 간에 다른 주요 매개변수는 PRODUCT_BUNDLE_IDENTIFIER입니다. Dev의 경우: com.example.myapp.dev, Staging의 경우: com.example.myapp.staging, Production의 경우: com.example.myapp입니다. 다른 번들 ID를 사용하면 세 가지 버전을 모두 단일 장치에 동시에 설치할 수 있습니다. CODE_SIGN_IDENTITY(Dev의 경우 Apple Development, Production의 경우 Apple Distribution) 및 PROVISIONING_PROFILE_SPECIFIER도 다릅니다.

코드에 값을 전달하려면 INFOPLIST_PREFIX_HEADER 또는 -D 전처리기와 함께 OTHER_SWIFT_FLAGS를 사용합니다. 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

// Info.plist를 통한 API URL — 값이 대체됨
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의 값은 변수 $(PARAMETER_NAME)를 통해 Info.plist로 전달할 수 있습니다. .xcconfig에 매개변수가 정의된 경우(예: API_BASE_URL) Info.plist에서 사용할 수 있습니다: <key>ApiBaseUrl</key><string>$(API_BASE_URL)</string>. 빌드 시 Xcode는 $(API_BASE_URL)을 .xcconfig의 값으로 바꿉니다. 이를 통해 코드를 변경하지 않고도 애플리케이션을 구성할 수 있습니다. 스킴만 전환하면 됩니다.

Info.plist에서 사용되는 .xcconfig 매개변수는 공개여야 합니다. 이들은 바이너리에 포함되어 디컴파일된 애플리케이션에서 볼 수 있습니다. 비밀 값(토큰, 비밀번호)에는 .xcconfig를 사용하지 마세요. 서버에서 실행되는 Firebase Remote Config와 같은 서비스를 사용하세요. Info.plist용 .xcconfig는 서버 URL, 엔터티 이름, 추적기 식별자, feature flags에 적합합니다.

코드에서 Info.plist 값에 액세스: Objective-C/Swift의 경우 Bundle.main.object(forInfoDictionaryKey: “ApiBaseUrl”). 값이 .xcconfig를 통해 설정된 경우 대체되어 Bundle main.infoDictionary에서 사용할 수 있습니다. 이 방법은 Info.plist가 표준 iOS 메커니즘이고 그 값이 extensions, widgets 및 Siri Intents를 포함한 모든 시스템 구성 요소에서 사용할 수 있기 때문에 BuildConfigField(Android에서와 같이)보다 선호됩니다.