Android Gradle 플러그인(AGP) 업그레이드 어시스턴트는 프로젝트에서 사용하는 AGP 버전을 업그레이드할 수 있는 Android 스튜디오의 도구입니다.
Google에서는 빌드 구성을 위한 새로운 기능, 다른 Gradle 플러그인에서 사용할 새로운 API, Android 스튜디오와의 프로젝트 빌드 통합 조정과 관련된 AGP 변경사항을 정기적으로 출시합니다. 프로젝트에서 사용하는 AGP 버전을 업그레이드하면 최신 기능을 활용할 수 있습니다.
권장되는 업그레이드 어시스턴트의 프로젝트 구조에 관한 자세한 내용은 이 페이지의 설정을 참고하세요.
AGP 업그레이드 어시스턴트 사용 사례
AGP 업그레이드 어시스턴트를 사용하면 AGP 버전을 업그레이드하는 데 필요한 변경사항을 알 수 있습니다. 다음은 업그레이드 어시스턴트의 가장 일반적인 사용 사례입니다.
문법 변경사항: 업그레이드 어시스턴트는 이전 버전의 AGP 빌드 파일을 최신 버전의 AGP에 필요한 빌드 파일로 변환하려고 합니다. AGP의 개발이 진행됨에 따라 교체되거나 지원 중단되거나 지원되지 않는 인터페이스를 지원하도록 빌드 파일이 업데이트됩니다.
AGP와 Gradle 간 호환성 요구사항: 업그레이드 어시스턴트는 AGP와 Gradle 간의 호환성 요구사항을 인식하므로 개발자가 AGP 버전에 필요한 Gradle 버전을 사용 중인지 확인할 수 있습니다.
AGP와 서드 파티 Gradle 플러그인 간 호환성 요구사항: 업그레이드 어시스턴트는 AGP와 일부 서드 파티 Gradle 플러그인 간의 호환성 요구사항을 인식하므로 개발자가 AGP 버전에 필요한 서드 파티 Gradle 플러그인 버전을 사용 중인지 확인할 수 있습니다.
일반적으로, 업그레이드 어시스턴트를 사용하면 빌드 파일을 더 쉽게 업데이트하고 AGP 업그레이드 후에 관련 오류 메시지를 쉽게 이해할 수 있습니다. 업그레이드 어시스턴트는 제안된 변경사항이 필요한 이유도 설명합니다.
AGP 업그레이드 어시스턴트 사용 방법
업그레이드 어시스턴트 실행에 설명된 대로 프로젝트 구조상 업그레이드 어시스턴트를 사용할 수 있는지 확인한 후 Android 스튜디오에서 이를 실행합니다.
프로젝트 설정
업그레이드 어시스턴트를 실행하기 전에 프로젝트의 형식이 올바르며 백업되어 있는지 확인합니다. AGP 업그레이드 어시스턴트가 올바르게 설정되었는지 확인하려면 다음 섹션을 읽어보세요.
Gradle 빌드 파일과 도메인별 언어를 사용하여 프로젝트 구조화
AGP 업그레이드 어시스턴트를 최대한 활용하려면 다음 단계를 따르세요.
- Gradle 빌드 파일을 사용하여 빌드 구성: 업그레이드 어시스턴트는 Gradle 빌드 파일의 정적 분석을 사용합니다. 업그레이드 어시스턴트를 최대한 활용하려면 이러한 빌드 파일을 사용하여 빌드를 구성합니다.
- 선언적 빌드 도메인별 언어 사용: Gradle 빌드 파일은 Groovy 또는 Kotlin으로 표현됩니다. 그러나 프로젝트 구성 표현식이 더 선언적일수록 업그레이드 어시스턴트가 업그레이드를 위해 조정이 필요한 위치를 모두 찾아낼 가능성이 커집니다.
프로젝트가 이러한 제한사항을 준수하더라도 업그레이드 어시스턴트가 여전히 완벽한 업그레이드를 실행하지 못할 수 있습니다. 버그를 해결하거나 신고하는 방법에 관한 안내는 오류 문제 해결을 참고하세요.
프로젝트 백업
업그레이드 어시스턴트를 사용하려면 버전 제어 시스템에서 확인된 커밋되지 않은 변경사항이 프로젝트에 남아 있지 않아야 합니다. 버전 제어를 사용하지 않는다면 이 시점에서 정상 작동하는 것으로 알려진 마지막 버전을 백업합니다.
업그레이드 어시스턴트가 실행되고 프로젝트가 성공적으로 빌드 및 테스트된 후 버전 제어 시스템에 새 버전의 프로젝트를 커밋할 수 있습니다.
업그레이드 어시스턴트 실행
업그레이드 어시스턴트를 실행하려면 다음 단계를 따르세요.
업그레이드 어시스턴트를 실행하려면 Tools > AGP Upgrade Assistant로 이동하거나 그림 1과 같이 알림 메시지를 클릭합니다.
도구 창이 열리며 기본 업그레이드 세부정보가 표시됩니다. 프로젝트의 현재 AGP 버전과 이 Android 스튜디오에서 지원되는 최신 버전의 정보가 포함됩니다.
그림 1. 실행된 AGP 업그레이드 어시스턴트의 도구 창과 알림 메시지 필수 및 권장 단계를 확인합니다.
왼쪽 패널의 체크박스가 있는 트리에서는 업그레이드의 개별 단계를 자세히 보여줍니다. 개별 단계는 업데이트 필요 또는 권장 여부와 이것이 다른 단계의 기본 요건인지 여부를 기준으로 분류되어 있습니다. 트리에서 개별 항목을 선택하면 기본 패널에 각 단계에 관한 세부정보가 표시됩니다.
업그레이드를 실행하려면 필수 및 원하는 단계를 선택하고 Run selected steps를 클릭합니다.
업그레이드 어시스턴트가 프로젝트 빌드 파일을 변경하고 새 프로젝트 빌드를 Android 스튜디오와 동기화합니다. 모듈이 많은 경우에는 시간이 걸릴 수 있습니다. 새 버전의 플러그인과 라이브러리를 다운로드해야 할 수 있기 때문입니다.
업그레이드 후 보고서를 검토합니다. 이 보고서는 완료된 단계와 업그레이드 성공 여부를 설명합니다. 업그레이드 후 프로젝트를 빌드하거나 테스트하는 데 문제가 있는 경우 업그레이드 어시스턴트에서 실행한 변경사항을 되돌리는 작업도 포함됩니다.
프로젝트가 Android 스튜디오와 성공적으로 동기화되면 프로젝트를 빌드하고 테스트 모음을 실행하여 업그레이드 작업으로 기능이 변경되지 않았는지 확인합니다.
프로젝트가 정상 상태인지 확인한 후 버전 제어 시스템에 프로젝트의 새 버전을 커밋합니다.
오류 문제 해결
업그레이드 어시스턴트가 업그레이드를 제안했는데 업그레이드가 실패하면 일반적으로 빌드 파일이 변경되어 이에 따라 동기화가 실패했기 때문입니다. 오류를 가려내고 해결하려면 다음 단계를 따르세요.
먼저 동기화 실패를 유발한 오류를 검사합니다. 오류의 원인이 분명한 때에는 프로젝트의 빌드 파일에서 해결할 수 있습니다.
오류 메시지가 명확하지 않거나 문제의 원인이 분명하지 않으면 프로젝트를 원래 상태로 되돌려 업그레이드를 더 작은 단계로 세분화해야 합니다. 버전 제어 또는 백업에서 원래 상태를 복원하고 원래 상태의 프로젝트가 Android 스튜디오와 동기화되도록 합니다.
다음 두 종류의 업그레이드 세분화를 사용하여 오류를 조사합니다.
최신 버전이 아닌 AGP 버전으로 업그레이드. 많은 수의 버전을 업그레이드하다가 잘못되는 경우 문제를 가려내는 가장 좋은 방법은 버전에서 버전으로 일련의 소규모 업그레이드를 실행하여 문제를 일으키는 첫 번째 업그레이드를 찾는 것입니다.
업그레이드 내에서 개별 단계를 한 번에 하나씩 실행. 문제를 일으키는 업그레이드를 찾았다면 업그레이드의 개별 단계를 사용 중지할 수 있습니다. 사용 중지한 후 각 단계를 한 번에 하나씩 실행하여 이러한 단계 중 오류의 원인이 되는 단계를 찾아보세요. 문제가 되는 단계를 찾을 수 없으면 사용 중인 다른 Gradle 플러그인의 출시 노트에서 Gradle 또는 AGP와의 호환성 문제를 확인합니다. 때로는 새 버전에서 지원 중단된 API나 내부 API의 사용이 해결되었을 수 있습니다.
버그 신고. 모든 준비 단계와 동기화에 성공했는데도 최종 업그레이드 단계에서 여전히 실패하는 경우도 있습니다. 이 경우 버그를 신고해 주세요. 오류를 직접 해결하는 데 성공했더라도 개발팀에서 문제를 해결할 수 있도록 버그 추적기를 통해 원래 실패를 신고해 주시기 바랍니다.