Gradle Version Catalog 시작하기

Junsu Park

Published in

Team Aliens

10 min readOct 8, 2023

들어가며

안녕하세요, Team Aliens에서 DMS Android 개발에 참여하고 있는 박준수입니다.

Gradle은 Groovy 언어를 이용한 빌드 자동화 시스템입니다. Android Studio를 사용한 이래 안드로이드 개발에서도 적극 활용되고 있으며 모듈에 의존성, 플러그인 등을 선언하기 위해 필수적인 기술입니다.

Gradle Version Catalog는 Gradle의 의존성과 플러그인의 추가 및 유지보수를 효율적으로 관리하는 기술입니다.

안드로이드 개발을 할 때 Gradle을 사용하여 의존성, 플러그인을 선언하고 버전 관리를 해보신 적이 있으신가요? 이 글에서 DMS Android에서 어떻게 Gradle Version Catalog를 적용하였는지 말씀드리려 합니다.

Gradle Version Catalog ?

Gradle Version Catalog는 Gradle의 의존성, 플러그인 추가 및 유지보수를 효율적으로 관리하는 기술입니다.

다중 모듈을 사용할 때 의존성과 플러그인의 관리를 쉽게 할 수 있습니다.
하나의 버전 목록을 만들어 여러 모듈이 Type-safe하게 참조합니다.

buildSrc를 사용한 의존성, 플러그인 관리와 비교

buildSrc ?

Gradle을 사용하는 프로젝트에서 다중 모듈의 의존성, 플러그인 버전 관리를 필요로 할 때 공통 Gradle 의존성, 플러그인 경로 및 버전 정보를 명시해두는 모듈입니다.

Gradle Version Catalog vs buildSrc

Gradle Version Catalog를 사용하는 이유

Gradle Version Catalog 사용하는 주된 이유는 의존성과 플러그인을 하나의 공간에서 관리할 수 있고 유지보수가 용이하기 때문입니다.

다중 모듈 프로젝트를 개발할 때, 모듈별로 의존성 또는 플러그인의 path가 다르게 선언되는 것을 방지합니다.
의존성과 플러그인을 불러오기 위해 모듈마다 path 문자열을 하드코딩하는 것을 방지합니다.
IDE에서 의존성 또는 플러그인의 목록에 대한 코드 어시스턴스를 제공합니다.
libs 변수에 접근하여 Type-safe하게 의존성 또는 플러그인을 참조할 수 있습니다.

Gradle Version Catalog의 섹션

Gradle Version Catalog의 섹션은 versions, libraries, plugins, bundles의 주요한 섹션으로 구성되어 있습니다.

[libraries]

[libraries] 섹션에 의존성 정보를 담는 변수를 정의합니다.

[plugins]

plugins 섹션에 플러그인 정보를 담는 변수를 정의합니다.

`[versions]`

versions 섹션에 libraries, plugins섹션에 선언되어 있는 의존성, 플러그인의 버전 정보를 담는 변수를 정의합니다.

[bundles]

libraries, plugins 섹션에 선언되어 있는 의존성, 플러그인 목록을 담는 변수를 정의합니다.

Gradle Version Catalog path의 구분

Gradle Version Catalog에서 의존성, 플러그인 등의 정보를 담은 변수를 선언할 때 path 키워드를 통해 Gradle 검색 경로를 구분할 수 있습니다.

group & name

androidx-core = { group = "androidx.core", name = "core-ktx", version.ref = "core" }

group 키워드로 여러 모듈을 가지고 있는 그룹의 path 지정합니다.

name 키워드를 사용하여 특정 아티팩트 참조할 수 있습니다.

module

androidx-core = { modulie = "androidx.core:core-ktx", version.ref = "core" }

module 키워드로 특정 모듈의 path를 지정합니다.

id

android-application = { id = "com.android.application", version.ref = "agp" }

id 키워드로 플러그인의 path를 지정합니다.

Gradle Version Catalog의 사용

이제 Gradle Version Catalog의 사용 방법을 소개하겠습니다.

Version Catalog 파일 추가

Gradle Version Catalog를 적용할 루트 프로젝트의 gradle/ 하위에 libs.versions.toml 파일을 추가합니다.

Gradle에서 libs.versions.toml이라는 이름을 기본적으로 검색하여 의존성, 플러그인의 접근자를 생성합니다.

Version Catalog 파일 내에 의존성 선언

[versions]
core = "<version>"

[libraries]
androidx-core = { group = "androidx.core", name = "core-ktx", version.ref = "core" }

Version Catalog 내 변수는 Kebab case(예: app-junsu-kebabExample)를 사용하여 명명합니다.

Version Catalog 변수를 Kebab case로 선언하면 더 나은 코드 어시스턴스를 제공받을 수 있습니다.

기존 코드 이전

루트 프로젝트의 build.gradle.kts

기존 코드

plugins {
  id("com.android.application") version "<version>" apply false
  // ...
}

플러그인 path 선언

[versions]
agp = "<version>"

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

기존 코드 변경

plugins {
  alias(libs.plugins.android.application) apply false
  // ...
}

모듈의 build.gradle.kts

plugins블록

기존 코드

plugins {
   id("com.android.application")
}

플러그인 path 선언

[versions]
agp = "<version>"

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

기존 코드 변경

plugins {
   alias(libs.plugins.android.application)
}

dependencies 블록

기존 코드

dependencies {
  implementation("androidx.core:core-ktx:<version>")
  implementation("androidx.appcompat:appcompat:<version>")
  implementation("com.google.android.material:material:<version>")
}

의존성 path 선언

[versions]
core = "<version>"
appcompat = "<version>"
material = "<version>"

[libraries]
androidx-core = { group = "androidx.core", name = "core-ktx", version.ref = "core" }
androidx-appcompat = { module = "androidx.appcompat:appcompat", version.ref = "appcompat" }
material = { module = "com.google.android.material:material", version.ref = "material" }

기존 코드 변경

dependencies {
  implementation(libs.androidx.core)
  implementation(libs.androidx.appcompat)
  implementation(libs.material)
}

이슈

Use the explicit one if necessary

'val Project.libs: LibrariesForLibs' can't be called in this context by implicit receiver. Use the explicit one if necessary

Use the explicit one if neccessary 오류 메시지는 인텔리제이상의 오류(KTIJ-19369)입니다.

오류가 발생하는 파일에 @Suppress 애너테이션을 명시하여 해결할 수 있습니다.

// TODO: Remove once KTIJ-19369 is fixed
@file:Suppress("DSL_SCOPE_VIOLATION")

plugins { /* ... */ }

마치며

이상 Gradle Version Catalog 소개 글을 마치겠습니다. 이번 글에서 다룬 내용은 다음과 같습니다.

Version Catalog의 개념
Version Catalog와 buildSrc를 사용한 버전 관리
Version Catalog의 특징
프로젝트에 Version Catalog를 적용하는 방법
Version Catalog의 메이저 에러

감사합니다.

자료

https://developer.android.com/build/migrate-to-catalogs