Artifact Transforms

What if you want to makes changes to the files contained in one of your dependencies before you use it?

For example, you might want to unzip a compressed file, adjust the contents of a JAR, or delete unnecessary files from a dependency that contains multiple files prior to using the result in a task.

Gradle has a built-in feature for this called Artifact Transforms. With Artifact Transforms, you can modify, add to, remove from the set files (or artifacts) - like JAR files - contained in a dependency. This is done as the last step when resolving artifacts, before tasks or tools like the IDE can consume the artifacts.

Artifact Transforms Overview

Each component exposes a set of variants, where each variant is identified by a set of attributes (i.e., key-value pairs such as debug=true).

When Gradle resolves a configuration, it looks at each dependency, resolves it to a component, and selects the corresponding variant from that component that matches the requested attributes. If the component does not have a matching variant, resolution fails unless Gradle can construct a sequence of transformations that will modify an existing artifact to create a valid match (without changing its transitive dependencies).

Artifact Transforms are a mechanism for converting one type of artifact into another during the build process. They provide the consumer an efficient and flexible mechanism for transforming the artifacts of a given producer to the required format without needing the producer to expose variants in that format.

Artifact Transforms are a lot like tasks. They are units of work with some inputs and outputs. Mechanisms like UP-TO-DATE and caching work for transforms as well.

The primary difference between tasks and transforms is how they are scheduled and put into the chain of actions Gradle executes when a build configures and runs. At a high level, transforms always run before tasks because they are executed during dependency resolution. Transforms modify artifacts BEFORE they become an input to a task.

Here’s a brief overview of how to create and use Artifact Transforms:

Implement a Transform: You define an artifact transform by creating a class that implements the TransformAction interface. This class specifies how the input artifact should be transformed into the output artifact.
Declare request Attributes: Attributes (key-value pairs used to describe different variants of a component) like org.gradle.usage=java-api and org.gradle.usage=java-runtime are used to specify the desired artifact format or type.
Register a Transform: You register the transform by using the registerTransform() method of the dependencies block. This method tells Gradle that a transform can be used to modify the artifacts of any variant that possesses the given "from" attributes. It also tells Gradle what new set of "to" attributes will describe the format or type of the resulting artifacts.
Use the Transform: When a resolution requires an artifact that isn’t already present in the selected component (because none of the actual artifact possess compatible attributes to the requested attributes), Gradle doesn’t just give up! Instead, Gradle first automatically searches all registered transforms to see if it can construct a chain of transformations that will ultimately produce a match. If Gradle finds such a chain, it then runs each transform in sequence, and delivers the transformed artifacts as a result.

1. Implement a Transform

A transform is typically written as an abstract class that implements the TransformAction interface. It can optionally have parameters defined in a separate interface.

Each transform has exactly one input artifact. It must be annotated with the @InputArtifact annotation.

Then, you implement the transform(TransformOutputs) method from the TransformAction interface. This method’s implementation defines what the transform should do when triggered. The method has a TransformOutputs parameter that you use to tell Gradle what artifacts the transform produces.

Here, MyTransform is the custom transform action that converts a jar artifact to a transformed-jar artifact:

build.gradle.kts

abstract class MyTransform : TransformAction<TransformParameters.None> {
    @get:InputArtifact
    abstract val inputArtifact: Provider<FileSystemLocation>

    override fun transform(outputs: TransformOutputs) {
        val inputFile = inputArtifact.get().asFile
        val outputFile = outputs.file(inputFile.name.replace(".jar", "-transformed.jar"))
        // Perform transformation logic here
        inputFile.copyTo(outputFile, overwrite = true)
    }
}

build.gradle

abstract class MyTransform implements TransformAction<TransformParameters.None> {
    @InputArtifact
    abstract Provider<FileSystemLocation> getInputArtifact()

    @Override
    void transform(TransformOutputs outputs) {
        def inputFile = inputArtifact.get().asFile
        def outputFile = outputs.file(inputFile.name.replace(".jar", "-transformed.jar"))
        // Perform transformation logic here
        inputFile.withInputStream { input ->
            outputFile.withOutputStream { output ->
                output << input
            }
        }
    }
}

2. Declare request Attributes

Attributes specify the required properties of a dependency.

Here we specify that we need the transformed-jar format for the runtimeClasspath configuration:

build.gradle.kts

configurations.named("runtimeClasspath") {
    attributes {
        attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, "transformed-jar")
    }
}

build.gradle

configurations.named("runtimeClasspath") {
    attributes {
        attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, "transformed-jar")
    }
}

3. Register a Transform

A transform must be registered using the dependencies.registerTransform() method.

Here, our transform is registered with the dependencies block:

build.gradle.kts

dependencies {
    registerTransform(MyTransform::class) {
        from.attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, "jar")
        to.attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, "transformed-jar")
    }
}

build.gradle

dependencies {
    registerTransform(MyTransform) {
        from.attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, "jar")
        to.attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, "transformed-jar")
    }
}

"To" attributes are used to describe the format or type of the artifacts that this transform can use as an input, and "from" attributes to describe the format or type of the artifacts that it produces as an output.

4. Use the Transform

During a build, Gradle automatically runs registered transforms to satisfy a resolution request if a match is not directly available.

Since no variants exist supplying artifacts of requested format (as none contain the artifactType attribute with a value of "transformed-jar"), Gradle attempts to construct a chain of transformations that will supply it.

Gradle’s search finds MyTransform, which is registered as producing the requested format, so it will automatically be run. Running this transform action modifies the artifacts of an existing source variant to produce new artifacts that are delivered to the consumer, in the requested format.

Gradle produces a "virtual artifact set" of the component as part of this process.

Understanding Artifact Transforms

Dependencies can have different variants, essentially different versions or forms of the same dependency. These variants can each provide a different artifact set, meant to satisfy different use cases, such as compiling code, browsing documentation or running applications.

Each variant is identified by a set of attributes. Attributes are key-value pairs that describe specific characteristics of the variant.

Let’s use the following example where an external Maven dependency has two variants:

Table 1. Maven Dependencies
Variant	Description
`org.gradle.usage=java-api`	Used for compiling against the dependency.
`org.gradle.usage=java-runtime`	Used for running an application that uses the dependency.

And a project dependency has even more variants:

Table 2. Project Dependencies
Variant	Description
`org.gradle.usage=java-api` `org.gradle.libraryelements=classes`	Represents classes directories.
`org.gradle.usage=java-api` `org.gradle.libraryelements=jar`	Represents a packaged JAR file, containing classes and resources.

The variants of a dependency may differ in their transitive dependencies or in the set of artifacts they contain, or both.

For example, the java-api and java-runtime variants of the Maven dependency only differ in their transitive dependencies, and both use the same artifact — the JAR file. For the project dependency, the java-api,classes and the java-api,jars variants have the same transitive dependencies but different artifacts — the classes directories and the JAR files respectively.

When Gradle resolves a configuration, it uses the attributes defined to select the appropriate variant of each dependency. The attributes that Gradle uses to determine which variant to select are called the requested attributes.

For example, if a configuration requests org.gradle.usage=java-api and org.gradle.libraryelements=classes, Gradle will select the variant of each dependency that matches these attributes (in this case, classes directories intended for use as an API during compilation). Matches do not have to exact, as some attribute values can be identified to Gradle as compatible with other values and used interchangeably during matching.

Sometimes, a dependency might not have a variant with attributes that match the requested attributes. In such cases, Gradle can transform one variant’s artifacts into another "virtual artifact set" by modifying its artifacts without changing its transitive dependencies.

Gradle will not attempt to select or run Artifact Transforms when a variant of the dependency matching the requested attributes already exists.

For example, if the requested variant is java-api,classes, but the dependency only has java-api,jar, Gradle can potentially transform the JAR file into a classes directory by unzipping it using an Artifact Transform that is registered with these attributes.

Understanding Artifact Transforms Chains

When Gradle resolves a configuration and a dependency does not have a variant with the requested attributes, it attempts to find a chain of one or more Artifact Transforms that can be run sequentially to create the desired variant. This process is called Artifact Transform selection:

The Artifact Transform Selection Process:

Start with requested Attributes:
- Gradle starts with the attributes specified on the configuration being resolved, appends any attributes specified on an ArtifactView, and finally appends any attributes declared directly on the dependency.
- It considers all registered transforms that modify these attributes.
Find a path to existing Variants:
- Gradle works backwards, trying to find a path from the requested attributes to an existing variant.

For example, if the minified attribute has values true and false, and a transform can change minified=false to minified=true, Gradle will use this transform if only minified=false variants are available but minified=true is requested.

Gradle selects a chain of transforms using the following process:

If there is only one possible chain that produces the requested attributes, it is selected.
If there are multiple such chains, then only the shortest chains are considered.
If there are still multiple chains remaining that are equally suitable but produce different results, the selection fails, and an error is reported.
If all the remaining chains produce the same set of resulting attributes, Gradle arbitrarily selects one.

How can multiple chains produce different suitable results? Transforms can alter multiple attributes at a time. A suitable result of a transformation chain is one possessing attributes compatible with the requested attributes. But a result may contain other attributes as well, that were not requested, and are irrelevant to the result.

For example: if attributes A=a and B=b are requested, and variant V1 contains attributes A=a, B=b, and C=c, and variant V2 contains attributes A=a, B=b, and D=d, then since all the values of A and B are identical (or compatible) either V1 or V2 would satisfy the request.

A Full Example

Let’s continue exploring the minified example begun above: a configuration requests org.gradle.usage=java-runtime, org.gradle.libraryelements=jar, minified=true. The dependencies are:

External guava dependency with variants:
- org.gradle.usage=java-runtime, org.gradle.libraryelements=jar, minified=false
- org.gradle.usage=java-api, org.gradle.libraryelements=jar, minified=false
Project producer dependency with variants:
- org.gradle.usage=java-runtime, org.gradle.libraryelements=jar, minified=false
- org.gradle.usage=java-runtime, org.gradle.libraryelements=classes, minified=false
- org.gradle.usage=java-api, org.gradle.libraryelements=jar, minified=false
- org.gradle.usage=java-api, org.gradle.libraryelements=classes, minified=false

Gradle uses the minify transform to convert minified=false variants to minified=true.

For guava, Gradle converts
- org.gradle.usage=java-runtime, org.gradle.libraryelements=jar, minified=false to
- org.gradle.usage=java-runtime, org.gradle.libraryelements=jar, minified=true.
For producer, Gradle converts
- org.gradle.usage=java-runtime, org.gradle.libraryelements=jar, minified=false to
- org.gradle.usage=java-runtime, org.gradle.libraryelements=jar, minified=true.

Then, during execution:

Gradle downloads the guava JAR and runs the transform to minify it.
Gradle executes the producer:jar task to produce the JAR and then runs the transform to minify it.
These tasks and transforms are executed in parallel where possible.

To set up the minified attribute so that the above works you must add the attribute to all JAR variants being produced, and also add it to all resolvable configurations being requested. You should also register the attribute in the attributes schema.

build.gradle.kts

val artifactType = Attribute.of("artifactType", String::class.java)
val minified = Attribute.of("minified", Boolean::class.javaObjectType)
dependencies {
    attributesSchema {
        attribute(minified)                      (1)
    }
    artifactTypes.getByName("jar") {
        attributes.attribute(minified, false)    (2)
    }
}

configurations.runtimeClasspath.configure {
    attributes {
        attribute(minified, true)                (3)
    }
}

dependencies {
    registerTransform(Minify::class) {
        from.attribute(minified, false).attribute(artifactType, "jar")
        to.attribute(minified, true).attribute(artifactType, "jar")
    }
}

dependencies {                                 (4)
    implementation("com.google.guava:guava:27.1-jre")
    implementation(project(":producer"))
}

tasks.register<Copy>("resolveRuntimeClasspath") { (5)
    from(configurations.runtimeClasspath)
    into(layout.buildDirectory.dir("runtimeClasspath"))
}

build.gradle

def artifactType = Attribute.of('artifactType', String)
def minified = Attribute.of('minified', Boolean)
dependencies {
    attributesSchema {
        attribute(minified)                      (1)
    }
    artifactTypes.getByName("jar") {
        attributes.attribute(minified, false)    (2)
    }
}

configurations.runtimeClasspath {
    attributes {
        attribute(minified, true)                (3)
    }
}

dependencies {
    registerTransform(Minify) {
        from.attribute(minified, false).attribute(artifactType, "jar")
        to.attribute(minified, true).attribute(artifactType, "jar")
    }
}
dependencies {                                 (4)
    implementation('com.google.guava:guava:27.1-jre')
    implementation(project(':producer'))
}

tasks.register("resolveRuntimeClasspath", Copy) {(5)
    from(configurations.runtimeClasspath)
    into(layout.buildDirectory.dir("runtimeClasspath"))
}

1	Add the attribute to the schema
2	All JAR files are not minified
3	Request that the runtime classpath is minified
4	Add the dependencies which will be transformed
5	Add task that requires the transformed artifacts

You can now see what happens when we run the resolveRuntimeClasspath task, which resolves the runtimeClasspath configuration. Gradle transforms the project dependency before the resolveRuntimeClasspath task starts. Gradle transforms the binary dependencies when it executes the resolveRuntimeClasspath task:

$ gradle resolveRuntimeClasspath
> Task :producer:compileJava
> Task :producer:processResources NO-SOURCE
> Task :producer:classes
> Task :producer:jar

> Transform producer.jar (project :producer) with Minify
Nothing to minify - using producer.jar unchanged

> Task :resolveRuntimeClasspath
Minifying guava-27.1-jre.jar
Nothing to minify - using listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar unchanged
Nothing to minify - using jsr305-3.0.2.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 j2objc-annotations-1.1.jar unchanged
Nothing to minify - using animal-sniffer-annotations-1.17.jar unchanged
Nothing to minify - using failureaccess-1.0.1.jar unchanged

BUILD SUCCESSFUL in 0s
3 actionable tasks: 3 executed

Implementing Artifact Transforms

Similar to task types, an artifact transform consists of an action and some optional parameters. The major difference from custom task types is that the action and the parameters are implemented as two separate classes.

Artifact Transforms without Parameters

An artifact transform action is provided by a class implementing TransformAction. Such a class implements the transform() method, which converts the input artifacts into zero, one, or multiple output artifacts.

Most Artifact Transforms are one-to-one, so the transform method will be used to transform each input artifact contained in the from variant into exactly one output artifact.

The implementation of the artifact transform action needs to register each output artifact by calling TransformOutputs.dir() or TransformOutputs.file().

You can supply two types of paths to the dir or file methods:

An absolute path to the input artifact or within the input artifact (for an input directory).
A relative path.

Gradle uses the absolute path as the location of the output artifact. For example, if the input artifact is an exploded WAR, the transform action can call TransformOutputs.file() for all JAR files in the WEB-INF/lib directory. The output of the transform would then be the library JARs of the web application.

For a relative path, the dir() or file() method returns a workspace to the transform action. The transform action needs to create the transformed artifact(s) at the location of the provided workspace.

The output artifact(s) replace the input artifact(s) in the transformed variant in the order they were registered. For example, if the selected input variant contains the artifacts lib1.jar, lib2.jar, lib3.jar, and the transform action registers a minified output artifact <artifact-name>-min.jar for each input artifact, then the transformed configuration will consist of the artifacts lib1-min.jar, lib2-min.jar, and lib3-min.jar.

Here is the implementation of an Unzip transform, which unzips a JAR file into a classes directory. The Unzip transform does not require any parameters:

build.gradle.kts

abstract class Unzip : TransformAction<TransformParameters.None> {          (1)
    @get:InputArtifact                                                      (2)
    abstract val inputArtifact: Provider<FileSystemLocation>

    override
    fun transform(outputs: TransformOutputs) {
        val input = inputArtifact.get().asFile
        val unzipDir = outputs.dir(input.name + "-unzipped")                (3)
        unzipTo(input, unzipDir)                                            (4)
    }

    private fun unzipTo(zipFile: File, unzipDir: File) {
        // implementation...
    }
}

build.gradle

abstract class Unzip implements TransformAction<TransformParameters.None> { (1)
    @InputArtifact                                                          (2)
    abstract Provider<FileSystemLocation> getInputArtifact()

    @Override
    void transform(TransformOutputs outputs) {
        def input = inputArtifact.get().asFile
        def unzipDir = outputs.dir(input.name + "-unzipped")                (3)
        unzipTo(input, unzipDir)                                            (4)
    }

    private static void unzipTo(File zipFile, File unzipDir) {
        // implementation...
    }
}

1	Use `TransformParameters.None` if the transform does not use parameters
2	Inject the input artifact
3	Request an output location for the unzipped files
4	Do the actual work of the transform

Note how the implementation uses @InputArtifact to inject an artifact to transform into the action class, so that it can be accessed within the transform method. This method requests a directory for the unzipped classes by using TransformOutputs.dir() and then unzips the JAR file into this directory.

Artifact Transforms with Parameters

An artifact transform may require parameters, such as a String for filtering or a file collection used to support the transformation of the input artifact. To pass these parameters to the transform action, you must define a new type with the desired parameters. This type must implement the marker interface TransformParameters.

The parameters must be represented using managed properties and the parameter type must be a managed type. You can use an interface or abstract class to declare the getters, and Gradle will generate the implementation. All getters need to have proper input annotations, as described in the incremental build annotations table.

Here is the implementation of a Minify transform that makes JARs smaller by only keeping certain classes in them. The Minify transform requires knowledge of the classes to keep within each JAR, which is provided as an Map property within its parameters:

build.gradle.kts

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 ...
    }
}

build.gradle

abstract class Minify implements TransformAction<Parameters> { (1)
    interface Parameters extends TransformParameters {         (2)
        @Input
        Map<String, Set<String>> getKeepClassesByArtifact()
        void setKeepClassesByArtifact(Map<String, Set<String>> keepClasses)
    }

    @PathSensitive(PathSensitivity.NAME_ONLY)
    @InputArtifact
    abstract Provider<FileSystemLocation> getInputArtifact()

    @Override
    void transform(TransformOutputs outputs) {
        def fileName = inputArtifact.get().asFile.name
        for (entry in parameters.keepClassesByArtifact) {      (3)
            if (fileName.startsWith(entry.key)) {
                def 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 void minify(File artifact, Set<String> keepClasses, File jarFile) {
        println "Minifying ${artifact.name}"
        // Implementation ...
    }
}

1	Declare the parameter type
2	Interface for the transform parameters
3	Use the parameters
4	Use the unchanged input artifact when no minification is required

Observe how you can obtain the parameters by TransformAction.getParameters() in the transform() method. The implementation of the transform() method requests a location for the minified JAR by using TransformOutputs.file() and then creates the minified JAR at this location.

Remember that the input artifact is a dependency, which may have its own dependencies. Suppose your artifact transform needs access to those transitive dependencies. In that case, it can declare an abstract getter returning a FileCollection and annotate it with @InputArtifactDependencies. When your transform runs, Gradle will inject the transitive dependencies into the FileCollection property by implementing the getter.

Note that using input artifact dependencies in a transform has performance implications; only inject them when needed.

Artifact Transforms with Caching

Artifact Transforms can make use of the build cache to store their outputs and avoid rerunning their transform actions when the result is known.

To enable the build cache to store the results of an artifact transform, add the @CacheableTransform annotation on the action class.

For cacheable transforms, you must annotate its @InputArtifact property — and any property marked with @InputArtifactDependencies — with normalization annotations such as @PathSensitive.

The following example demonstrates a more complex transform that relocates specific classes within a JAR to a different package. This process involves rewriting the bytecode of both the relocated classes and any classes that reference them (class relocation):

build.gradle.kts

@CacheableTransform                                                          (1)
abstract class ClassRelocator : TransformAction<ClassRelocator.Parameters> {
    interface Parameters : TransformParameters {                             (2)
        @get:CompileClasspath                                                (3)
        val externalClasspath: ConfigurableFileCollection
        @get:Input
        val excludedPackage: Property<String>
    }

    @get:Classpath                                                           (4)
    @get:InputArtifact
    abstract val primaryInput: Provider<FileSystemLocation>

    @get:CompileClasspath
    @get:InputArtifactDependencies                                           (5)
    abstract val dependencies: FileCollection

    override
    fun transform(outputs: TransformOutputs) {
        val primaryInputFile = primaryInput.get().asFile
        if (parameters.externalClasspath.contains(primaryInputFile)) {       (6)
            outputs.file(primaryInput)
        } else {
            val baseName = primaryInputFile.name.substring(0, primaryInputFile.name.length - 4)
            relocateJar(outputs.file("$baseName-relocated.jar"))
        }
    }

    private fun relocateJar(output: File) {
        // implementation...
        val relocatedPackages = (dependencies.flatMap { it.readPackages() } + primaryInput.get().asFile.readPackages()).toSet()
        val nonRelocatedPackages = parameters.externalClasspath.flatMap { it.readPackages() }
        val relocations = (relocatedPackages - nonRelocatedPackages).map { packageName ->
            val toPackage = "relocated.$packageName"
            println("$packageName -> $toPackage")
            Relocation(packageName, toPackage)
        }
        JarRelocator(primaryInput.get().asFile, output, relocations).run()
    }
}

build.gradle

@CacheableTransform                                                          (1)
abstract class ClassRelocator implements TransformAction<Parameters> {
    interface Parameters extends TransformParameters {                       (2)
        @CompileClasspath                                                    (3)
        ConfigurableFileCollection getExternalClasspath()
        @Input
        Property<String> getExcludedPackage()
    }

    @Classpath                                                               (4)
    @InputArtifact
    abstract Provider<FileSystemLocation> getPrimaryInput()

    @CompileClasspath
    @InputArtifactDependencies                                               (5)
    abstract FileCollection getDependencies()

    @Override
    void transform(TransformOutputs outputs) {
        def primaryInputFile = primaryInput.get().asFile
        if (parameters.externalClasspath.contains(primaryInput)) {           (6)
            outputs.file(primaryInput)
        } else {
            def baseName = primaryInputFile.name.substring(0, primaryInputFile.name.length - 4)
            relocateJar(outputs.file("$baseName-relocated.jar"))
        }
    }

    private relocateJar(File output) {
        // implementation...
        def relocatedPackages = (dependencies.collectMany { readPackages(it) } + readPackages(primaryInput.get().asFile)) as Set
        def nonRelocatedPackages = parameters.externalClasspath.collectMany { readPackages(it) }
        def relocations = (relocatedPackages - nonRelocatedPackages).collect { packageName ->
            def toPackage = "relocated.$packageName"
            println("$packageName -> $toPackage")
            new Relocation(packageName, toPackage)
        }
        new JarRelocator(primaryInput.get().asFile, output, relocations).run()
    }
}

1	Declare the transform cacheable
2	Interface for the transform parameters
3	Declare input type for each parameter
4	Declare a normalization for the input artifact
5	Inject the input artifact dependencies
6	Use the parameters

Note the classes to be relocated are determined by examining the packages of the input artifact and its dependencies. Additionally, the transform ensures that packages contained in JAR files on an external classpath are not relocated.

Incremental Artifact Transforms

Similar to incremental tasks, Artifact Transforms can avoid some work by only processing files that have changed since the last execution. This is done by using the InputChanges interface.

For Artifact Transforms, only the input artifact is an incremental input; therefore, the transform can only query for changes there. To use InputChanges in the transform action, inject it into the action.

For more information on how to use InputChanges, see the corresponding documentation for incremental tasks.

Here is an example of an incremental transform that counts the lines of code in Java source files:

build.gradle.kts

abstract class CountLoc : TransformAction<TransformParameters.None> {

    @get:Inject                                                         (1)
    abstract val inputChanges: InputChanges

    @get:PathSensitive(PathSensitivity.RELATIVE)
    @get:InputArtifact
    abstract val input: Provider<FileSystemLocation>

    override
    fun transform(outputs: TransformOutputs) {
        val outputDir = outputs.dir("${input.get().asFile.name}.loc")
        println("Running transform on ${input.get().asFile.name}, incremental: ${inputChanges.isIncremental}")
        inputChanges.getFileChanges(input).forEach { change ->          (2)
            val changedFile = change.file
            if (change.fileType != FileType.FILE) {
                return@forEach
            }
            val outputLocation = outputDir.resolve("${change.normalizedPath}.loc")
            when (change.changeType) {
                ChangeType.ADDED, ChangeType.MODIFIED -> {

                    println("Processing file ${changedFile.name}")
                    outputLocation.parentFile.mkdirs()

                    outputLocation.writeText(changedFile.readLines().size.toString())
                }
                ChangeType.REMOVED -> {
                    println("Removing leftover output file ${outputLocation.name}")
                    outputLocation.delete()
                }
            }
        }
    }
}

build.gradle

abstract class CountLoc implements TransformAction<TransformParameters.None> {

    @Inject                                                             (1)
    abstract InputChanges getInputChanges()

    @PathSensitive(PathSensitivity.RELATIVE)
    @InputArtifact
    abstract Provider<FileSystemLocation> getInput()

    @Override
    void transform(TransformOutputs outputs) {
        def outputDir = outputs.dir("${input.get().asFile.name}.loc")
        println("Running transform on ${input.get().asFile.name}, incremental: ${inputChanges.incremental}")
        inputChanges.getFileChanges(input).forEach { change ->          (2)
            def changedFile = change.file
            if (change.fileType != FileType.FILE) {
                return
            }
            def outputLocation = new File(outputDir, "${change.normalizedPath}.loc")
            switch (change.changeType) {
                case ADDED:
                case MODIFIED:
                    println("Processing file ${changedFile.name}")
                    outputLocation.parentFile.mkdirs()

                    outputLocation.text = changedFile.readLines().size()

                case REMOVED:
                    println("Removing leftover output file ${outputLocation.name}")
                    outputLocation.delete()

            }
        }
    }
}

1	Inject `InputChanges`
2	Query for changes in the input artifact

This transform will only run on source files that have changed since the last run, as otherwise the line count would not need to be recalculated.

Registering Artifact Transforms

You need to register the artifact transform actions, providing parameters if necessary so that they can be selected when resolving dependencies.

To register an artifact transform, you must use registerTransform() within the dependencies {} block.

There are a few points to consider when using registerTransform():

At least one from and to attributes are required.
Each from attribute must have a corresponding to attribute, and vice-versa.
The transform action itself can have configuration options. You can configure them with the parameters {} block.
You must register the transform on the project that has the configuration that will be resolved.
You can supply any type implementing TransformAction to the registerTransform() method.

For example, imagine you want to unpack some dependencies and put the unpacked directories and files on the classpath. You can do so by registering an artifact transform action of type Unzip, as shown here:

build.gradle.kts

dependencies {
    registerTransform(Unzip::class.java) {
        from.attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named<LibraryElements>(LibraryElements.JAR))
        from.attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, ArtifactTypeDefinition.JAR_TYPE)
        to.attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named<LibraryElements>(LibraryElements.CLASSES_AND_RESOURCES))
        to.attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, ArtifactTypeDefinition.DIRECTORY_TYPE)
    }
}

build.gradle

dependencies {
    registerTransform(Unzip) {
        from.attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(LibraryElements, LibraryElements.JAR))
        from.attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, ArtifactTypeDefinition.JAR_TYPE)
        to.attribute(LibraryElements.LIBRARY_ELEMENTS_ATTRIBUTE, objects.named(LibraryElements, LibraryElements.CLASSES_AND_RESOURCES))
        to.attribute(ArtifactTypeDefinition.ARTIFACT_TYPE_ATTRIBUTE, ArtifactTypeDefinition.DIRECTORY_TYPE)
    }
}

Another example is that you want to minify JARs by only keeping some class files from them. Note the use of the parameters {} block to provide the classes to keep in the minified JARs to the Minify transform:

build.gradle.kts

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 {
    registerTransform(Minify::class) {
        from.attribute(minified, false).attribute(artifactType, "jar")
        to.attribute(minified, true).attribute(artifactType, "jar")

        parameters {
            keepClassesByArtifact = keepPatterns
        }
    }
}

build.gradle

def artifactType = Attribute.of('artifactType', String)
def minified = Attribute.of('minified', Boolean)
def keepPatterns = [
    "guava": [
        "com.google.common.base.Optional",
        "com.google.common.base.AbstractIterator"
    ] as Set
]


dependencies {
    registerTransform(Minify) {
        from.attribute(minified, false).attribute(artifactType, "jar")
        to.attribute(minified, true).attribute(artifactType, "jar")

        parameters {
            keepClassesByArtifact = keepPatterns
        }
    }
}

Executing Artifact Transforms

On the command line, Gradle runs tasks; not Artifact Transforms: ./gradlew build. So how and when does it run transforms?

There are two ways Gradle executes a transform:

Artifact Transforms execution for project dependencies can be discovered ahead of task execution and therefore can be scheduled before the task execution.
Artifact Transforms execution for external module dependencies cannot be discovered ahead of task execution and, therefore are scheduled inside the task execution.

In well-declared builds, project dependencies can be fully discovered during task configuration ahead of task execution scheduling. If the project dependency is badly declared (e.g., missing a task input), the transform execution will happen inside the task.

It’s important to remember that Artifact Transforms:

will only ever be run if no matching variants exist to satisfy a request
can be run in parallel
will not be rerun if possible (if multiple resolution requests require the same transform to be executed on the same artifacts, and the transform is cacheable, the transform will only be run once and the results fetched from the cache on each subsequent request)

`TransformAction`s are only instantiated and run if input artifacts exist. If there are no artifacts present in an input variant to a transform, that transform will be skipped. This can happen in the middle of a chain of actions, resulting in all subsequent transforms being skipped.

Was this page helpful?