KMP AGP 9 마이그레이션, 안드 앱 모듈부터 손본 빌드 복구 일지

 

지난주에 KMP 프로젝트 AGP 버전을 9으로 올리고 동기화를 눌렀는데요. 화면이 온통 빨간 에러로 덮이는 걸 보면서 '아, 오늘 야근이구나' 싶었습니다.

 

처음엔 버전 숫자만 바꾸는 단순 작업인 줄 알았어요. 근데 막상 열어보니까 이건 버전 업이 아니라 프로젝트 구조를 갈아엎는 일이더군요. 공유 코드랑 실행되는 앱을 아예 떼어놓으라는 거였습니다. 그날 깨진 빌드를 다시 살린 순서를 그대로 정리해뒀어요.

 

전제는 이렇습니다. AGP 8.x 기반에 코틀린(Kotlin) 2.x를 쓰던, 모듈 하나에 안드로이드 앱이랑 공유 코드가 같이 들어있는 흔한 단일 모듈 KMP 프로젝트였어요.

 

AGP 9에서 KMP 빌드가 통째로 깨지는 이유

빨간 줄의 출처는 크게 세 갈래였습니다.

 

첫 번째는 플러그인 충돌이에요. AGP 9이 코틀린 컴파일을 자체적으로 내장하게 바뀌었거든요. 그래서 기존에 쓰던 org.jetbrains.kotlin.android 플러그인을 그대로 두면 둘이 부딪힙니다. 이건 빼야 동기화가 넘어가요.

 

두 번째는 기본 요건 미달입니다. AGP 9은 자바 17 이상, 그래들(Gradle) 9.1 이상을 요구하는 것으로 알려져 있어요. 둘 중 하나라도 낮으면 동기화 단계에서 바로 멈춰버립니다.

 

세 번째가 진짜 핵심인데요. 한 모듈 안에서 com.android.application 같은 안드로이드 플러그인이랑 KMP 플러그인을 같이 못 쓰게 막혔습니다. 예전 KMP 템플릿의 단일 모듈 구조가 더는 안 통한다는 얘기예요. 제가 멘붕이 왔던 게 바로 이 지점이었습니다.

 

 

안드로이드 앱 모듈을 먼저 분리해야 하는 이유

AGP에는 업그레이드 어시스턴트(Upgrade Assistant)가 있어서 DSL 변경 같은 건 어느 정도 자동으로 고쳐줍니다. 근데 모듈을 쪼개는 구조 변경은 손도 못 대더라고요. 이 수동 작업을 제일 먼저 해치워야 나머지가 풀립니다.

 

순서를 거꾸로 잡으면 고생만 합니다. 앱 모듈을 먼저 떼어내면 의존성 방향이 androidApp → 공유 모듈, 이렇게 한 방향으로 깔끔하게 정리돼요. 이걸 안 하고 다른 설정부터 건드리면 2차, 3차로 빌드가 또 깨질 수 있습니다.

 

프로젝트 루트에 androidApp 디렉터리를 새로 만들고, 기존 공유 모듈에 섞여 있던 것들을 옮겼어요. 옮길 대상은 이렇습니다.

 

1. AndroidManifest.xml 전체
2. Application 클래스와 진입점이 되는 Activity
3. 안드로이드 전용 리소스(drawable, layout, values 등)

 

이 셋만 깨끗하게 들어내도 공유 모듈이 한결 가벼워집니다.

 

 

namespace, variant 등 바뀐 공유 모듈 설정 정리

모듈을 떼고 나면 공유 모듈 쪽 build.gradle.kts를 손볼 차례입니다. 여기서 챙길 게 몇 개 있어요.

 

플러그인부터 교체합니다. 공유 라이브러리 모듈은 이제 com.android.library 대신 com.android.kotlin.multiplatform.library를 쓰는 구조로 바뀌었어요. 이름이 길어서 처음엔 오타도 났네요.

 

근데 이 새 플러그인에 함정이 있습니다. 빌드 변형을 하나만 지원한다는 점이에요. 쉽게 말하면 debug/release로 나누거나 flavor로 분기를 친 라이브러리 의존성을 해석하다가 실패할 수 있다는 얘기입니다. KMP 안드로이드 타깃에서 buildType 설정 자체가 빠졌고, 대체 기능도 따로 없는 것으로 보여요. 빌드 타입에 기대던 분기 로직이 있다면 이 부분은 다시 짜야 합니다.

 

namespace도 옮겨줘야 합니다. 매니페스트의 package 속성을 지우고, build.gradle.kts에 namespace를 직접 명시하는 식이에요. 이건 AGP 8에서 필수화된 거라 익숙한 분들도 많을 겁니다.

 

코틀린·KSP·Hilt 도구 버전 정렬 기준

구조를 다 바꿔놨는데 버전이 안 맞으면 또 빨간 줄이 뜹니다. 특히 KSP 쪽에서 호환성 에러가 잘 나더라고요. 리서치하면서 정리한 기준 버전은 이렇습니다.

 

1. 코틀린은 2.3.x 권장
2. KSP는 2.3.6 이상
3. Hilt는 2.59.2 이상 (AGP 9 지원이 2.59부터 들어왔거든요. 다만 그 초기 버전엔 런타임 아티팩트 버그(dagger #5099)가 있어서, 2.59.2 이상으로 올려두는 게 이 함정을 피하는 길입니다)

 

여기서 한 가지 짚고 싶은 게 레거시 옵트아웃입니다. AGP 9에는 옛 동작을 잠시 유지하는 옵션이 있는데요. 이게 AGP 10.0에서 제거될 예정이라고 합니다. 당장 급하면 켜둘 수야 있지만, 결국 빚으로 남는 임시방편이라고 봅니다. 개인적으로는 처음 작업할 때 제대로 끊고 가는 쪽을 택했어요.

 

 

AGP 9 업그레이드 마이그레이션 순서 체크리스트

제가 빌드를 살린 순서를 그대로 옮기면 이렇습니다. 이 순서대로 가면 실패 지점이 단계별로 격리돼서 디버깅이 훨씬 수월해져요.

 

1. 그래들 9.1 이상, JDK 17 이상으로 먼저 올리기
2. androidApp 모듈 신설하고 매니페스트·Application·Activity·리소스 분리
3. 공유 모듈 플러그인을 com.android.kotlin.multiplatform.library로 교체
4. 코틀린, KSP, Hilt 버전 정렬
5. buildType 등 빠진 DSL 정리하고 단일 변형 구조에 맞추기
6. 마지막에 전체 클린 빌드

 

저는 2번에서 한참 헤맸는데요. 리소스 일부를 안 옮기는 바람에 클린 빌드에서 한 번 더 깨졌어요. 앱 전용 리소스가 공유 모듈에 남아 있나 꼭 한 번 더 확인하시는 게 좋습니다.

 

작업을 끝내고 보니 결국 두 갈래 길이었어요. 한쪽은 빨간 줄 메시지를 하나씩 쫓아가며 땜질하는 길이고, 다른 한쪽은 모듈 경계를 먼저 다시 긋고 시작하는 길입니다. AGP 9 마이그레이션은 버전 숫자를 바꾸는 게 아니라 구조를 갈아엎는 일이었으니까, 저는 망설이지 말고 후자로 가시라고 권하고 싶어요. 앱 모듈부터 떼어내고 의존성 방향을 한쪽으로 세워두면, 나머지 빨간 줄은 그 다음에 순서대로 사라집니다.