# Information View

## Introduction

As a build automation tool, Gradle strives to be both performant and flexible. Gradle's build cache is used to achieve its performance goals. Similarly, Gradle's configuration objects and script files are designed to be flexible automation tools.

|Content|Description|
|--|--|
|[Build Cache](#Build-Cache)|This section descibes how Gradle uses the cache to meet its performance goals, the run-time cache implementation behavior and the cache storage solution.|
|[Configuration Object](#Configuration-Object-Definition-Model)|This section describes how Gradle meets its flexibility by using run-time configuration objects, how those objects are loaded from persistent configuration data and how those objects relate to each other.|

## Build Cache

We identify Gradle's caching mechanism as a key architectural element which contributes greatly to Gradle's performance. We will describe the purpose of Gradle's cache, its usage, cached information consistency mechanisms and data retention policies.

### Purpose & Usage

One of Gradle's quality properties is performance^{[1](https://hackmd.io/_kQoeX1gQWCIiwAKNdXpOA)}. Gradle's [build cache](https://docs.gradle.org/current/userguide/build_cache.html), improves performance by storing previously computed information such that subsequent Gradle builds need not perform redundant work. Caching is an application of the *reuse of resources and results* architectural tactic.

To improve performance, Gradle utilizes the cache by executing [incremental builds](https://hackmd.io/wlbMQxXaSmuTBk5hLWpKDQ?both#Incremental-Builds) and skipping the loading phase phase for some [configuation objects](#Configuration-Objects) during the [configuration lifecycle phase](https://hackmd.io/wlbMQxXaSmuTBk5hLWpKDQ?both#Configuration).

### Cache Implementation

Tasks which are tagged as [cacheable](https://hackmd.io/wlbMQxXaSmuTBk5hLWpKDQ?both#Cacheable-Task) will have their output stored in the cache [storage](#Storage) following a successful execution. A task which produces reproducible results (if the same input is given, then the same output is produced) can be tagged as cacheable.

Therefore, instead of executing cacheable tasks, the cached outputs may be retrieved through a simple key-value pair lookup. The key would be the task's input (or its hash).

When looking for cached entitites, Gradle will [first search the local cache](https://github.com/gradle/gradle/blob/f5dbf19bdf2115386000a16bc1722b220f1622f1/subprojects/build-cache/src/main/java/org/gradle/caching/internal/controller/DefaultBuildCacheController.java#L99) followed by the remote cache. This maximizes performance by minimizing [network transfer overhead](https://en.wikipedia.org/wiki/Overhead_(computing))

Gradle uses a a simple [locking mechanism](https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/locks/ReadWriteLock.html) as as evidenced by the [code](https://github.com/gradle/gradle/blob/7b9ecdc1ebabb0ffd78e23b9611edddaf2638c28/subprojects/build-cache/src/main/java/org/gradle/caching/local/internal/DirectoryBuildCacheService.java#L107) to prevent concurrent read and write access to the cache. The cache's consistency is also kept consistent by [removing corrupt cached files](https://github.com/gradle/gradle/blob/7b9ecdc1ebabb0ffd78e23b9611edddaf2638c28/subprojects/build-cache/src/main/java/org/gradle/caching/local/internal/DirectoryBuildCacheService.java#L121).

### Storage
The caching feature allows for cache to be stored both [locally](https://hackmd.io/wlbMQxXaSmuTBk5hLWpKDQ?both#Local-Cache) and [remotely](https://hackmd.io/wlbMQxXaSmuTBk5hLWpKDQ?both#Remote-Cache). However, Gradle's default caching solution is a simple local [directory build cache](https://github.com/gradle/gradle/blob/5e08aaad9dbddfda762904006127f2662af33453/subprojects/core-api/src/main/java/org/gradle/caching/local/DirectoryBuildCache.java#L29). Each cached file has a [build cache key](https://github.com/gradle/gradle/blob/79394f9910a9ea08d223e435c6cad14e887e58b7/subprojects/core-api/src/main/java/org/gradle/caching/BuildCacheKey.java#L23) which may maps to a file.

Information retention policies may be set to [remove unused cached files](https://github.com/gradle/gradle/blob/5e08aaad9dbddfda762904006127f2662af33453/subprojects/core-api/src/main/java/org/gradle/caching/local/DirectoryBuildCache.java#L55) after a given period of time. These policies are used to save storage space and can be configured by the user.

## Configuration Object Definition Model

### Configuration Objects

Configuration objects are run-time object instances whose state determines the behavior of a given Gradle execution. The configuration object definition model demonstrates the mapping between architecturally significant run-time configuration objects and the persistent data from which they loaded. ArtifactRepository configuration objects are not included in the model due to the ambiguous nature of their defining data source.

As mentioned in the [build cache](#Build-Cache) section, configuration objects can be fetched from the cache rather than loaded from their defining data source.

Configuration objects are initialized during the Gradle's configuration lifecycle phase (orthe initialization phase for Settings). Their configuartion dictates the behavior during the execution phase.

### Data Source

### build.gradle

The build.gradle file has a 1-1 mapping with a project configuration object. The content of the file is written in either Groovy or Kotlin. The file is used to [configure](https://hackmd.io/wlbMQxXaSmuTBk5hLWpKDQ?both#Configure-Project) and [add tasks](https://hackmd.io/wlbMQxXaSmuTBk5hLWpKDQ?both#Add-Tasks) to a project configuration object.

Gradle makes use of both the *registry* and an *the command design patterns* to achieve its flexibility quality property. A task may be abstract as a composite command.

### gradle.properties

The gradle properties file is a simple key value store used to configure build variables. The file may appear multiple times especially in a multi-project setup. The properties file is not required by all Gradle executions. The properties file may be used to set both general or [project specific properties](https://hackmd.io/wlbMQxXaSmuTBk5hLWpKDQ?both#Setting-Project-Specific-Properties).

### settings.gradle

A gradle execution loads a single settings.gradle file. During the initialization lifecycle phase the settings.gradle file is loaded into a Settings configurations object. The settings object contains all the necessary information to initiate the configuration lifecycle phase. This includes information such project descriptors and a project hierarchy.

### class file

A plugin is a class which implements the [plugin interface](https://github.com/gradle/gradle/blob/b0032a8a355379e5868b22d660f8be5cf857168e/subprojects/core-api/src/main/java/org/gradle/api/Plugin.java). When adding a plugin to a project, the plugin's class name is provided. For example, the [JavaBase plugin](https://github.com/gradle/gradle/blob/0f10e5f6bd873a7fdcc1861e6b6ffc8aafa774d1/subprojects/plugins/src/main/java/org/gradle/api/plugins/JavaBasePlugin.java#L74) has the class name "JavaBase". Gradle will look for the class name and its corresponding file during plugin configuration.

## Configuration Object Relationship Model
To understand how configuration objects interact together and are composed to create a fully configurable Gradle Build, the configuration object relationship model demonstrates the relationship between the configuration objects introduced above.


Configuration objects interact with and are comprised of other configuration objects. For example, a project may contain many tasks, but a task can only belong to one project.