Example of how to idiomatically structure a large build with Gradle 7.2+

• For a better understanding of the concepts used in this example, check out Understanding Gradle.
• In addition to this, check How to set up a larger Gradle project.
• here is documentation and another sample on this topic in the Gradle User Manual.

Example

This example is a software product called Idiomatic Gradle (IG).

To build the example, clone this repository and run the following for more information:

• ./gradlew :tasks
• ./gradlew :projects

This example consists of:

Production code

Inside the 'product' folder, there are three components/builds:

• product/ig-server: A server providing some services
• product/ig-api: A client API Jar that clients (e.g. Android Apps) can integrate directly
• product/ig-common: Some common code used by both Server and API Jar

For the sake of the sample each of these folders only contain one subproject. In a real-world application, this can be structured into many, many more Gradle subprojects.

Packaging and Publishing

Both the server and the client API Jar require some special packaging to be published/distributed. Hence, this is configured in a separate component/build only responsible for aggregating build results:

• aggregation/package-server: Package the complete server and its dependencies into one fat jar that can run without other dependencies
• aggregation/publish-api: Package the client into one Jar that is published to a Maven repository

Testing

Each project contains unit tests using Gradle's default setup for Java projects with the src/test/java folder. Furthermore, some projects contain end2end tests testing with the real (packaged) server and the real client API Jar. For this, the packaging/publishing projects provide their results in the build for other subprojects to consume.

Idiomatic Build Logic Structure

The build contains some standard configuration for Java compilation and testing. It contains more involved configuration code to configure the packaging/publishing and the end2end test setup. There are multiple ways to do all this in Gradle today. This sample employs the following good patterns which result in a good build structure (easy to maintain and fast for Gradle to execute) as described here.

With this, the following outdated practices are avoided:

• No direct dependencies between tasks declared (except for extending lifecycle tasks like assemble or check)
• No direct dependencies between tasks from different subprojects are declared
• No cross-project configuration (subproject / allprojects) is performed
• Each build script of a subproject is simpler to read as all relationships to other projects are expressed in terms of dependencies
• ...

Discussions and alternative structuring options

• Using a Version Catalog
• Name of 'Settings Plugin' project
• Using JVM packages for precompiled script plugins

More questions or points you would like to discuss? Please open an issue.

FAQ

• Android Studio: 'gradle/plugins' project clean uses different Gradle version

More questions or points you would like to discuss? Please open an issue.

Summer 2022 Update (Gradle 7.5.1)

• Moved all Gradle details into gradle folder. build-logic is now gradle/plugins following the Gradle recommendations - see gradle/gradle#21192.
• Alternative setups using Gradle's new Version Catalog concept (see #4).
  • Use Catalog for Aliases (keep Platform) - Replace the ExternalLibrariesExtension for aliases with a catalog - libs.versions.toml - shared by all builds/components.
  • Use only the Catalog (remove Platform) - Remove the gradle/platform project and put the versions directly into the catalog instead.