Nutri Capture - 버전 카탈로그로 완전 전환

#1 개요

build.gradle에 정의한 라이브러리(의존성)들의 주소 및 버전을, 버전 카탈로그(libs.versions.toml)가 완전히 관리하게 했다.

 

#2 개선한 포인트

#2-1 버전 카탈로그로 완전 전환

버전 카탈로그로 빌드 이전  |  Android Studio  |  Android Developers

지금까지의 Nutri Capture는 일부 라이브러리만 버전 카탈로그가 관리했었다. 이제는 kapt를 제외(#3-2 참조)한 모든 플러그인 및 라이브러리를 버전 카탈로그가 관리하게 변경한다.

 

#2-2 라이브러리 최신화

# in libs.versions.toml

[versions] 
... # 변경할 부분

[libraries]
...

[plugins]
...

버전 카탈로그가 좋은 이유 중 하나는, "versions" 테이블에 있는 키-값 쌍의 값 부분만 바꿔 라이브러리 최신화가 가능하다는 점이다. 하지만, 라이브러리끼리의 버전 호환성은 여전히 프로그래머가 잘 파악해야 한다. 

 

#3 버전 카탈로그로 완전 전환

#3-1 코드 스니펫

// in ":app" 모듈의 build.gradle.kts

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
    id("org.jetbrains.kotlin.kapt") // 특별대우 (#3-2 참조)
    alias(libs.plugins.hilt)
}

android {
    ...
}

dependencies {

    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.lifecycle.runtime.ktx)
    implementation(libs.androidx.activity.compose)
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.ui)
    implementation(libs.androidx.ui.graphics)
    implementation(libs.androidx.ui.tooling.preview)
    implementation(libs.androidx.material3)
    ...
}

플러그인은 alias 키워드를 써서 '버전 카탈로그의 플러그인 항목 (libs.plugins)'의 항목을 참조하고, 라이브러리들은 implementation의 인수에 '버전 카탈로그의 라이브러리 항목 (libs)'의 항목을 전달한다.

 

#3-2 kapt를 특별대우 하는 이유

#3-1에 있는 코드를 보면, kapt는 버전 카탈로그화 시키지 않았다. Gradle Sync 문제 때문이다. 아래와 같은 코드를 썼는데 에러가 났다.

 

...

[plugins]
kotlin-kapt = { id = "org.jetbrains.kotlin.kapt", version.ref = "kotlin" }

kapt의 버전은 'org.jetbrains.kotlin.android 플러그인' (← 코틀린 코드를 컴파일할 수 있게 해주는 플러그인)에 의해 이미 지정되었으므로 버전을 명시하면 충돌이 난다는 이유다. 그래서 version.ref라는 key를 아예 제거하고 Gradle Sync를 해보면, 이건 이거대로 version.ref가 없다는 에러가 난다. 아마 무결성 차원에서 막아둔 듯하다.

 

하지만 덕분에 (org.jetbrains.kotlin.android 플러그인은 코틀린 버전에 종속되므로) "kapt는 코틀린 버전과 자동으로 연동"된다는 걸 알았다. 그래서 버전 카탈로그의 관리 목록에서 뺐다(예외로 뒀다).

 

#4 라이브러리 최신화

#4-1 버전 변경 사항

# in libs.versions.toml
# 변경 사항 없는 줄은 생략(...)함

[versions]
agp = "8.9.3" # <- "8.5.1" (androidGradlePlugin)
hiltNavigationCompose = "1.3.0" # <- "1.2.0" (androidxHiltNavigationCompose)
hiltVersion = "2.56.2" # <- "2.46" (hilt)
kotlin = "2.1.20" # <- "1.9.21" (동일)
coreKtx = "1.17.0" # <- "1.13.1" (androidxCore)
junitVersion = "1.3.0" # <- "1.2.1" (Now in Androidd에 해당 프로퍼티값 쓰는 라이브러리 없음)
espressoCore = "3.7.0" # <- "3.6.1" (androidxEspresso)
lifecycleRuntimeKtx = "2.9.4" # <- "2.8.6" (androidxLifecycle)
activityCompose = "1.11.0" # <- "1.9.2" (androidxActivity)
composeBom = "2025.09.01" # <- "2024.04.01" (동일)
navigationRuntimeKtx = "2.9.5" # <- "2.8.1" (androidxNavigation)
roomRuntime = "2.8.1" # <- "2.6.1" (room)
ksp = "2.1.20-1.0.31" # <- "1.9.0-1.0.13" (동일)
...

[libraries]
...

[plugins]
...

가능한 최신 버전으로 모든 플러그인과 라이브러리를 업그레이드했다. 주석(#)에서 화살표 뒤는 변경 전의 버전이고, 괄호 속의 이름은 Now in Android에서 사용하는 프로퍼티명이다 (참고: 전체 libs.versions.toml 보기)

 

#4-2 "kotlin" 버전 변경의 여파 대응

":app" 모듈의 build.gradle.kts

plugins {
    ...
    // Compose Compiler 추가
    alias(libs.plugins.kotlin.compose)
}

android {
    ...

    // 이제는 필요없는 구문 삭제
//  composeOptions {
//      kotlinCompilerExtensionVersion = "1.5.6"
//  }
    ...
}

dependencies {

    ...
}

Kotlin 1.x 시절에는 Compose Compiler 버전을 별도로 (composeOptions.kotlinCompilerExtensionVersion에서) 관리해야 했지만, 이제 Kotlin 2.0 이후 Compose Compiler가 별도 Gradle Plugin으로 분리되었다. 따라서 composeOptions.kotlinCompilerExtensionVersion는 이제 필요 없다.

 

버전 카탈로그 (libs.versions.toml)

[versions]
...

[libraries]
...

[plugins]
...
kotlin-compose = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" } # Compose Compiler

build.gradle에서 호출한 libs.plugins.kotlin.compose를 존재시킨(?)다.

 

#4-3 "agp" 버전 변경의 여파 대응

# in gradle-wrapper.properties

...
distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip
...

Android Gradle Plugin의 버전을 8.9.3으로 올렸는데, 8.9.x 버전 이상의 Android Gradle Plugin은 최소 8.11.1 버전 이상의 Gradle에 기반해야 한다. 따라서 Gradle 버전을 위와 기존 8.7에서 8.11.1로 변경했다.

 

#4-4 "composeBom" 버전 변경의 여파 대응

# in libs.versions.toml

[versions]
...
materialIconsExtended = "1.7.8"

[libraries]
...
androidx-material-icons-extended = { module = "androidx.compose.material:material-icons-extended", version.ref = "materialIconsExtended" }

[plugins]
...

기존 composeBom의 버전은 "2024.04.01"이었다. composeBom 버전을 "2025.09.01"으로 올리자, 아래 코드에서 에러가 났다.

 

// in NutrientChatBar.kt

import androidx.compose.material.icons.Icons // e: Unresolved reference 'icons'.

...

'icons' 패키지를 찾을 수 없다는 에러 메시지였다. composeBom에 어떤 변화가 생겼기 때문이리라. 하지만 BOM to library version mapping에서 "2024.04.01" 버전의 mapping 정보가 나와 있지 않았다. 너무 오래됐기 때문일 것이다. 그래도 검색을 통해 이런 경우에는 "androidx.compose.material:material-icons-extended" 라이브러리를 추가하면 된다는 정보를 찾았고, 따라 해봤더니 해결할 수 있었다. 

 

다행히 BOM to library version mapping에는 "2025.09.01" 버전 composeBom의 mapping 정보는 나와 있었는데, 여기서 의문을 해결할 수 있었다. "2025.09.01" 버전부터는 최초로, 1.4.0 버전의 "androidx.compose.material3:material3"를 쓴다. 그리고 이 라이브러리의 1.4.0 버전을 설명하는 공식 문서에는 다음과 같은 설명이 나온다.

 

1. (androidx.compose.material.icons가 제공하는) Material Icons는 새로운 디자인인 Material Symbols로 대체되었기 때문에 더 이상 지원 안 함
2. androidx.compose.material.icons 라이브러리는 모든 아이콘 세트를 전부 포함하고 있어서, 실제로는 쓰지도 않는 아이콘까지 빌드하느라 빌드 시간에 악영향을 주기에 더 이상 지원 안 함

그러니 정말 필요한 사람만 추가 라이브러리(androidx.compose.material:material-icons-extended)를 다운로드해서 쓰라는 말이다.

 

#4-5 여러 라이브러리 버전 변경의 여파 대응

// in ":app" 모듈의 build.gradle.kts

plugins {
    ...
}

android {
    ...
    compileSdk = 36

    ...
}

dependencies {

    ...
}

거의 모든 라이브러리를 최신 버전으로 올렸더니, Gradle Sync 시 35 또는 36의 complieSdk를 요구했다 (기존은 34). 그래서 교집합인 36로 compileSdk를 올렸다.

 

Gradle Sync 시 떴던 에러 메시지 전문

1. Dependency 'androidx.hilt:hilt-navigation-compose:1.3.0' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

2. Dependency 'androidx.hilt:hilt-lifecycle-viewmodel-compose:1.3.0' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

3. Dependency 'androidx.navigation:navigation-compose-android:2.9.0' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

4. Dependency 'androidx.compose.material3:material3-android:1.4.0' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

5. Dependency 'androidx.compose.ui:ui-tooling-data-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

6. Dependency 'androidx.compose.material:material-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

7. Dependency 'androidx.compose.foundation:foundation-layout-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

8. Dependency 'androidx.compose.material:material-ripple-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

9. Dependency 'androidx.compose.foundation:foundation-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

10. Dependency 'androidx.compose.animation:animation-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

11. Dependency 'androidx.compose.animation:animation-core-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

12. Dependency 'androidx.compose.ui:ui-text-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

13. Dependency 'androidx.compose.ui:ui-tooling-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

14. Dependency 'androidx.compose.ui:ui-graphics-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

15. Dependency 'androidx.core:core:1.17.0' requires libraries and applications that depend on it to compile against version 36 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 36, for example 36.

16. Dependency 'androidx.activity:activity-ktx:1.11.0' requires libraries and applications that depend on it to compile against version 36 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 36, for example 36.

17. Dependency 'androidx.compose.runtime:runtime-saveable-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

18. Dependency 'androidx.lifecycle:lifecycle-runtime-compose-android:2.9.4' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

19. Dependency 'androidx.lifecycle:lifecycle-viewmodel-compose-android:2.9.4' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

20. Dependency 'androidx.compose.ui:ui-android:1.9.2' requires libraries and applications that depend on it to compile against version 35 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 35, for example 36.

21. Dependency 'androidx.activity:activity:1.11.0' requires libraries and applications that depend on it to compile against version 36 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 36, for example 36.

22. Dependency 'androidx.activity:activity-compose:1.11.0' requires libraries and applications that depend on it to compile against version 36 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 36, for example 36.

23. Dependency 'androidx.core:core-ktx:1.17.0' requires libraries and applications that depend on it to compile against version 36 or later of the Android APIs.

:app is currently compiled against android-34.

Recommended action: Update this project to use a newer compileSdk of at least 36, for example 36.

 

#5 소스 코드

#5-1 버전 카탈로그로 완전 전환

GitHub - Kanmanemone/nutri-capture-new

#3이 적용된 커밋

 

#5-2 라이브러리 최신화

GitHub - Kanmanemone/nutri-capture-new

(#3과) #4가 적용된 커밋

 

#5-3 본 프로젝트의 가장 최신 Commit

GitHub - Kanmanemone/nutri-capture-new