Android Gradle 플러그인 API 업데이트

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

이 페이지에서는 Android Gradle 플러그인(AGP) API 지원 중단 및 삭제를 추적하고 코드를 적절하게 업데이트하는 방법에 관한 정보를 제공합니다.

API 지원 중단 및 삭제 추적기

다음 표에는 AGP API가 지원 중단되고 삭제되는 시점이 AGP 버전 측면에서 요약되어 있습니다.

API 지원 중단된 시점의 AGP 버전 삭제된 시점의 AGP 버전
Component.setAsmFramesComputationMode 7.2
Component.transformClassesWith 7.2
RenderScript 7.2
Transform 7.2 8.0

AGP 8.0

다음은 AGP 8.0의 중요한 API 업데이트입니다.

Transform API가 삭제됨

AGP 8.0부터 Transform API가 삭제됩니다. 즉, 패키지 com.android.build.api.transform의 모든 클래스가 삭제됩니다.

빌드 성능을 개선하기 위해 Transform API가 삭제되는 것으로, Transform API를 사용하는 프로젝트는 AGP가 빌드에 덜 최적화된 흐름을 사용하도록 하여 빌드 시간에 큰 회귀를 일으킬 수 있기 때문입니다. 또한 Transform API를 사용한 다음 이를 다른 Gradle 기능과 결합하는 것 역시 어렵습니다. 대체 API의 목표는 성능이나 빌드 정확성 문제를 일으키지 않으면서도 AGP를 더욱 쉽게 확장하도록 만드는 것입니다.

대체 API

Transform API의 단일 대체 API는 없으며 사용 사례별로 타겟팅한 새 API가 있습니다. 대체 API는 모두 androidComponents {} 블록에 있습니다. 이 API는 모두 AGP 7.2에서 사용할 수 있습니다.

바이트 코드 변환 지원

바이트 코드를 변환하려면 Instrumentation API를 사용합니다. 라이브러리의 경우 로컬 프로젝트 클래스용 계측만 등록할 수 있습니다. 앱과 테스트의 경우 계측을 로컬 클래스용으로만 등록하거나 로컬 및 원격 종속 항목을 포함한 모든 클래스용으로 등록할 수 있습니다. 계측은 이 API를 사용하기 위해 클래스 경로 내 다른 클래스에 대한 액세스가 제한된 상태로 각 클래스에서 별도로 실행됩니다(자세한 내용은 createClassVisitor() 참고). 이러한 액세스 제한은 전체 빌드 및 증분 빌드의 성능을 개선하고 API 노출 영역을 단순하게 유지합니다. 각 라이브러리는 준비되는 즉시(모든 컴파일이 완료된 이후가 아님) 동시에 계측됩니다. 또한 단일 클래스가 변경되면 영향을 받는 클래스만 증분 빌드로 다시 계측해야 합니다. Instrumentation API 사용 방법의 예는 ASM으로 클래스 변환 AGP 레시피를 참고하세요.

생성된 클래스의 앱 추가 관련 지원

생성된 클래스를 앱에 추가하려면 Artifacts API를 MultipleArtifact.ALL_CLASSES_DIRS와 함께 사용합니다. 구체적으로는 다음을 사용합니다.

artifacts.use(TaskProvider)
  .wiredWith(...)
  .toAppend(Artifact.Multiple)

위의 아티팩트를 MultipleArtifact.ALL_CLASSES_DIRS와 함께 사용하여 프로젝트 클래스에 생성한 추가 디렉터리를 더합니다. Artifacts API는 맞춤 작업을 출력할 고유 위치를 자동으로 선택합니다. 이 API 사용 방법의 예는 addToAllClasses 레시피를 참고하세요.

전체 프로그램 분석을 기반으로 변환 지원

전체 프로그램 분석을 바탕으로 변환을 구현하기 위해 모든 클래스는 단일 작업으로 함께 변환될 수 있습니다. 이 접근 방식은 Instrumentation API를 사용할 때보다 빌드 성능 비용이 훨씬 많이 들기 때문에 주의해서 사용해야 합니다. 플러그인에서 이 API를 사용하는 경우 앱 개발자가 개발 빌드에 변환을 사용 중지할 수 있게 변환을 빌드 유형별로 선택하도록 구현하는 것이 좋습니다.

모든 클래스를 함께 변환하는 작업을 등록하기 위해 Android Gradle 플러그인 7.4에 Artifacts.forScope API를 도입했습니다. 현재 프로젝트의 모든 클래스를 변환하려면 Artifacts.forScope.PROJECT를 사용합니다. 현재 프로젝트, 가져온 프로젝트, 모든 외부 종속 항목의 모든 클래스를 변환하려면 Artifacts.forScope.ALL을 사용합니다. 다음 코드는 Artifacts.forScope.ALL을 사용하여 모든 클래스를 함께 변환하는 작업을 등록하는 방법을 보여줍니다.

variant.artifacts.forScope(ScopedArtifacts.Scope.ALL)
    .use(taskProvider)
    .toTransform(
        ScopedArtifact.CLASSES,
        ModifyClassesTask::allJars,
        ModifyClassesTask::allDirectories,
        ModifyClassesTask::output,
    )

이 API 사용 방법의 예는 modifyProjectClasses 레시피를 참고하고, Android 빌드 유형에 맞춤 확장 프로그램을 등록하는 방법의 예는 customizeAgpDsl 레시피를 참고하세요.

사용 사례가 AndroidComponents API에 해당하지 않는 경우 버그를 신고하세요.

Firebase Performance Monitoring 플러그인(1.4.1이 AGP 8.0과 호환됨) 및 Hilt Gradle 플러그인(2.40.1이 AGP 8.0과 호환됨) 등 흔히 사용되는 일부 플러그인은 이미 이 새 API를 사용하도록 이전되었습니다. 또한 AGP 업그레이드 어시스턴트를 사용하면 흔히 사용되는 플러그인을 프로젝트 개발자가 필요에 따라 업그레이드하도록 지원합니다.

서드 파티 플러그인을 통해 Transformation API를 사용하는 경우 작성자에게 플러그인을 업데이트해야 AGP 8.0용 새 API와 호환된다는 점을 알려주세요.

AGP 7.2

다음은 AGP 7.2의 중요한 API 업데이트입니다.

RenderScript가 지원 중단됨

AGP 7.2부터 RenderScript API가 지원 중단됩니다. 이 API는 계속 작동하지만, 경고가 호출되고 향후 AGP 버전에서 완전히 삭제됩니다. RenderScript에서 전환되는 방법에 관한 안내는 RenderScript에서 이전을 참고하세요.

Component.transformClassesWithComponent.setAsmFramesComputationMode가 지원 중단됨

AGP 7.2부터 클래스 바이트 코드 계측 API인 Component.transformClassesWithComponent.setAsmFramesComputationMode는 지원 중단됩니다. 이러한 API는 새 블록인 Component.instrumentation으로 이동했으며 이 블록에는 계측 프로세스 구성과 관련된 모든 API가 포함됩니다. 이러한 계측 기능을 계속 사용하려면 다음 코드 스니펫과 같이 새 블록에서 대응하는 API를 대신 사용하세요.

androidComponents {
      onVariants(selector().all(), {
          instrumentation.transformClassesWith(AsmClassVisitorFactoryImpl.class,
                                               InstrumentationScope.Project) { params ->
              params.x = "value"
          }
          instrumentation.setAsmFramesComputationMode(
              COMPUTE_FRAMES_FOR_INSTRUMENTED_METHODS
          )
      })
  }