前言
Transform API
是 AGP1.5
就引入的特性,主要用于在 Android
构建过程中,在 Class
转 Dex
的过程中修改 Class
字节码。利用 Transform API
,我们可以拿到所有参与构建的 Class
文件,然后可以借助 ASM
等字节码编辑工具进行修改,插入自定义逻辑。
国内很多团队都或多或少的用 AGP
的 Transform API
来搞点儿黑科技,比如无痕埋点,耗时统计,方法替换等。但是在 AGP7.0
中 Transform
已经被标记为废弃了,并且将在 AGP8.0
中移除。
而 Transrom
被废弃之后,它的代替品则是 Transform Action
,它是由 Gradle
提供的产物变换 API
。
Transform API
是由 AGP
提供的,而 Transform Action
则是由Gradle提供。不光是 AGP
需要Transform
, Java
也需要,所以由 Gradle
来提供统一的 Transform API
也合情合理。
当然如果你只是想利用 ASM
对字节码插桩, AGP
提供了对基于 TransformAction
的 ASM
插桩的封装,只需要使用 AsmClassVisitorFactory
即可.
而本文主要包括以下内容:
TransformAction
是什么?- 如何自定义
TransformAction
TransformAction
在AGP
中的应用
TransformAction
是什么?
简单来说, TransformAction
就是 Gradle
提供的产物转换 API
,可以注册两个属性间的转换Action
,将依赖从一个状态切换到另一个状态
我们在项目中的依赖,可能会有多个变体,例如,一个依赖可能有以下两种变体: classes
( org.gradle.usage=java-api
, org.gradle.libraryelements=classes
)或 JAR
( org.gradle.usage=java-api, org.gradle.libraryelements=jar
)
它们的主要区别就在于,一个的产物是 jar
,一个则是 classes
(类目录)
当 Gradle
解析配置时,解析的配置上的属性将确定请求的属性,并选中匹配属性的变体。例如,当配置请求 org.gradle.usage=java-api, org.gradle.libraryelements=classes
时,就会选择 classes
目录作为输入。
但是如果依赖项没有所请求属性的变体,那么解析配置就会失败。有时我们可以将依赖项的产物转换为请求的变体。
例如,解压缩 Jar
的 TranformAction
会将 java-api
, jars
转换为 java-api,classes
变体。
这种转换可以对依赖的产物进行转换,所以称为“产物转换” 。 Gradle
允许注册产物转换,并且当依赖项没有所请求的变体时, Gradle
将尝试查找一系列产物转换以创建变体。
TransformAction
选择和执行逻辑
如上所述,当 Gradle
解析配置并且配置中的依赖关系不具有带有所请求属性的变体时, Gradle
会尝试查找一系列 TransformAction
以创建变体。
每个注册的转换都是从一组属性转换为一组属性。例如,解压缩转换可以从 org.gradle.usage=java-api, org.gradle.libraryelements=jars
转换至 org.gradle.usage=java-api, org.gradle.libraryelements=classes
。
为了找到一条这样的链, Gradle
从请求的属性开始,然后将所有修改某些请求的属性的 TransformAction
视为通向那里的可能路径。
例如,考虑一个 minified
属性,它有两个值: true
和 false
。 minified
属性表示依赖项的变体,表示删除了不必要的类文件。
如果我们的依赖只有 minified=false
的变体,并且我们的配置中请求了 minified=true
的属性,如果我们注册了 minify
的转换,那么它就会被选中
在找到的所有变换链中, Gradle
尝试选择最佳的变换链:
- 如果只有一个转换链,则选择它。
- 如果有两个变换链,并且一个是另一个的后缀,则将其选中。
- 如果存在最短的变换链,则将其选中。
- 在所有其他情况下,选择将失败并报告错误。
同时还有两个特殊情况:
- 当已经存在与请求属性匹配的依赖项变体时,
Gradle
不会尝试选择产物转换。 artifactType
属性是特殊的,因为它仅存在于解析的产物上,而不存在于依赖项上。因此任何只变换artifactType
的TransformAction
,只有在使用ArtifactView时才会考虑使用
自定义 TransformAction
下面我们就以自定义一个 MinifyTransform
为例,来看看如何自定义 TransformAction
,主要用于过滤产物中不必要的文件
定义 TransformAction
abstract class Minify : TransformAction<Minify.Parameters> { // (1) interface Parameters : TransformParameters { // (2) @get:Input var keepClassesByArtifact: Map<String, Set<String>> } @get:PathSensitive(PathSensitivity.NAME_ONLY) @get:InputArtifact abstract val inputArtifact: Provider<FileSystemLocation> override fun transform(outputs: TransformOutputs) { val fileName = inputArtifact.get().asFile.name for (entry in parameters.keepClassesByArtifact) { // (3) if (fileName.startsWith(entry.key)) { val nameWithoutExtension = fileName.substring(0, fileName.length - 4) minify(inputArtifact.get().asFile, entry.value, outputs.file("${nameWithoutExtension}-min.jar")) return } } println("Nothing to minify - using ${fileName} unchanged") outputs.file(inputArtifact) // (4) } private fun minify(artifact: File, keepClasses: Set<String>, jarFile: File) { println("Minifying ${artifact.name}") // Implementation ... } } 复制代码
代码很简单,主要分为以下几步:
TransformAction transform
其实一个 TransformAction
主要就是输入,输出,变换逻辑三个部分
注册 TransformAction
接下来就是注册了,您需要注册 TransformAction
,并在必要时提供参数,以便在解析依赖项时可以选择它们
val artifactType = Attribute.of("artifactType", String::class.java) val minified = Attribute.of("minified", Boolean::class.javaObjectType) val keepPatterns = mapOf( "guava" to setOf( "com.google.common.base.Optional", "com.google.common.base.AbstractIterator" ) ) dependencies { attributesSchema { attribute(minified) // <1> } artifactTypes.getByName("jar") { attributes.attribute(minified, false) // <2> } } configurations.all { afterEvaluate { if (isCanBeResolved) { attributes.attribute(minified, true) // <3> } } } dependencies { // (4) implementation("com.google.guava:guava:27.1-jre") implementation(project(":producer")) } dependencies { registerTransform(Minify::class) { // <5> from.attribute(minified, false).attribute(artifactType, "jar") to.attribute(minified, true).attribute(artifactType, "jar") parameters { keepClassesByArtifact = keepPatterns // Make sure the transform executes each time timestamp = System.nanoTime() } } } tasks.register<Copy>("resolveRuntimeClasspath") { from(configurations.runtimeClasspath) into(layout.buildDirectory.dir("runtimeClasspath")) } 复制代码
注册 TransformAction
也分为以下几步:
- 添加
minified
属性 - 将所有JAR文件的
minified
属性设置为false
- 在所有可解析的配置上设置请求的属性为
minified=true
- 添加将要转换的依赖项
- 注册
Transformaction
,设置from
与to
的属性,并且传递自定义参数
运行 TransformAction
在定义与注册了 TransformAction
之后,下一步就是运行了
上面我们自定义了 resolveRuntimeClasspath
的 Task
, Minify
转换会在我们请求 minified=true
的变体时调用
当我们运行 gradle resolveRuntimeClasspath
时就可以得到如下输出
> Task :resolveRuntimeClasspath Nothing to minify - using jsr305-3.0.2.jar unchanged Minifying guava-27.1-jre.jar Nothing to minify - using failureaccess-1.0.1.jar unchanged Nothing to minify - using listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar unchanged Nothing to minify - using j2objc-annotations-1.1.jar unchanged Nothing to minify - using checker-qual-2.5.2.jar unchanged Nothing to minify - using error_prone_annotations-2.2.0.jar unchanged Nothing to minify - using animal-sniffer-annotations-1.17.jar unchanged 复制代码
可以看出,当我们执行 task
的时候, gradle
自动调用了 TransformAction
,对 guava.jar
进行了变换,并将结果存储在 layout.buildDirectory.dir("runtimeClasspath")
中
变换 ArtifactType
的 TransformAction
上文提到, artifactType
属性是特殊的,因为它仅存在于解析的产物上,而不存在于依赖项上。因此任何只变换 artifactType
的 TransformAction
,只有在使用ArtifactView时才会考虑使用
其实在 AGP
中,相当一部分自定义 TransformAction
都是属于只变换 ArtifactType
的,下面我们来看下如何自定义一个这样的 TransformAction
class TransformActionPlugin : Plugin<Project> { override fun apply(project: Project) { project.run { val artifactType = Attribute.of("artifactType", String::class.java) dependencies.registerTransform(MyTransform::class.java) { // 1 it.from.attribute(artifactType, "jar") it.to.attribute(artifactType, "my-custom-type") } val myTaskProvider = tasks.register("myTask", MyTask::class.java) { it.inputCount.set(10) it.outputFile.set(File("build/myTask/output/file.jar")) } val includedConfiguration = configurations.create("includedConfiguration") // 2 dependencies.add(includedConfiguration.name, "org.jetbrains.kotlin:kotlin-stdlib-jdk8:1.7.10") val combinedInputs = project.files(includedConfiguration, myTaskProvider.map { it.outputFile }) val myConfiguration = configurations.create("myConfiguration") dependencies.add(myConfiguration.name, project.files(project.provider { combinedInputs })) tasks.register("consumerTask", ConsumerTask::class.java) { // 3 it.artifactCollection = myConfiguration.incoming.artifactView {viewConfiguration -> viewConfiguration.attributes.attribute(artifactType, "my-custom-type") }.artifacts it.outputFile.set(File("build/consumerTask/output/output.txt")) } } } } 复制代码
主要分为以下几步:
- 声明与注册自定义
Transform
,指定输入与输出的artifactType
- 创建自定义的
configuration
,指定输入的依赖是什么(当然也可以直接用AGP
已有的configuration
) - 在使用时,通过自定义
configuration
的artifactView
,获取对应的产物 ConsumerTask
中消费自定义TransformAction
的输出产物
然后我们运行 ./gradlew consumerTask
就可以得到以下输出
> Task :app:consumerTask Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-common/1.7.10/bac80c520d0a9e3f3673bc2658c6ed02ef45a76a/kotlin-stdlib-common-1.7.10.jar. File exists = true Processing ~/AndroidProject/2022/argust/GradleTutorials/app/build/myTask/output/file.jar. File exists = true Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-jdk8/1.7.10/d70d7d2c56371f7aa18f32e984e3e2e998fe9081/kotlin-stdlib-jdk8-1.7.10.jar. File exists = true Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains/annotations/13.0/919f0dfe192fb4e063e7dacadee7f8bb9a2672a9/annotations-13.0.jar. File exists = true Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib/1.7.10/d2abf9e77736acc4450dc4a3f707fa2c10f5099d/kotlin-stdlib-1.7.10.jar. File exists = true Processing ~/.gradle/caches/modules-2/files-2.1/org.jetbrains.kotlin/kotlin-stdlib-jdk7/1.7.10/1ef73fee66f45d52c67e2aca12fd945dbe0659bf/kotlin-stdlib-jdk7-1.7.10.jar. File exists = true 复制代码
可以看出,当运行 consumerTask
时,执行了 MyTransform
,并将 jar
类型的产物转化成了 my-custom-type
TransformAction
在 AGP
中的应用
现在 AGP
中的 Transform
已经基本上都改成 TransformAction
了,我们一起来看几个例子
AarTransform
Android ARchive
,也就是 .aar
后缀的资源包, gradle
是如何使用它的呢?
如果有同学尝试过就知道,如果是默认使用 java-libray
的工程,肯定无法依赖并使用 aar
的,引入时会报 Could not resolve ${dependencyNotation}
,说明在 Android Gradle Plugin
当中,插件对 aar
包的依赖进行了处理,只有通过了插件处理,才能正确使用 aar
内的资源。那就来看看 AGP
是如何在 TransformAction
的帮助下做到这点的
Aar
转换的实现就是 AarTransform
,我们一起来看下源码:
// DependencyConfigurator.kt for (transformTarget in AarTransform.getTransformTargets()) { registerTransform( AarTransform::class.java, AndroidArtifacts.ArtifactType.EXPLODED_AAR, transformTarget ) { params -> params.targetType.setDisallowChanges(transformTarget) params.sharedLibSupport.setDisallowChanges(sharedLibSupport) } } public abstract class AarTransform implements TransformAction<AarTransform.Parameters> { @NonNull public static ArtifactType[] getTransformTargets() { return new ArtifactType[] { ArtifactType.SHARED_CLASSES, ArtifactType.JAVA_RES, ArtifactType.SHARED_JAVA_RES, ArtifactType.PROCESSED_JAR, ArtifactType.MANIFEST, ArtifactType.ANDROID_RES, ArtifactType.ASSETS, ArtifactType.SHARED_ASSETS, ArtifactType.JNI, ArtifactType.SHARED_JNI, // ... }; } @Override public void transform(@NonNull TransformOutputs transformOutputs) { // 具体实现 } 复制代码
代码也比较简单,主要做了下面几件事:
- 在
DependencyConfigurator
中注册Aar
转换成各种类型资源的TransformAction
- 在
AarTransform
中根据类型将aar
包中的文件解压到输出到各个目录
JetifyTransform
Jetifier
也是在迁移到 AndroidX
之后的常用功能,它可以将引用依赖内的 android.support.*
引用都替换为对 androidx
的引用,从而实现对 support
包的兼容
下面我们来看一下 JetifyTransform
的代码
// com.android.build.gradle.internal.DependencyConfigurator if (projectOptions.get(BooleanOption.ENABLE_JETIFIER)) { registerTransform( JetifyTransform::class.java, AndroidArtifacts.ArtifactType.AAR, jetifiedAarOutputType ) { params -> params.ignoreListOption.setDisallowChanges(jetifierIgnoreList) } registerTransform( JetifyTransform::class.java, AndroidArtifacts.ArtifactType.JAR, AndroidArtifacts.ArtifactType.PROCESSED_JAR ) { params -> params.ignoreListOption.setDisallowChanges(jetifierIgnoreList) } } // com.android.build.gradle.internal.dependency.JetifyTransform override fun transform(transformOutputs: TransformOutputs) { val inputFile = inputArtifact.get().asFile val outputFile = transformOutputs.file("jetified-${inputFile.name}") jetifierProcessor.transform2( input = setOf(FileMapping(inputFile, outputFile)), copyUnmodifiedLibsAlso = true, skipLibsWithAndroidXReferences = true ) } 复制代码
- 读取并判断
ENABLE_JETIFIER
属性,这就是我们在gradle.properties
中配置的jetifier
开关 - 为
aar
和jar
类型的依赖都注册JetifyTransform
转换 - 在
transform
中对support
包的依赖进行替换,完成后会将处理过的资源重新压缩,并且会带上jetified
的前缀
总结
本文主要讲解了 TransformAction
是什么, TransformAction
自定义,以及 TransformAction
在 AGP
中的应用,可以看出,目前 AGP
中的产物转换已经基本上都用 TransformAction
来实现了
事实上, AGP
对 TransformAction
进行了一定的封装,如果你只是想利用 ASM
实现字节码插桩,那么直接使用 AsmClassVisitorFactory
就好了。但如果想要阅读 AGP
的源码,了解 AGP
构建的过程,还是需要了解一下 TransformAction
的基本使用与原理的