Android Gradle 플러그인 업그레이드 어시스턴트 사용

Android Gradle 플러그인(AGP) 업그레이드 어시스턴트는 프로젝트에서 사용하는 AGP 버전을 업그레이드할 수 있는 Android 스튜디오의 도구입니다.

Google에서는 빌드 구성을 위한 새로운 기능, 다른 Gradle 플러그인에서 사용할 새로운 API, Android 스튜디오와의 프로젝트 빌드 통합 조정과 관련된 AGP 변경사항을 정기적으로 출시합니다. 프로젝트에서 사용하는 AGP 버전을 업그레이드하면 최신 기능을 활용할 수 있습니다.

AGP 업그레이드 어시스턴트는 어떤 용도로 사용되나요?

AGP 업그레이드 어시스턴트를 사용하면 AGP 버전을 업그레이드하는 데 필요한 변경사항을 알 수 있습니다. 다음은 업그레이드 어시스턴트의 가장 일반적인 사용 사례입니다.

  • 문법 변경사항: 업그레이드 어시스턴트는 이전 버전의 AGP 빌드 파일을 최신 버전의 AGP에 필요한 빌드 파일로 변환하려고 합니다. AGP를 개발할 때 Google에서는 시간이 지남에 따라 교체되거나 지원 중단되거나 지원되지 않는 인터페이스를 지원하도록 빌드 파일을 업데이트합니다.

  • AGP와 Gradle 간 호환성 요구사항: 업그레이드 어시스턴트는 AGP와 Gradle 간의 호환성 요구사항을 인식하므로 AGP 버전에 필요한 Gradle 버전을 사용하는지 확인할 수 있습니다.

  • AGP와 타사 Gradle 플러그인 간 호환성 요구사항: 업그레이드 어시스턴트는 AGP와 일부 타사 Gradle 플러그인 간의 호환성 요구사항을 인식하므로 AGP 버전에 필요한 타사 Gradle 플러그인 버전을 사용하는지 확인할 수 있습니다.

일반적으로 업그레이드 어시스턴트는 시행착오를 거쳐 빌드 파일을 변경해야 하거나 업그레이드 후 오류 메시지의 의미를 추측할 필요가 없게 만드는 것을 목표로 하며, 제안하는 변경사항이 필요한 이유도 설명합니다.

AGP 업그레이드 어시스턴트 사용 방법

아래 설명된 대로 프로젝트 구조상 업그레이드 어시스턴트를 사용할 수 있는지 확인한 후 Android 스튜디오에서 이를 실행합니다.

설정

업그레이드 어시스턴트를 실행하기 전에 프로젝트의 형식이 올바르며 백업되어 있는지 확인합니다.

Gradle 빌드 파일과 도메인별 언어를 사용하여 프로젝트 구조화

AGP 업그레이드 어시스턴트는 다음을 실행하는 경우에 최상의 성능을 발휘합니다.

  • Gradle 빌드 파일을 사용하여 빌드 구성: 업그레이드 어시스턴트는 Gradle 빌드 파일의 정적 분석을 사용합니다. 업그레이드 어시스턴트를 최대한 활용하려면 이러한 빌드 파일을 사용하여 빌드를 구성해야 합니다. 업그레이드 어시스턴트는 빌드 파일에서 사용되는 상수와 변수를 정의하는 데 buildSrc를 사용하는 프로젝트를 지원하지 않습니다. 일반적으로 buildSrc를 사용하여 프로젝트를 구조화하지 않는 것이 좋습니다. 비효율적일 수 있기 때문입니다. 아무리 사소한 변경이라도 buildSrc 상수와 변수를 변경하면 프로젝트가 완전히 다시 빌드됩니다.
  • 선언적 빌드 도메인별 언어 사용: Gradle 빌드 파일은 완전한 프로그래밍 언어(Groovy나 Kotlin)로 표현됩니다. 그러나 프로젝트 구성 표현식이 더 선언적일수록 업그레이드 어시스턴트가 업그레이드를 위해 조정이 필요한 위치를 모두 찾아낼 가능성이 커집니다.

이러한 제한사항을 준수하면서 프로젝트를 실행하더라도 업그레이드 어시스턴트가 여전히 완벽한 업그레이드를 하지 못할 수 있습니다. 버그를 해결하거나 신고하는 방법에 관한 안내는 문제 해결을 참고하세요.

프로젝트 백업

업그레이드 어시스턴트 사용을 시작하려면 버전 제어 시스템에서 확인된 커밋되지 않은 변경사항이 프로젝트에 남아 있지 않아야 합니다. 버전 제어를 사용하지 않는다면 이 시점에서 정상 작동하는 것으로 알려진 마지막 버전을 백업하는 것이 좋습니다.

업그레이드 어시스턴트가 실행되고 프로젝트가 성공적으로 빌드 및 테스트된 후 버전 제어 시스템에 새 버전의 프로젝트를 커밋할 수 있습니다.

업그레이드 어시스턴트 실행

업그레이드 어시스턴트를 실행하려면 다음 단계를 따르세요.

  1. 알림 메시지에서 또는 Tools > AGP Upgrade Assistant...로 이동하여 업그레이드 어시스턴트를 실행합니다. 도구 창이 열리고 프로젝트의 현재 AGP 버전에서 사용 중인 Android 스튜디오에서 지원되는 최신 버전으로의 기본 업그레이드 세부정보가 표시됩니다.
실행된 AGP 업그레이드 어시스턴트의 도구 창과 알림 메시지
그림 1. 실행된 AGP 업그레이드 어시스턴트의 도구 창과 알림 메시지
  1. 필수 및 권장 단계를 확인합니다. 왼쪽 패널의 체크박스가 있는 트리는 업그레이드의 개별 단계를 자세히 안내합니다. 개별 단계는 업데이트 필수 단계와 권장 단계, 다른 단계의 전제 조건인 단계 등으로 분류됩니다. 트리에서 개별 항목을 선택하면 기본 패널에 각 단계에 관한 세부정보가 표시됩니다.

  2. 필요하거나 원하는 단계를 선택하고 Run selected steps를 클릭하여 업그레이드를 실행합니다. 업그레이드 어시스턴트는 프로젝트 빌드 파일을 변경하고 새 프로젝트 빌드를 Android 스튜디오와 동기화하려고 합니다. 모듈이 많은 경우에는 시간이 걸릴 수 있습니다. 새 버전의 플러그인과 라이브러리를 다운로드해야 할 수 있기 때문입니다.

  3. 프로젝트가 Android 스튜디오와 성공적으로 동기화되면 프로젝트를 빌드하고 테스트 모음을 실행하여 업그레이드 작업으로 기능이 변경되지 않았는지 확인합니다.

  4. 프로젝트가 정상 상태인지 확인한 후 버전 제어 시스템에 프로젝트의 새 버전을 커밋합니다.

문제 해결

업그레이드 어시스턴트에서 업그레이드를 제공하지만 업그레이드에 실패하는 경우(일반적으로 빌드 파일 변경으로 인한 동기화 실패가 원인임) 문제 해결 단계에 따라 오류를 가려내고 수정할 수 있습니다.

  • 먼저 동기화 실패를 유발한 오류를 검사합니다. 오류의 원인이 분명한 때에는 프로젝트의 빌드 파일에서 해결할 수 있습니다.

  • 오류 메시지가 명확하지 않거나 문제의 원인이 분명하지 않으면 프로젝트를 원래 상태로 되돌려 업그레이드를 더 작은 단계로 분류해야 합니다. 버전 제어 또는 백업에서 원래 상태를 복원하고 원래 상태의 프로젝트가 다시 한번 Android 스튜디오와 동기화되도록 합니다. 그런 후 다음 두 종류의 업그레이드 분류를 사용하여 조사하면 됩니다.

    • 최신 버전이 아닌 AGP 버전으로 업그레이드. 많은 수의 버전을 업그레이드하다가 잘못되는 경우 계속 진행하면서 문제를 가려내는 가장 좋은 방법은 버전에서 버전으로 일련의 소규모 업그레이드를 실행하여 문제를 일으키는 첫 번째 업그레이드를 찾는 것입니다.
    • 업그레이드 내에서 개별 단계를 한 번에 하나씩 실행. 연속적인 AGP 버전 간에 문제를 일으키는 업그레이드를 찾았다면 업그레이드의 개별 단계를 사용 중지할 수 있습니다. 사용 중지한 후 각 단계를 한 번에 하나씩 실행하여 이러한 단계 중 문제가 되는 단계를 찾아보세요. 문제가 되는 단계를 찾을 수 없으면 사용 중인 다른 Gradle 플러그인의 출시 노트에서 Gradle이나 AGP와의 호환성 문제를 확인하는 것이 좋습니다. 지원 중단된 API나 내부 API 사용 문제가 새 버전에서 해결되는 경우도 있습니다.
  • 버그 신고. 모든 준비 단계와 동기화에 성공했는데도 최종 업그레이드 단계에서 여전히 실패하는 경우도 있습니다. 이 경우 버그를 신고해 주세요.

오류를 직접 수정하는 데 성공했더라도 개발팀에서 문제를 해결할 수 있도록 버그 추적기에 원래 실패를 신고해 주시기 바랍니다.