Gradle Made Simple (Part 2): Gradle Basics Every Flutter Dev Must Know

In Part 2 of the "Gradle Made Simple" series, we dive into the core concepts every Flutter developer needs to grasp to effectively manage and troubleshoot their Gradle builds. We'll explore AGP compatibility, version management, and the critical gradle.properties file.

AGP vs. Gradle Wrapper

The Android Gradle Plugin (AGP) teaches Gradle how to build Android apps, while the Gradle Wrapper serves as the build system engine. These two must be synchronized to prevent build failures. An incompatibility can result in errors like "Plugin requires newer Gradle" or "Unsupported class file major version".

To update your Gradle Wrapper, open gradle/wrapper/gradle-wrapper.properties and adjust the distributionUrl to a compatible version:

• distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip

Verify the update locally by running:

• ./gradlew --version

To check your AGP version, look in your project-level build.gradle (Groovy) or build.gradle.kts (Kotlin) file.

Old Gradle:

buildscript {
 dependencies {
 classpath "com.android.tools.build:gradle:8.6.0"
 }
}

New Way (settings.gradle + app/build.gradle):

In settings.gradle:

plugins {
 id "com.android.application" version "8.6.0"
}

In app/build.gradle:

plugins {
 id "com.android.application"
}

Remember that AGP 8.6.0 requires Gradle 8.7 or newer. Refer to the official AGP release notes for compatibility information.

Understanding gradle.properties

The gradle.properties file is where you configure global options and environment settings for your builds. It has two locations:

• Project-level (<project_root>/gradle.properties): Affects only this project.
• Global/user-level (~/.gradle/gradle.properties): Affects all projects on your machine.

Common Settings

1. org.gradle.jvmargs:
   • What it does: Configures memory and file encoding for Gradle.
   • Example: org.gradle.jvmargs=-Xmx2048m -Dfile.encoding=UTF-8
   • Use it: Always in gradle.properties at the project root to prevent out-of-memory errors.
2. android.useAndroidX:
   • What it does: Migrates your project to AndroidX libraries.
   • Example: android.useAndroidX=true
   • Use it: Always, for modern projects.
3. android.enableJetifier:
   • What it does: Converts dependencies using old support libraries to AndroidX.
   • Example: android.enableJetifier=true
   • Use it: Along with useAndroidX=true.
4. org.gradle.parallel:
   • What it does: Enables parallel execution of independent modules.
   • Example: org.gradle.parallel=true
   • Use it: For large projects with multiple modules.

You can override settings temporarily from the command line:

• ./gradlew assembleDebug -Pandroid.useAndroidX=false

Useful Gradle Commands

• ./gradlew clean: Cleans the build.
• ./gradlew assembleDebug: Builds a debug APK.
• ./gradlew assembleRelease: Builds a release APK.

Mastering Gradle is essential for efficient Flutter development. Understanding its quirks transforms it from a nightmare to a manageable tool.