Android Build-logic & Version Catalog

Gradle 빌드 관리: Build-logic , Version Catalog 정리

안녕하세요 이번 글에서는 안드로이드 프로젝트 빌드 관리 핵심 키워드인
Build-logic (컨벤션 플러그인)
Version Catalog (빌드 카탈로그)
를 정리해보겠습니다.

---

1. 필요성

멀티 모듈 프로젝트에서 build.gradle.kts 를 열어보면 이런 코드가 수십 개씩 반복됩니다.

plugins {
    id("com.android.library")
    id("org.jetbrains.kotlin.android")
}

android {
    compileSdk = 35
    defaultConfig {
        minSdk = 24
    }
}

dependencies {
    implementation("androidx.core:core-ktx:1.13.1")
}

문제는?

• 모든 모듈에 똑같은 설정이 복붙
• 라이브러리 버전 관리도 제각각
• 유지보수할 때 너무 힘듦

그래서 등장한 게 Version Catalog 와 Build-logic

---

2. Version Catalog (빌드 카탈로그)

정의

• Gradle 7.0 이상에서 제공하는 기능
• gradle/libs.versions.toml 파일에 라이브러리 버전과 좌표를 한 곳에 모아 관리

예시: libs.versions.toml

[versions]
core-ktx = "1.13.1"
appcompat = "1.7.0"
agp = "8.6.0"

[libraries]
core-ktx = { module = "androidx.core:core-ktx", version.ref = "core-ktx" }
appcompat = { module = "androidx.appcompat:appcompat", version.ref = "appcompat" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
android-library     = { id = "com.android.library", version.ref = "agp" }

사용하는 쪽 (모듈)

dependencies {
    implementation(libs.core.ktx)
    implementation(libs.appcompat)
}

효과: 버전을 한 곳에서만 관리하므로 모든 모듈이 일관성 유지

---

3. Build-logic (컨벤션 플러그인)

정의

• 여러 모듈에서 반복되는 Gradle 설정을 플러그인으로 추출한 전용 모듈
• 보통 루트에 build-logic/ 폴더를 만들고, includeBuild("build-logic") 로 포함시킵니다.

구조

build-logic/
 ├─ build.gradle.kts
 └─ src/main/kotlin/com/example/buildlogic/
       ├─ AndroidLibraryConventionPlugin.kt
       └─ AndroidApplicationConventionPlugin.kt

build-logic/build.gradle.kts

plugins {
    `kotlin-dsl`
}

repositories {
    gradlePluginPortal()
    google()
    mavenCentral()
}

gradlePlugin {
    plugins {
        register("androidLibraryConvention") {
            id = "example.android.library"
            implementationClass = "com.example.buildlogic.AndroidLibraryConventionPlugin"
        }
    }
}

dependencies {
    implementation("com.android.tools.build:gradle:8.6.0")
    implementation("org.jetbrains.kotlin:kotlin-gradle-plugin:2.0.0")
}

AndroidLibraryConventionPlugin.kt

package com.example.buildlogic

import com.android.build.gradle.LibraryExtension
import org.gradle.api.Plugin
import org.gradle.api.Project
import org.gradle.kotlin.dsl.configure

class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) = with(target) {
        pluginManager.apply("com.android.library")
        pluginManager.apply("org.jetbrains.kotlin.android")

        extensions.configure<LibraryExtension> {
            compileSdk = 35
            defaultConfig {
                minSdk = 24
            }
        }
    }
}

사용하는 쪽 (모듈)

plugins {
    id("example.android.library") // build-logic에서 정의한 컨벤션 플러그인
}

android {
    namespace = "com.example.feature.chat"
}

효과:

• 모듈별 build.gradle.kts 가 깔끔해짐
• 공통 설정은 build-logic 에서 한 번만 관리

---

4. Version Catalog vs Build-logic 차이

구분	Version Catalog	Build-logic
목적	라이브러리 버전/좌표 통합 관리	빌드 설정/플러그인 로직 공통화
위치	gradle/libs.versions.toml	build-logic/ 별도 포함 빌드
적용	libs.xxx 로 불러오기	id("xxx") 플러그인 적용
효과	버전 일관성	중복 코드 제거, 유지보수 쉬움

쉽게 말해:

• Version Catalog = “어떤 라이브러리를 쓸지 한 군데 모아둔 표”
• Build-logic = “모듈마다 반복되는 빌드 스크립트를 대신해주는 규칙”

---

5. 결론

최근 안드로이드/Gradle 개발의 표준 패턴은:

1. Version Catalog 로 라이브러리 버전 통합 관리
2. Build-logic 으로 공통 빌드 로직 플러그인화
3. 각 모듈에서는 고유 설정만 남겨 깔끔하게 관리

이렇게 세팅하면 멀티 모듈 프로젝트가 커져도 유지보수가 쉽고, 협업 시 충돌 가능성 감소

---