Understanding Gradle Build System for Android Development

Every Android developer interacts with Gradle, whether they realize it or not. When a new project is created in Android Studio, a default directory structure is generated and dependencies are added in app/build.gradle . Syncing the project may fail, prompting developers to search for solutions online. To truly understand why issues occur and how to resolve them, one must look beyond the IDE buttons and explore Gradle, the underlying automated build tool.

This article covers:

Why an automated build tool is needed

What the default Android project contains

Dependency management

Packaging process

By reading this guide, you can grasp how Gradle works, search more effectively for related problems, and solve common compilation errors faster.

Why an Automated Build Tool?

An APK is essentially a zip file containing code and resources. A naïve way to build an APK would be a shell script such as:

# Convert .java to .class
javac xxx.java
# Convert .class to .dex
dx xxx.class
# Package into APK
zip xxx.apk [code and resources]

When a project grows, additional steps are required, such as generating R.java and handling external libraries. A more realistic script looks like:

# Generate R.java
aapt [resource files]
# Compile Java sources
javac xxx.java R.java -classpath xxx.jar
# Convert to dex
dx xxx.class R.class xxx.jar
# Package into APK
zip xxx.apk [code and resources]

Maintaining such scripts across multiple projects quickly becomes cumbersome, especially when dealing with debug/release builds, multi‑channel packaging, and external dependencies. Gradle solves these problems by providing conventions, a standardized directory layout, and a powerful task system.

Default Android Project Structure

When Android Studio creates a new project, it generates directories such as .gradle , .idea , gradle/wrapper , settings.gradle , the root build.gradle , and the module app/build.gradle . The article explains the purpose of each:

.gradle and .idea store IDE and Gradle caches. Deleting them and running ./gradlew clean can resolve sync issues.

gradle/wrapper together with the gradlew scripts ensure that every project uses the correct Gradle version without requiring a global installation. The wrapper launches gradle-wrapper.jar which downloads the specified distribution if needed: exec "$JAVACMD" "${JVM_OPTS[@]}" -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@"

settings.gradle defines which modules are included in the build via the include method.

The root build.gradle contains the buildscript block (executed first), repositories , and dependencies for the Android Gradle Plugin: classpath 'com.android.tools.build:gradle:3.4.0'

The module app/build.gradle applies the com.android.application plugin, which creates tasks such as assembleDebug and assembleRelease . It also defines the android configuration block and the module’s own dependencies.

Dependency Management

Since AGP 3.0, Gradle uses implementation and api instead of the old compile . Other configurations include compileOnly , runtimeOnly , and runtimeOnly . Their effects can be illustrated with a simple dependency graph:

If module B depends on C with implementation , module A cannot compile against C directly, but C will be packaged in the final APK.

If B uses api , A can compile against C.

compileOnly makes C unavailable at runtime, while runtimeOnly excludes C from compilation but includes it in the APK.

Gradle distinguishes between compileClasspath (used for compilation) and runtimeClasspath (used for packaging). Example commands:

implementation project(':demo:mylibrary')

implementation 'androidx.appcompat:appcompat:1.0.2'

To inspect the resolved runtime classpath:

./gradlew :app:dependencies --configuration releaseRuntimeClasspath > dependencies.txt

The output shows transitive dependencies, e.g.:

releaseRuntimeClasspath - Resolved configuration for runtime for variant: release
\--- androidx.appcompat:appcompat:1.0.2
    +--- androidx.annotation:annotation:1.0.0
    +--- androidx.core:core:1.0.1
    ...

Gradle obtains this information from the pom.xml files published alongside Maven artifacts, which contain dependency entries with scopes such as compile and runtime .

Dependency Conflicts

When different modules request different versions of the same library, Gradle selects the highest version by default. Conflicts can be resolved by excluding a transitive dependency, forcing a specific version, or using custom rules (e.g., Baidu App’s rule that disallows versions higher than those defined in version.properties ).

Packaging Process

With Gradle 5.1.1 and Android Gradle Plugin 3.1.2, a typical release build is executed with:

gradlew assembleRelease --dry-run

Key tasks include:

preBuild : Performs pre‑compilation checks, such as detecting mismatched compileClasspath and runtimeClasspath versions.

compileReleaseAidl : Uses AidlCompile to run the AIDL processor.

Various generate and merge tasks that create and combine resources and code.

Transform tasks (e.g., :app:transformClassesWithProguardForRelease ) that modify bytecode before packaging.

PackageApplication : Packages compiled .class / .dex files and resources into the final APK.

The article also explains how the classpath is used during compilation, how the Transform mechanism works, and why the dex conversion can reveal issues that the Java compiler cannot (e.g., duplicate classes or interface/class mismatches).

Conclusion

Although the article does not cover advanced topics such as Gradle’s lifecycle, plugin development, or custom Transform implementations, it provides a solid overview of the Android build toolchain. Readers should now know where to look when encountering common Gradle‑related problems.

References

https://docs.gradle.org/current/userguide/userguide.html

https://developer.android.com/studio/build/gradle-plugin-3-0-0-migration?hl=zh-cn

https://github.com/gradle/gradle

https://android.googlesource.com/platform/tools/base/+/refs/tags/gradle_3.1.2