Topics

#android #gradle-plugin #groovy #java #jvm #kotlin #scala

Language breakdown

No language data available.

▸ Files click to expand

README

= Dependency Analysis Gradle Plugin

image::https://img.shields.io/maven-metadata/v.svg?label=release&metadataUrl=https%3A%2F%2Frepo1.maven.org%2Fmaven2%2Fcom%2Fautonomousapps%2Fdependency-analysis%2Fcom.autonomousapps.dependency-analysis.gradle.plugin%2Fmaven-metadata.xml[Latest version,link="https://mvnrepository.com/artifact/com.autonomousapps.dependency-analysis/com.autonomousapps.dependency-analysis.gradle.plugin"] image::https://img.shields.io/maven-metadata/v?metadataUrl=https%3A%2F%2Fcentral.sonatype.com%2Frepository%2Fmaven-snapshots%2Fcom%2Fautonomousapps%2Fdependency-analysis-gradle-plugin%2Fmaven-metadata.xml[Latest snapshot,link="https://central.sonatype.com/service/rest/repository/browse/maven-snapshots/com/autonomousapps/dependency-analysis-gradle-plugin/"] image::https://github.com/autonomousapps/dependency-analysis-gradle-plugin/actions/workflows/test.yml/badge.svg[Build status,link="https://github.com/autonomousapps/dependency-analysis-android-gradle-plugin/actions/workflows/test.yml"]

== Features [[features]]

The Dependency Analysis Gradle Plugin has the following features:

It reports on dependency-related issues such as:

… unused dependencies.
… used transitive dependencies, which it is advisable you declare directly.
… dependencies declared on the wrong configuration (api vs implementation vs compileOnly, etc.).
… unused annotation processors.

For these types of issues, the plugin has auto-remediation capabilities.

It can also report on plugin-related issues such as when:

… the org.jetbrains.kotlin.jvm plugin is applied but isn't used.
… the com.android.library plugin is applied but the module could be JVM.

Additionally, the plugin:

… will warn when a classpath has duplicate class files.
… can trigger downloading of external dependencies, which can help with containerized builds.
… print the dominator tree for a project, which can help with discovering "fat" dependencies that are bloating the

size of your deployables.

… generate a project graph to help visualize the shape of your project.

== Compatibilities

Supported languages: Java and Kotlin on Android; and Groovy, Java, Kotlin, and Scala on the JVM.

The plugin only analyzes modules with these specific plugins applied:

.Android modules

com.android.application
com.android.library
com.android.test
com.android.kotlin.multiplatform.library

In the case of Android modules, the plugin also takes into account whether org.jetbrains.kotlin.android has been applied.

.JVM modules

java-library
org.jetbrains.kotlin.jvm

.KMP (Kotlin Multiplatform) modules for jvm and androidLibrary targets

org.jetbrains.kotlin.multiplatform
com.android.kotlin.multiplatform.library

.Other JVM plugins

This plugin supports these three plugins, but only in the that they also have an "application" plugin applied (see below), or java-library in the case of groovy and scala.

java
groovy
scala

In addition, the plugin distinguishes between "libraries" and "applications." The former have an API, while the latter do not. In practical terms, this means that "application" modules should not have any api-like dependencies.

.JVM application modules Modules with the following plugins (in addition to those above) are considered to be applications.

application
org.gretty
com.google.cloud.tools.jib
org.springframework.boot

== Add to your project and use

For detailed instructions, see https://github.com/autonomousapps/dependency-analysis-android-gradle-plugin/wiki/Adding-to-your-project[the wiki].

The simplest approach is to add the following:

.settings.gradle.kts [source,kotlin]

plugins { id("com.autonomousapps.build-health") version "<>" }

and then in the root build script:

.build.gradle.kts [source,kotlin]

dependencyAnalysis { issues { all { onAny { severity("fail") } } } }

IMPORTANT: If your project uses Kotlin or Android (or both), then those plugins must also be loaded in the settings script classloader (or a parent). See https://github.com/autonomousapps/dependency-analysis-gradle-plugin/wiki/Adding-to-your-project[the wiki] for more information

For a quick start, just run the following:

./gradlew buildHealth

You will probably see output like the following:

Task :buildHealth FAILED

FAILURE: Build failed with an exception.

What went wrong:

Execution failed for task ':buildHealth'.

There were dependency violations. See report at file:///path/to/project/build/reports/dependency-analysis/build-health-report.txt

If you wish to have this (potentially very long) report printed to console, add this to the dependencyAnalysis DSL:

.build.gradle.kts [source,kotlin]

dependencyAnalysis { reporting { printBuildHealth(true) } }

=== Partial analysis

The instructions above will configure the plugin to do a global analysis of the entire multi-project project. There are cases where it may be desirable to do partial analysis, or analysis of just one or a set of projects, or conversely to exclude specific projects. There are various ways to achieve this.

One such approach is to use the projectHealth task, which is discussed in more detail <>.

Another common approach, especially for very large projects, is to <> the com.autonomousapps.dependency-analysis plugin, rather than the com.autonomousapps.build-health plugin as discussed above.

Finally, one may use a Gradle property to specify which projects to include:

.gradle.properties [source,properties]

Include all projects except those whose path begins with `:prefix`

dependency.analysis.project.includes=^((?!:prefix)).*$

The value provided is evaluated as a regex. The example above uses a negative lookahead to exclude any project whose path (project.path) begins with :prefix, and include everything else.

== Repositories

From 2.19.0 for releases, and 2.18.1-SNAPSHOT for snapshots, this plugin uses https://central.sonatype.com. To add this plugin to your project, use the following repositories.

.settings.gradle.kts [source,kotlin]

pluginManagement { repositories { // releases mavenCentral() // snapshots maven(url = "https://central.sonatype.com/repository/maven-snapshots/") // Once you start using pluginManagement, you should explicitly add this, // unless you NEVER want to use this repository gradlePluginPortal() } }

== More advanced usage [[advanced_usage]]

You do not have to apply this plugin to all projects via the settings script. It can also be applied to only specific subprojects. In this case, it must also be applied to the root build script.

.root build.gradle.kts [source,kotlin]

plugins { id("com.autonomousapps.dependency-analysis") version "<>" }

.sub/project/build.gradle.kts [source,kotlin]

plugins { id("com.autonomousapps.dependency-analysis") }

IMPORTANT: If your project uses Kotlin or Android (or both), then those plugins must also be loaded in the root build script classloader (or a parent). See https://github.com/autonomousapps/dependency-analysis-gradle-plugin/wiki/Adding-to-your-project[the wiki] for more information

== Project Health [[project_health]]

The analysis can be run against individual modules with the projectHealth task. For example:

./gradlew app:projectHealth

== Fix dependency issues automatically

It is common for the plugin to report many issues with your project's dependency declarations. Since fixing manually can be tedious, the plugin also provides a task to auto-remediate all issues.

./gradlew fixDependencies

The fixDependencies task is registered on each project where the plugin is applied. Running it as above will run the task in each subproject. See also https://dev.to/autonomousapps/one-click-dependencies-fix-191p[One click dependencies fix].

=== Fix only some dependency issues automatically

In some circumstances, it may be considered infeasible to resolve all issues in one pass. Maybe you have a very large project, or you publish libraries and you know that changing your dependency declarations will also change your libraries' metadata, which might break consumers. To support this use-case, the the fixDependencies task takes an optional flag to tell it to, essentially, make only "safe" changes.

./gradlew fixDependencies --upgrade

With this flag in place, the fixDependencies task will not remove or "downgrade" any dependency declarations. It will only add or "upgrade" declarations (e.g., from implementation to api).

In an incremental rollout scenario, one could imagine using the --upgrade flag, then updating all consumers, then finally removing the flag and removing all unused dependencies.

=== Caveats

If the analysis has any bugs, then fixing the dependency declarations make break your build (but this is also the case with manual fixes). If you encounter this, please https://github.com/autonomousapps/dependency-analysis-gradle-plugin/issues/new/choose[file an issue].

Additionally, the rewriting functionality is based on a simplified Gradle Groovy DSL grammar, which will fail in the presence of complex Groovy build scripts. The Kotlin DSL grammar has full support for the entire Kotlin language, which makes the rewriting functionality work much better for Gradle Kotlin DSL scripts. There are no plans to do the same for Gradle Groovy DSL.

== Reason

You may be curious why the plugin is emitting (or not emitting) advice regarding some dependency. You can ask it why:

./gradlew lib:reason --id com.squareup.okio:okio:2.2.2 <1>

Task :lib:reason

You asked about the dependency 'com.squareup.okio:okio:2.2.2'. There is no advice regarding this dependency.

Shortest path from :lib to com.squareup.okio:okio:2.2.2: :lib \--- com.squareup.okio:okio:2.2.2

Source: main

Exposes class okio.BufferedSource (implies api).

<1> The version string is optional.

== Basic configuration

For detailed information on how to configure the plugin, see https://github.com/autonomousapps/dependency-analysis-android-gradle-plugin/wiki/Customizing-plugin-behavior[the wiki].

To configure the plugin, use the https://github.com/autonomousapps/dependency-analysis-android-gradle-plugin/blob/main/src/main/kotlin/com/autonomousapps/DependencyAnalysisExtension.kt[dependencyAnalysis] extension.

Below is a summary of the top-level DSL options:

.build.gradle.kts [source,kotlin]

dependencyAnalysis { // Declare that the plugin should use typesafe project accessors. False by default. useTypesafeProjectAccessors(true)

// Configure ABI exclusion rules. abi { ... }

// Configure the severity of issues, and exclusion rules, for potentially the entire project. issues { ... }

// Configure issue reports. reporting { ... }

// Configure dependency structure rules (bundles, mapping, etc). structure { ... }

// Configure usage rules. usage { ... } }

== Ancillary tasks

As mentioned <>, the plugin has a variety of features not strictly related to maintaining a correct dependency graph.

=== Trigger downloading of external dependencies

This task will resolve all the external dependencies for a given source set's compile and runtime classpaths. "Resolving" a dependency will also result in downloading that dependency. A common case where this is useful is when you want to create an image for a containerized build.

./gradlew ::resolveExternalDependenciesMain

where "Main" refers to the name of the source set or Android variant (capitalized).

=== Print the dominator tree

This will print the https://en.wikipedia.org/wiki/Dominator(graphtheory)[dominator tree] for the given project. This is useful when looking for "fat" dependencies that contribute significantly to final binary size (such as with a fatjar or when building an image), and in cases where it's desirable to shrink that binary.

./gradlew ::printDominatorTreeCompileMain

where "Main" refers to the name of the source set or Android variant (capitalized).

=== Generate a project graph

This will generate various views of the project graph in your multi-project build, for both compile and runtime classpaths. In addition to the graphviz output, there is also a topological sort, which might be useful for debugging issues with evaluation order.

./gradlew ::projectGraphMain

where "Main" refers to the name of the source set or Android variant (capitalized).

== Programmatic usage and API guarantees

From version 3.0.0, the plugin includes an api definition in api/api.txt. Any backwards-incompatible change from then on will result in a major version release. Note that some code is public only due to tooling limitations; most of this code is in an internal package, but com.autonomousapps.tasks is also considered "internal." Usage of any API in these internal packages is at your own risk.

For typical users who only apply the plugin and run the primary tasks (buildHealth, projectHealth, reason, etc.), major releases should be treated as non-events. For these users, the "API" is just those primary tasks.

== Publications

The following is a list of articles / blog posts that have been published discussing this plugin:

https://medium.com/@emartynov/from-spaghetti-to-strict-cleaning-up-gradle-dependencies-in-a-large-android-codebase-47b72662109d[From Spaghetti to Strict: Cleaning Up Gradle Dependencies in a large Android codebase]
https://blog.gradle.org/detect-maven-hijack-risks-in-gradle-with-plugin[Detecting Maven-Hijack-style risks in Gradle builds with the Dependency Analysis Gradle Plugin]
https://dev.to/autonomousapps/the-proper-care-and-feeding-of-your-gradle-build-d8g[The proper care and feeding of your Gradle build]
https://dev.to/autonomousapps/dependency-analysis-gradle-plugin-using-bytecode-analysis-to-find-unused-dependencies-509n[Dependency Analysis Gradle Plugin: Using bytecode analysis to find unused dependencies]
https://dev.to/autonomousapps/dependency-analysis-gradle-plugin-what-s-an-abi-3l2h[Dependency Analysis Gradle Plugin: What's an ABI?]
https://dev.to/autonomousapps/reducing-my-gradle-plugin-s-impact-on-configuration-time-a-journey-32h2[Reducing my Gradle plugin's impact on configuration time: A journey]
https://dev.to/autonomousapps/one-click-dependencies-fix-191p[One-click dependencies fix]

This plugin has also been featured in these newsletters: