Understanding Gradle and the Android Build Process: Projects, Tasks, Dependency Management, and Packaging

Every Android developer interacts with Gradle, whether directly or indirectly, and this guide shows why an automated build tool is essential, what files are generated by Android Studio, and how dependency management works.

Why use an automation tool? Manually creating an assemble.sh script to compile Java to .class , convert to .dex , and zip into an APK quickly becomes unmanageable for multiple projects, feature additions, external libraries, debug/release builds, and multi‑channel packaging.

Gradle solves these problems by defining each module as a Project and each build step (e.g., generating R.java , compiling Java) as a Task . Tasks can depend on one another via TaskA.dependsOn(TaskB) , and doFirst / doLast hooks allow custom actions before or after a task.

Project structure

The default Android project contains .gradle and .idea directories for Gradle and Android Studio caches. Cleaning these caches (delete .idea / .gradle , run ./gradlew clean , or invalidate caches in Android Studio) often resolves sync issues.

Gradle Wrapper

The gradlew script ensures each project uses the correct Gradle version. It launches gradle-wrapper.jar , which downloads the specified distribution from gradle-wrapper.properties if not present. Example wrapper command:

exec "$JAVACMD" "${JVM_OPTS[@]}" -classpath "$CLASSPATH" org.gradle.wrapper.GradleWrapperMain "$@"

Root build.gradle

It starts with a buildscript block (executed first), followed by repositories (Google, JCenter, Maven Central) and dependencies (e.g., classpath 'com.android.tools.build:gradle:3.4.0' ). The allprojects block applies common repository settings to every module.

App module build.gradle

Applying com.android.application creates tasks such as assembleDebug and assembleRelease . The android block configures the build, while the dependencies block declares libraries using the new configurations implementation , api , compileOnly , and runtimeOnly .

Dependency configurations

implementation adds a library to both compile and runtime classpaths of the current module but not to consumers; api exposes it to consumers; compileOnly is compile‑time only; runtimeOnly is packaged but not compiled. These affect compileClasspath and runtimeClasspath of each component.

Example command to list the release runtime classpath:

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

Gradle resolves transitive dependencies from the component’s pom.xml , downloading both binary .aar files and their POM metadata.

Dependency conflicts

When different modules require different versions of the same library, Gradle selects the highest version by default. Conflict resolution strategies include disabling transitive dependencies, using exclude , or forcing a specific version. Baidu’s internal rule also checks version consistency against version.properties .

Packaging process

Key tasks include:

preBuild : performs pre‑compile checks (e.g., mismatched compile/runtime classpaths).

compileReleaseAidl : runs the AIDL compiler via AidlCompile .

Various generate and merge tasks that create and combine resources.

Transform tasks (e.g., ProGuard) that modify bytecode before dexing.

Dex conversion tasks that turn .class files into .dex files, catching duplicate classes or interface/class mismatches.

PackageApplication : packages the final APK.

The build proceeds through four steps: compiling Java sources with the appropriate classpath, applying transforms, converting to dex, and finally packaging resources and dex files into the APK.

Conclusion

Although the article does not cover Gradle’s lifecycle, plugin development, or the Transform API in depth, it provides a comprehensive overview of the Android build toolchain, enabling developers to locate the right entry point when troubleshooting build issues.