Skip to main content

Build Logic

Pros of Convention Plugins with Version Catalog​

Simplified Configuration​

  • Less Boilerplate: Convention plugins reduce the need for repetitive configuration in each project, allowing you to centralize common settings.
  • Cleaner Build Files: Your build.gradle.kts files become more concise and readable, as the bulk of the configuration is handled by the convention plugins.

Easier Dependency Management​

  • Centralized Versioning: Using a version catalog allows you to define dependencies and their versions in one place (libs.versions.toml), making it easier to manage and update them across the project.
  • Avoids Conflicts: Centralized version management helps in avoiding version conflicts and ensuring that all modules use the same versions of dependencies.

Improved Maintainability​

  • Single Source of Truth: With a version catalog, all version numbers are managed centrally, simplifying the process of updating dependencies.
  • Modularization: Convention plugins encourage modularization by separating concerns and making it easier to manage different aspects of the build process.

Reusability​

  • Reusable Configurations: Convention plugins can be reused across multiple projects, saving time and effort when setting up new projects.

Cons of Convention Plugins with Version Catalog​

Complexity in Setup​

  • Initial Learning Curve: Setting up convention plugins and a version catalog can be complex and might require a deep understanding of Gradle, especially for teams unfamiliar with these concepts.
  • Customization Overhead: If the default behavior of a convention plugin doesn’t fit your specific needs, customizing it can be challenging.

Overhead in Small Projects​

  • Unnecessary Complexity: For smaller projects, the overhead of setting up and maintaining convention plugins and a version catalog might outweigh the benefits, making it an over-engineered solution.

Setup Instructions​

Follow these steps to set up your project with the build-logic module and apply predefined classes from android-beyond-template project.

Steps​

  1. Include build-logic in settings.gradle.kts

    • Add the following line to your settings.gradle.kts file: 
      includeBuild("build-logic")

  2. Import build-logic Module

    • Import the build-logic module into your new project.

  3. Replace Versions and Dependencies

    • Update your versions and dependencies inside libs.versions.toml.
    • Note: Leave the plugins section unchanged for now.
    • Sync Gradle.
    • If you encounter a "duplicate settings.gradle files" error, delete the redundant settings.gradle file in the new module if it includes nothing.

  4. Update Config File

    • Replace the applicationId and namespace with your project-specific values inside the Config file located in build-logic.

  5. Enable Kotlin K2 Compiler (Optional)

    • Add the following line to your gradle.properties file: 
      kotlin.experimental.tryK2=true

  6. Replace Plugin Aliases

    • Update your plugin aliases with the new ones defined in libs.versions.toml in your build.gradle.kts(:app) file: 
      alias(libs.plugins.convention.application)
      alias(libs.plugins.convention.compose.application)
    • Sync Gradle.

  7. Add Necessary Plugins

    • Add any required plugins in the build.gradle file at the project level. 
      alias(libs.plugins.kotlin.jvm) apply true
      alias(libs.plugins.kotlin.serialization) apply false
      alias(libs.plugins.kotlin.ksp) apply false
      alias(libs.plugins.hilt) apply false
      alias(libs.plugins.compose.compiler) apply false
      alias(libs.plugins.android.library) apply false

  8. Run the App

    • After completing the above steps, run the app. You should be good to go!

Follow these instructions carefully to ensure your project is set up correctly with the new build logic and configurations.

Explanation of configureAndroidKotlin Function​

The configureAndroidKotlin function is an internal utility function designed to configure common settings for Android projects using Kotlin. This function centralizes the configuration of Android and Kotlin settings, making it easier to maintain consistency across the project.

Function Definition​

The configureAndroidKotlin function is defined in the extension package and takes two parameters:

  • Project: The Gradle project instance.
  • CommonExtension: A generic type representing the Android extension (e.g., ApplicationExtension, LibraryExtension).

The configureAndroidKotlin function configures the following settings:

Namespace and SDK Versions​

  • namespace: Sets the namespace for the project using Config.android.nameSpace.
  • compileSdk: Sets the compile SDK version using Config.android.compileSdkVersion.

Default Config​

  • minSdk: Sets the minimum SDK version using Config.android.minSdkVersion.
  • testInstrumentationRunner: Sets the test instrumentation runner to androidx.test.runner.AndroidJUnitRunner.
  • vectorDrawables.useSupportLibrary: Enables the use of the support library for vector drawables.

Compile Options​

  • sourceCompatibility: Sets the source compatibility to Config.jvm.javaVersion.
  • targetCompatibility: Sets the target compatibility to Config.jvm.javaVersion.

Packaging Options​

  • resources.excludes: Excludes specific resources from the packaging.

Dependencies​

Adds the following dependencies using the version catalog. For example:

  • androidx-core-ktx
  • androidx-lifecycle-runtime-ktx
  • junit
  • androidx-junit
  • androidx-espresso-core
  • androidx-appcompat
  • androidx-activity-compose
  • androidx-lifecycle-viewmodel-compose

Kotlin Compile Options​

Configures the Kotlin compile options:

  • jvmTarget: Sets the JVM target to Config.jvm.kotlinJvm.
  • freeCompilerArgs: Adds free compiler arguments from Config.jvm.freeCompilerArgs.

Summary​

By using the configureAndroidKotlin function, you can centralize and standardize the configuration of your Android projects using Kotlin. This helps in maintaining consistency and reducing boilerplate code in your build.gradle.kts files.

Explanation of configureCompose Function​

The configureCompose function is an internal utility function designed to configure Jetpack Compose settings for Android projects. This function centralizes the configuration of Compose-related dependencies and settings, making it easier to maintain consistency across the project. And it is designed to be used in ComposeApplicationConventionPlugin and ComposeLibraryConventionPlugin.

Function Definition​

The configureCompose function is defined in the extension package and takes two parameters:

  • Project: The Gradle project instance.
  • CommonExtension: A generic type representing the Android extension (e.g., ApplicationExtension, LibraryExtension).

Configuration Details​

The configureCompose function configures the following settings:

Build Features​

  • buildFeatures.compose: Enables Jetpack Compose for the project.

Dependencies​

Adds the following dependencies using the version catalog. For example:

  • BOM (Bill of Materials):
    • androidx-compose-bom: Ensures that all Compose libraries use the same version.
  • Implementation Dependencies:
    • androidx-compose-foundation: Core foundational components for Jetpack Compose.
    • androidx-ui: Core UI components for Jetpack Compose.
    • androidx-ui-graphics: Graphics components for Jetpack Compose.
    • androidx-ui-tooling: Tooling support for Jetpack Compose.
    • androidx-ui-tooling-preview: Preview support for Jetpack Compose.
    • androidx-material3: Material Design components for Jetpack Compose.
    • androidx-navigation-compose: Navigation components for Jetpack Compose.
  • Android Test Implementation Dependencies:
    • androidx-ui-test-junit4: JUnit4 test support for Jetpack Compose.
  • Debug Implementation Dependencies:
    • androidx-ui-tooling: Tooling support for Jetpack Compose (debug configuration).
    • androidx-ui-test-manifest: Test manifest support for Jetpack Compose (debug configuration).

Summary​

By using the configureCompose function, you can centralize and standardize the configuration of Jetpack Compose settings and dependencies in your Android projects. This helps in maintaining consistency and reducing boilerplate code in your build.gradle.kts files.

How to Use the Plugins in an Android Project​

Plugin IDs​

Plugin ids are defined in build.gradle.kts files. Here is an example of how to define plugin ids for convention plugins in an Android project:

gradlePlugin {
    plugins {
        register("androidApplication") {
            id = "conventionPluginApplication.android.application"
            implementationClass = "plugin.AndroidApplicationConventionPlugin"
        }

        register("androidLibrary") {
            id = "conventionPluginLibrary.android.library"
            implementationClass = "plugin.AndroidLibraryConventionPlugin"
        }

        register("composeApplication") {
            id = "conventionPluginApplication.compose.application"
            implementationClass = "plugin.ComposeApplicationConventionPlugin"
        }

        register("composeLibrary") {
            id = "conventionPluginLibrary.compose.library"
            implementationClass = "plugin.ComposeLibraryConventionPlugin"
        }
    }
}

Steps​

To use the convention plugins in an Android project, follow these steps:

  1. Apply application and library plugins in your Android app or library modules' build.gradle.kts files.:

    • Example for an Android application module: 
      plugins {
          alias(libs.plugins.convention.application)
      }
    • Example for an Android library module: 
      plugins {
          alias(libs.plugins.convention.library)
      }

  2. Apply the compose plugin in your Android app or library modules' build.gradle.kts files.:

    • Example for an Android application module: 
      plugins {
          alias(libs.plugins.convention.compose.application)
      }
    • Example for an Android library module: 
      plugins {
          alias(libs.plugins.convention.compose.library)
      }

Summary​

Using convention plugins in an Android project provides a clear structure and reduces duplication across modules, but it also requires a solid understanding of Gradle's plugin system. Balancing the flexibility of individual module configurations with the reusability of convention plugins is key to maximizing their benefits.

Author

  • Name: Si Thu Hein (Codigo)
  • Edited: 14 Sep 2024