gradle-wrapper.properties

Overview

The `gradle-wrapper.properties` file is a configuration file used by the Gradle Wrapper, a mechanism that allows a project to be built with a specific Gradle version, regardless of what is installed on the developer's machine or CI environment. This file specifies the details required to download and use the designated Gradle distribution automatically.

The primary purpose of this file is to ensure build consistency across different machines and environments by locking the Gradle version and defining where and how the Gradle distribution is stored and retrieved.

File Structure and Properties

This file contains key-value pairs that define the configuration for the Gradle Wrapper. Each property affects how the wrapper behaves during build initialization.

Properties

Property Name	Description	Example Value
`distributionBase`	Defines the base directory where the Gradle distribution is stored or cached. Typically a special directory like [GRADLE_USER_HOME](/projects/288/68303) or `PROJECT`.	GRADLE_USER_HOME
`distributionPath`	Specifies the path relative to the base directory where the distribution is unpacked.	`wrapper/dists`
`zipStoreBase`	Defines the base directory where the downloaded Gradle distribution ZIP files are stored.	GRADLE_USER_HOME
`zipStorePath`	Specifies the path relative to the zip store base directory for saving the ZIP files of Gradle distributions.	`wrapper/dists`
`distributionUrl`	The URL from which the Gradle distribution ZIP is downloaded. This URL determines the Gradle version and distribution type (all, bin, etc.).	`https\://services.gradle.org/distributions/gradle-4.4-all.zip`

Detailed Explanation of Each Property

1. `distributionBase`

Purpose: Determines where the Gradle distribution unpacked files are stored.
Typical Values:
- GRADLE_USER_HOME — The Gradle user home directory, usually ~/.gradle on Unix-like systems.
- PROJECT — The project directory itself.
Effect: Using GRADLE_USER_HOME shares the distribution across projects, saving disk space and download time. Using PROJECT isolates the distribution per project.

2. `distributionPath`

Purpose: The relative path under the distributionBase where the distribution is stored.
Example: wrapper/dists means inside ${distributionBase}/wrapper/dists/.

3. `zipStoreBase`

Purpose: Defines where the Gradle ZIP files are cached.
Typical Values: Same as distributionBase.
Effect: Allows control over where the downloaded ZIP archives are saved.

4. `zipStorePath`

Purpose: Relative path under zipStoreBase where ZIP archives are saved.
Example: wrapper/dists means the ZIP files are saved in ${zipStoreBase}/wrapper/dists/.

5. `distributionUrl`

Purpose: Specifies the URL to the Gradle distribution ZIP file.
Format: The URL must be escaped (colon : replaced with \:) for proper parsing.

Example:

https\://services.gradle.org/distributions/gradle-4.4-all.zip

Details:
- The version (here 4.4) locks the Gradle version used by the wrapper.
- The suffix (all.zip) determines the distribution type:
  - all.zip includes sources and documentation.
  - bin.zip includes binaries only.

Usage Example

When a developer runs `./gradlew build` (Unix) or `gradlew.bat build` (Windows), the Gradle Wrapper:

Reads the gradle-wrapper.properties file.
Checks if the specified Gradle version is already downloaded and unpacked in the specified directories.
If not present, downloads the Gradle ZIP from the distributionUrl.
Unpacks and caches the Gradle distribution.
Executes the build using that Gradle version.

This process ensures that every user, CI pipeline, or environment uses exactly the same Gradle version without manual installation.

Important Implementation Details

The file is a simple properties file format with no classes or methods.
The properties govern the behavior of the Gradle Wrapper scripts (gradlew and gradlew.bat) and the wrapper JAR (gradle-wrapper.jar).
The escaping of URL characters (e.g., colon : as \:) is necessary for parsing correctness.
Changes to this file typically occur when upgrading Gradle versions or modifying distribution paths.
It is usually committed to version control to maintain build reproducibility.

Interaction with Other Parts of the System

Gradle Wrapper Scripts (gradlew, gradlew.bat): Invoke the Java wrapper launcher which reads this properties file to determine Gradle version and distribution location.
gradle-wrapper.jar: Contains the logic to download, cache, and launch the specified Gradle distribution according to this configuration.
Project Build Scripts: Use the wrapper indirectly by invoking the wrapper scripts instead of a local Gradle installation.
CI/CD Pipelines: Rely on this file to ensure consistent Gradle versions across automated builds without installing Gradle manually.

Visual Diagram: Gradle Wrapper Workflow Using `gradle-wrapper.properties`

flowchart TD
    A[User runs ./gradlew or gradlew.bat] --> B[gradle-wrapper.properties Read]
    B --> C{Is Gradle distribution cached?}
    C -- Yes --> D[Use cached Gradle distribution]
    C -- No --> E[Download Gradle ZIP from distributionUrl]
    E --> F[Save ZIP to zipStoreBase/zipStorePath]
    F --> G[Unpack ZIP to distributionBase/distributionPath]
    G --> D
    D --> H[Execute Gradle build with specified version]

Summary

The `gradle-wrapper.properties` file is a lightweight, yet critical configuration file that ensures consistent Gradle usage across environments by specifying the distribution's location, caching strategy, and exact version URL. It works hand-in-hand with Gradle Wrapper scripts and the wrapper JAR to automate Gradle setup and execution seamlessly, promoting reliable and reproducible builds in development and CI/CD workflows.