모바일 앱의 Build Config — 정의, 설정 및 작동 원리

모바일 개발에서 Build Config란

Build Config는 모바일 애플리케이션의 컴파일, 빌드 및 패키징 프로세스를 정의하는 설정 모음입니다. 빌드 구성에는 대상 플랫폼 선택, 최소 SDK 버전, 최적화 플래그, 서명 키 및 환경 변수가 포함됩니다.

현대 모바일 프로젝트에는 단일 빌드 구성이 거의 없습니다. 일반적으로 여러 구성이 있습니다: debug(디버깅이 있는 개발용), release(최적화가 있는 프로덕션용), staging(실제 데이터로 테스트용) 및 다양한 플레이버(데모, 전체, 엔터프라이즈 버전).

Gradle Build Tool Survey(2025)에 따르면, 평균 Android 프로젝트는 3.2개의 다른 빌드 구성을 사용하고, iOS 프로젝트는 2.8개를 사용합니다. 각 구성은 자체 컴파일 플래그, 서명 인증서 및 서버 URL을 가질 수 있습니다.

Build Config의 주요 작업은 이러한 구성 간 전환을 자동화하는 것입니다. 개발자는 서버 URL이나 디버그 플래그를 수동으로 변경하는 대신 IDE에서 원하는 Build Variant를 선택하면 빌드 시스템이 해당 매개변수를 자동으로 적용합니다.

Build Config의 적절한 설정은 애플리케이션 보안에 중요한 영향을 미칩니다: debug 빌드에는 상세 로그, DB 인스펙터 및 디버깅 엔드포인트가 포함되며, 이는 release 바이너리에서 물리적으로 제외되어야 합니다. Gradle은 Build Types를 통해 이를 해결합니다: debug는 debuggable true 플래그를, release는 ProGuard와 함께 minifyEnabled true를 가질 수 있습니다. iOS는 Swift Active Compilation Conditions를 통해 동일한 작업을 수행하며, #if DEBUG 내부의 코드는 release 구성에서 컴파일되지 않습니다.

Android의 Build Config: Gradle과 BuildConfig

Android는 두 가지 주요 개념과 함께 Gradle 빌드 시스템을 사용합니다: Build Types와 Product Flavors. 이들의 조합이 Build Variants를 형성하며, 각 변형은 자체 완전한 빌드 구성을 가집니다.

Build Types: Debug와 Release

Build Type은 애플리케이션이 어떻게 빌드되는지를 정의하는 구성입니다. 기본적으로 Gradle은 두 가지 유형을 생성합니다: debug(디버깅 포함, 난독화 없음)와 release(ProGuard/R8 포함, 게시용 서명됨). 개발자는 자신의 유형(staging, benchmark, qa)을 추가할 수 있습니다.

// build.gradle.kts
android {
    buildTypes {
        debug {
            isDebuggable = true
            buildConfigField("String", "API_URL", "\"http://dev.api.com\"")
        }
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
            buildConfigField("String", "API_URL", "\"https://prod.api.com\"")
        }
    }
}

Product Flavors: 애플리케이션 버전

Product Flavors를 사용하면 단일 코드베이스에서 동일한 애플리케이션의 다른 버전을 만들 수 있습니다. 예: 광고가 있는 무료 버전, 광고가 없는 유료 버전, 추가 기능이 있는 엔터프라이즈 버전. 각 플레이버는 자체 applicationId, 리소스 및 SDK 종속성을 가질 수 있습니다.

android {
    productFlavors {
        register("demo") {
            applicationId = "com.example.app.demo"
            versionNameSuffix = "-demo"
        }
        register("full") {
            applicationId = "com.example.app"
            versionNameSuffix = ""
        }
    }
}

BuildConfig 클래스: 코드에서 접근

각 Build Variant에 대해 Gradle은 구성 필드가 있는 BuildConfig 클래스를 생성합니다. 개발자는 buildConfigField를 통해 사용자 정의 필드를 추가하고, 표준 필드(DEBUG, APPLICATION_ID, BUILD_TYPE, VERSION_CODE, FLAVOR)는 자동으로 생성됩니다.

// 코드에서 BuildConfig 사용
class NetworkModule {
    fun createApiClient(): ApiClient {
        return if (BuildConfig.DEBUG) {
            ApiClient(
                baseUrl = BuildConfig.API_URL,
                interceptor = HttpLoggingInterceptor()
            )
        } else {
            ApiClient(baseUrl = BuildConfig.API_URL)
        }
    }
}

BuildConfig를 사용하면 빌드 시간에 기능을 활성화 또는 비활성화할 수도 있습니다. 예를 들어, FEATURE_CHAT_ENABLED 필드를 추가하고 런타임 검사 및 코드의 조건 연산자 없이 애플리케이션의 전체 버전에서만 채팅을 활성화할 수 있습니다.

네트워크 요청 디버깅을 위해 DEBUG 필드가 있는 BuildConfig를 사용하면 debug 빌드에서만 OkHttp의 HttpLoggingInterceptor를 자동으로 연결할 수 있습니다. 이는 개발자가 실수로 릴리스 빌드 전에 로깅 제거를 잊어버린 경우에도 프로덕션에서 HTTP 요청이 기록되지 않음을 보장합니다.

iOS의 Build Config: Xcode와 Build Settings

iOS 생태계에서 Build Config는 Xcode Build Settings를 통해 관리됩니다 — 각 매개변수가 다른 구성(Debug, Release, Staging)에 대해 다른 값을 가질 수 있는 매개변수 테이블입니다.

Xcode Build Configurations

기본적으로 Xcode는 두 가지 구성을 생성합니다: Debug(개발용, 최적화 없음)와 Release(프로덕션용, -Os 최적화 포함). 개발자는 Project > Info > Configurations 메뉴를 통해 자신의 구성을 추가할 수 있습니다.

각 구성에 대해 Build Settings가 구성됩니다: 컴파일러 플래그(OTHER_SWIFT_FLAGS, GCC_PREPROCESSOR_DEFINITIONS), 코드 서명(CODE_SIGN_IDENTITY), 프로비저닝 프로필 및 entitlements. Xcode는 이러한 설정을 project.pbxproj 파일에 기록합니다.

xcconfig: 외부 구성 파일

Build Settings를 편리하게 관리하기 위해 iOS 개발자는 .xcconfig 파일을 사용합니다 — KEY = VALUE 형식의 매개변수가 있는 텍스트 파일입니다. 이는 Xcode용 .env와 유사합니다: 값이 프로젝트에 연결되고 project.pbxproj의 설정을 재정의합니다.

// Debug.xcconfig
BUNDLE_ID_SUFFIX = .debug
API_BASE_URL = http://localhost:8080
SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG
CODE_SIGN_IDENTITY = Apple Development

// Release.xcconfig
BUNDLE_ID_SUFFIX =
API_BASE_URL = https://api.production.com
SWIFT_ACTIVE_COMPILATION_CONDITIONS =
CODE_SIGN_IDENTITY = Apple Distribution

Info.plist: 런타임 구성

Build Config 매개변수 중 일부는 Info.plist — iOS 애플리케이션 매니페스트 파일에 저장됩니다. Info.plist를 통해 URL 스키마, 권한(카메라, 마이크), 백그라운드 모드 및 타사 서비스 로그인 구성이 설정됩니다.

xcconfig의 값은 $(VARIABLE_NAME) 구문을 사용하여 Info.plist에 대입할 수 있습니다. 예를 들어, Info.plist의 $(API_BASE_URL)은 활성 빌드 구성에 따라 확장됩니다. 이는 모든 Apple 플랫폼에 대한 환경 매개변수 관리를 중앙화합니다.

CI/CD 파이프라인의 Build Config

현대 프로젝트에서 Build Config는 지속적 통합 시스템(GitLab CI, GitHub Actions, Bitrise, CircleCI)과 통합됩니다. 각 파이프라인은 CI/CD 시스템의 환경 변수를 통해 Build Config 매개변수를 재정의할 수 있습니다.

CI의 Gradle Build Config

Android의 경우 CI 파이프라인이 지정된 Build Variant로 Gradle을 실행합니다: ./gradlew assembleFullRelease. 서명 매개변수는 CI 변수(STORE_PASSWORD, KEY_ALIAS)를 통해 전달됩니다. Gradle은 런타임 환경에서 이를 읽고 build.gradle.kts에 대입합니다.

// build.gradle.kts — CI 변수에서 읽기
android {
    signingConfigs {
        register("release") {
            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "debug.keystore")
            storePassword = System.getenv("STORE_PASSWORD") ?: ""
            keyAlias = System.getenv("KEY_ALIAS") ?: "key"
            keyPassword = System.getenv("KEY_PASSWORD") ?: ""
        }
    }
}

CI의 Xcode Build Config

iOS의 경우 CI는 구성 플래그와 함께 xcodebuild를 사용합니다: -configuration Release. 서명 인증서는 CI secrets를 통해, 프로필은 Apple Developer Portal API 또는 Fastlane match를 통해 제공됩니다.

Fastlane 도구는 Build Config 관리를 자동화합니다: xcconfig 생성, Info.plist 버전 업데이트, 빌드된 IPA 서명, App Store Connect에 업로드. Fastlane gym(빌드)과 match(서명)은 iOS CI 파이프라인의 표준입니다.

Bitrise Build Report(2025)에 따르면, CI에서 Build Config를 설정한 프로젝트는 수동 빌드 구성 시간을 73% 줄이고 서명 오류를 89% 줄입니다. 자동화된 Build Config는 프로덕션 준비 파이프라인의 필수 요소입니다.

또 다른 중요한 측면은 Build Config를 통한 버전 관리 매개변수화입니다. Gradle은 CI 변수에서 versionCode와 versionName을 읽고 build.gradle.kts에 동적으로 대입할 수 있어 개발자 간 버전 비동기화를 제거합니다. iOS에서는 agvtool(Apple Generic Versioning Tool)을 통해 유사한 작업이 해결되며, git 태그 또는 CI의 빌드 번호를 기반으로 빌드 번호를 증가시킬 수 있습니다.