Gradle architecture documentation

This directory contains documentation that describes Gradle's architecture and how the various pieces fit together and work.

Architecture decision records (ADRs)

The Gradle team uses ADRs to record architectural decisions that the team has made.

See Architecture decisions records for the list of ADRs. Be aware these are very technical descriptions of the decisions, and you might find the documentation below more useful as an introduction to the internals of Gradle.

Architecture overview

Platform architecture

Gradle is arranged into several coarse-grained components called "platforms". Each platform provides support for some kind of automation, such as building JVM software or building Gradle plugins. Platforms typically extend the features of other platforms to add this support.

By understanding the Gradle platforms and their relationships, you can get a feel for where in the Gradle source tree a particular feature is implemented.

See Gradle platform architecture for a list of the platforms and more details.

Gradle runtimes

Gradle is also made up of several different processes that work together to "run the build", such as the Gradle daemon and the gradlew command.

Each process, or "runtime", applies different constraints to the code that runs in that process. For example, each process has different supported JVMs and a different set of services available for dependency injection. While a lot of Gradle source code runs only in the Gradle daemon, not all of it does so. When working on some source code it is important to be aware of the runtimes in which it will run, so that you don't break these constraints. There is some assistance in the IDE for this plus a lot of validation that is applied at build time and on CI, but it is useful to keep these constraints in mind as well.

See Gradle runtimes for a list of these runtimes and more details.

Build execution model

Gradle generally does some work in response to a client request. There are several different clients, for example the gradlew command or the tooling API client, that can send requests to a Gradle daemon. Each daemon runs one request at a time. Generally speaking, the daemons only act in response to a request from a client and do not take any action on their own. There are some background actions that the daemon takes, for example monitoring system memory, watching for file changes or cleaning up caches. The daemon never runs any user code in the background.

There are several different types of requests, such as a request to run a set of tasks, or to query a tooling model, or to stop. Some requests will require that the build is configured and maybe some work executed, and other requests might not.

See Build execution model for more details.

Build state model

As Gradle executes, it acts on various pieces of the build definition, such as each project in the build. Gradle tracks the state of each piece and transitions each piece through its lifecycle as the build runs.

A central part of the Gradle architecture is the "build state model", which holds the state for each piece and coordinates state transitions and other mutations. Most source code in Gradle is arranged by which part(s) of the build state model it acts on. This affects the lifecycle of the code and the set of services available for dependency injection. When working on some source code it is important to be aware of the model it acts on.

See build state model for more details.