Gradle Convention Plugins

A collection of convention plugins to consistently configure Android applications and libraries. The plugins require Gradle 8.4+ and Android Gradle Plugin 8.3+ for Android projects.

• Installation
  • Version Catalog Requirements
• Plugins
  • Gradle Properties
  • KGP Root Plugin
  • Android Application
  • Published Android Library
  • Published Kotlin Library
  • Release Conventions
  • Dependency Management
  • Kotlinter
• Configuration
  • Dagger
  • Deep Links
  • Hilt
  • Java API Desugaring
  • Jetpack Compose
  • JUnit
  • Kotlinx Serialization
  • Moshi
  • Publishing
  • Room

Installation

All plugins are published to Maven Central. To use the plugins add the following repository to settings.gradle.kts under pluginManagement:

pluginManagement {
    repositories {
        mavenCentral()
    }
}

Version Catalog Requirements

When using the convention plugins certain versions are expected to be in the version catalog of the project. The version catalog named libs is used by default but the catalog can be changed by setting the kgp.versioncatalog.name property in the gradle.properties file of the root project.

The following versions are required in the version catalog:

• kgpJdk: The JDK version to use when setting jvmToolchain.

The following versions are required in the version catalog when using Android convention plugins:

• kgpCompileSdk: The SDK version the application compiles against.
• kgpMinSdk: The minimum API level required to run the application.
• kgpTargetSdk: The API level the application targets.
• kgpDokka: The version used for the Android Documentation Plugin dependency.

Plugins

Gradle Properties

Some convention plugins auto-apply other plugins to better support common use cases. However, it is possible the plugins are not wanted on certain projects. When present in the gradle.properties file, the properties below can be used to prevent plugins from being auto-applied on supported projects:

kgp.plugins.autoapply.dependencymanagement=false
kgp.plugins.autoapply.dokka=false
kgp.plugins.autoapply.kotlinter=false
kgp.plugins.autoapply.kover=false

KGP Root Plugin

A plugin that only gets applied to the root project in a multi-project build. It applies common configuration to the root project and subprojects including:

• Creating a clean task to delete the build directory of the root project.
• Setting the following default values for subprojects when enabled with kgp.autoconfigure.publishingproperties:
  • group: com.kroger.{rootProject.name}
  • version: set to the value of the environment variable BUILD_VERSION if it exists, otherwise 0.0.1
• Configures the Kotlinter plugin.
• Configures the Dependency Management plugin.

Usage

Add the following plugin to the root project build.gradle.kts file:

plugins {
    alias(libs.plugins.conventions.rootPlugin)
}

Android Application

• Applies common configuration to Android applications such as defaultConfig, compileOptions, and packaging
• Also applies and configures the following plugins:
  • Android Application
  • Kotlin Android
  • Kover
  • See Compose Configuration for more information on how Jetpack Compose is configured

Usage

Add the following plugin to the build.gradle.kts file of the Android application:

plugins {
    alias(libs.plugins.conventions.androidApplication)
}

Published Android Library

• Applies common configuration to Android libraries such as defaultConfig, compileOptions, packaging, and creating a sources jar.
• Also applies and configures the following plugins:
  • Release Conventions
  • Android Library
  • Kotlin Android
  • Kover
  • Dokka
  • android-junit5
  • See Compose Configuration for more information on how Jetpack Compose is configured

Usage

Add the following plugin to the build.gradle.kts file of the Android library:

plugins {
    alias(libs.plugins.conventions.publishedAndroidLibrary)
}

Alternatively if the library does not need to be published the following plugin can be used instead:

plugins {
    alias(libs.plugins.conventions.androidLibrary)
}

Published Kotlin Library

• Applies common configuration to Kotlin libraries such as creating a sources jar and configuring junit5 testing.
• Also applies and configures the following plugins:
  • Release Conventions
  • Kotlin JVM
  • Java Library
  • Kover
  • Dokka

Usage

Add the following plugin to the build.gradle.kts file of the Kotlin library:

plugins {
    alias(libs.plugins.conventions.publishedKotlinLibrary)
}

Alternatively if the library does not need to be published the following plugin can be used instead:

plugins {
    alias(libs.plugins.conventions.KotlinLibrary)
}

Release Conventions

This plugin is automatically applied when using either the Published Android Library Plugin or the Published Kotlin Library plugin. It uses the Gradle Maven Publish Plugin to publish the aar artifact for Android libraries or jar artifact for Kotlin libraries, including the sources jar when available, to the repository specified by the kgp.repository.url gradle property. The following project properties are used when publishing:

• group id: project.group
• artifact id: project.name
• version: project.version

These default values can be changed by using further configuration in the build.gradle.kts file of the project or the gradle.properties file of the project as shown in the documentation.

The following additional properties can be added to the gradle.properties file:

• kgp.repository.name: the name of the repository as it will appear in generated Gradle tasks. Default is Artifactory.
• kgp.repository.url: the URL of the repository to publish to. Default is null.

Standalone Usage

plugins {
    alias(libs.plugins.conventions.release)
}

Dependency Management

This applies the dependency analysis android gradle plugin and the gradle versions plugin.

Usage

The plugin is applied by default to the root project when using the KGP Root Plugin.

Auto-applying the plugin can be disabled by setting the following property to false in the gradle.properties file of the root project:

kgp.plugins.autoapply.dependencymanagement=false

To manually apply the plugin add the following to the root project build.gradle.kts file:

plugins {
    alias(libs.plugins.conventions.dependencyMaintenance)
}

Dependency Analysis Android Gradle Plugin

• Reports on unused dependencies that should be removed
• Used transitive dependencies (which you may want to declare directly)
• Dependencies declared on the wrong configuration (api vs implementation vs compileOnly, etc.)

Tasks

To run the dependency analysis plugin execute the following gradle task from the project root directory:

gradlew buildHealth

A report will be created in the {projectRoot}/build/reports/dependency-analysis directory named build-health-report in txt and json format by default.

Gradle Versions Plugin

• Reports on dependencies that have an update available
• Includes updates to Gradle
• Updates that are not considered stable (e.g., beta, snapshot) will not be included in the report by default

Tasks

To run the gradle versions plugin and check for dependencies with an update execute the following gradle task from the project root directory:

gradlew dependencyUpdates

A report will be created in the {projectRoot}/build/dependencyUpdates directory named report in txt and json format by default. The files show what dependencies are up to date, which have newer versions available, and which dependency versions could not be checked.

Kotlinter

The Kotlinter plugin is enabled by default for all projects that apply an Android plugin (application or library) or a kotlin plugin.

Auto-applying the plugin can be disabled by setting the following property to false in the gradle.properties file of the project:

kgp.plugins.autoapply.kotlinter=false

A pre-commit hook to lint kotlin files can be created by running the createLintKotlinPreCommitHook task from the root project. By default the task will create the hook in the .husky directory if it exists, otherwise the hook will be created in the .git/hooks directory. The hook executes the checkKotlinFiles task which will run ktlint against staged files for all configured projects. If a ktlint violation exists the commit will be cancelled.

If you want ktlint to try to auto-format staged files as a part of the commit then run the createFormatKotlinPreCommitHook instead.

The checkKotlinFiles task generates a report at build/lint-report.json that shows any issues and the formatKotlinFiles task generates a report at build/format-report.txt that shows any formatting fixes made. By default the Kotlinter plugin version specifies what version of ktlint is used. See the Kotlinter docs for details on how to override the ktlint version if needed.

Configuration

Dagger

The following utility functions exist to help configure Dagger:

• dagger(): adds the dagger, javax:inject, and dagger-compiler dependencies. Optionally adds dagger-android-processor, dagger-android, and dagger-android-support depending on the parameters used.

Version Catalog Requirements

The following versions are expected in the Version Catalog when using the Dagger utility function:

• kgpDagger: The version to use for dagger dependencies.

Deep Links

The following utility functions exist to help configure Deep Links:

• deepLink(): adds the deeplink and KSP deeplink-processor dependencies. Defaults the deep link doc file to {buildDir}/doc/deeplinks.json.

Version Catalog Requirements

The following versions are expected in the Version Catalog when using the Deep Links utility functions:

• kgpDeepLink: The version to use for deep link dependencies.

Hilt

By default when the Android Application plugin is applied hilt will be auto-configured on the project.

Auto-configuration does the following:

• Applies the KAPT and Hilt Android plugins
• KaptExtension.correctErrorTypes: set to true
• Dependencies
  • Adds the Hilt Android Compiler dependency to the kapt, kaptTest, and kaptAndroidTest configurations.
  • Adds the Hilt Android Testing dependency to the testImplementation and AndroidTestImplementation configurations.

  Note: if using Hilt with androidx dependencies you must add the androidx hilt compiler and other needed dependencies.

Version Catalog Requirements

The following versions are expected in the Version Catalog when using Hilt auto-configuration:

• kgpDagger: The version to use for Hilt dependencies.
• kgpAndroidxHiltCompiler: The version of the hilt compiler to use for compatible androidx library processing.

Properties

The following properties are used in the gradle.properties file of projects to control how auto-configuration is applied:

• kgp.android.autoconfigure.hilt.application: if true then Hilt will be auto-configured when the Android Application plugin is applied. Default is true.
• kgp.android.autoconfigure.hilt.library: if true then Hilt will be auto-configured when the Android Library plugin is applied. Default is false.

Java API Desugaring

Enabling desugaring allows the use of newer Java APIs in older versions of Java. Desugaring can be auto-configured when the Android Application plugin or the Published Android Library plugin is applied.

Auto-configuration does the following:

• android.compileOptions.isCoreLibraryDesugaringEnabled: set to true
• Dependencies:
  • Adds the desugar jdk libs dependency to the coreLibraryDesugaring configuration.

Version Catalog Requirements

The following versions are expected in the Version Catalog when using desugaring auto-configuration:

• kgpAndroidDesugarJdkLibs: The version to use for the com.android.tools:desugar_jdk_libs dependency.

Properties

The following property is used in the gradle.properties file of projects to control how auto-configuration is applied:

• kgp.android.autoconfigure.corelibrarydesugaring: if true then desugaring will be configured on supported projects. Default is false.

Jetpack Compose

By default when an Android plugin is applied (Android Application or Published Android Library) then Jetpack Compose will be auto-configured.

Auto-configuration does the following:

• android.buildFeatures.compose: set to true
• android.composeOptions.kotlinCompilerExtensionVersion: set to androidxComposeCompiler version from Version Catalog.
• Dependencies
  • Adds the Jetpack Compose bill of materials and the default dependencies needed for Android Studio preview support and writing UI tests.
  • Optionally adds further dependencies depending on the value of the kgp.android.autoconfigure.compose.dependencies property.

Version Catalog Requirements

The following versions and bundle are expected in the Version Catalog when using Jetpack Compose auto-configuration:

• kgpAndroidxComposeBom: Jetpack Compose Bill of Materials version to use for Jetpack Compose dependencies.
• kgpAndroidxComposeCompiler: Version of the Jetpack Compose Compiler to use. The version specified should be compatible with the version of the Kotlin Compiler Plugin used according to the Compatibility Map.
• kgpCompose: This Bundle is only required in the Version Catalog if the kgp.android.autoconfigure.compose.dependencies property is set to bundle. If it is then the compose bundle is added to the dependencies of the project.

Properties

The following properties are used in the gradle.properties file of projects to further control how auto-configuration is applied:

• kgp.android.autoconfigure.compose: if true then Jetpack Compose will be auto-configured on supported projects. Default is true.
• kgp.android.autoconfigure.compose.dependencies: controls what additional compose dependencies are added by default to projects based on the values below.
  • bundle: adds dependencies from the compose bundle in the Version Catalog.
  • material: adds dependencies needed to use Material UI.
  • material3: adds dependencies needed to use Material3 UI. Also adds the core Material Icons.
  • none: does not add any additional dependencies. This is the default value.

JUnit

A couple utility functions exist to help configure JUnit dependencies:

• junit5(): adds the junit-bom BOM and the junit-jupiter dependencies to the testImplementation configuration.
• junitVintage(): in addition to calling junit5() this will also add junit4 to the testImplementation configuration and the junit-vintage-engine to the testRuntimeOnly configuration.

Version Catalog Requirements

The following versions are expected in the Version Catalog when using the junit utility functions:

• kgpJunit4: The version of junit4. This is only required if junitVintage() is used.
• kgpJunit5: The version of junit5.

Kotlinx Serialization

The following utility function exists to help configure Kotlinx Serialization:

• kotlinxSerialization(): adds the org.jetbrains.kotlin.plugin.serialization plugin. If json is true adds the kotlinx-serialization-json dependency.

Version Catalog Requirements

The following versions are expected in the Version Catalog when using the kotlinxSerialization() utility functions:

• kotlinxSerialization: The version to use for Kotlinx Serialization dependencies.

Moshi

The following utility function exists to help configure Moshi:

• moshi(): adds the moshi dependency. If codegen is true moshi-kotlin-codegen is added to the ksp configuration. If moshiAdapters is true moshi-adapters is included. If moshiKoltlinReflect is true then moshi-kotlin is included.

Version Catalog Requirements

The following versions are expected in the Version Catalog when using the moshi utility functions:

• kgpMoshi: The version to use for Moshi dependencies.

Publishing

Setting the default group and version for all subprojects can be disabled.

Properties

The following property is used in the root gradle.properties file to control how auto-configuration is applied:

• kgp.autoconfigure.publishingproperties: if true then group and version will be set for all subprojects by the KGP Root Plugin. Default is true.

Room

The following utility functions exist to help configure Room:

• room(): adds the room-runtime, room-ktx, room-compiler dependencies. room-testing and the room plugin are also added/applied if a schemaDirectory is specified.

Version Catalog Requirements

The following versions are expected in the Version Catalog when using the room utility functions:

• kgpAndroidxRoom: The version to use for Room dependencies.