Gradle Wrapper

Author:
The Gradle Wrapper is a crucial feature for any project using Gradle. It ensures that anyone cloning your project can build it immediately without having to manually install a specific version of Gradle. This guide covers what the Gradle Wrapper is, why you should use it, and how to set it up and maintain it.

What is the Gradle Wrapper?

The Gradle Wrapper (or "Wrapper") is a script that comes with your project and downloads the correct Gradle version for the project. This eliminates the need for developers to install Gradle manually and ensures that the build is executed with the correct version of Gradle every time.

Why Use the Gradle Wrapper?

  • Consistency: Ensures all developers use the same Gradle version.
  • Convenience: No need to install Gradle manually.
  • Automation: Integrates smoothly with CI/CD pipelines.
  • Compatibility: Easily handle Gradle version upgrades.

Setting Up the Gradle Wrapper

Step 1: Generate the Wrapper

To generate the Gradle Wrapper, navigate to the root of your project and run the following command:

gradle wrapper --gradle-version <latest-version>

Replace <latest-version> with the version of Gradle you want to use, for example:

gradle wrapper --gradle-version 8.1.1

This command will create several files in your project:

  • gradlew: Unix shell script to run Gradle.
  • gradlew.bat: Windows batch script to run Gradle.
  • gradle/wrapper/gradle-wrapper.jar: The Wrapper JAR.
  • gradle/wrapper/gradle-wrapper.properties: Properties file specifying the Gradle version and download URL.

Step 2: Add Wrapper Files to Version Control

Ensure that the generated Wrapper files are added to your version control system (e.g., Git):

git add gradlew gradlew.bat gradle/wrapper/
git commit -m "Add Gradle Wrapper"

Step 3: Use the Wrapper

Instead of running gradle commands, use the Wrapper scripts:

On Unix-based systems (Linux, macOS):

./gradlew build

On Windows:

gradlew.bat build

These commands ensure that the correct version of Gradle is used.

Customizing the Wrapper

Specifying Distribution Type

You can specify whether to use a full Gradle distribution or a smaller “bin” distribution (which does not include the documentation and sources):

Edit the gradle/wrapper/gradle-wrapper.properties file:

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
distributionUrl=https\://services.gradle.org/distributions/gradle-8.1.1-bin.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

Upgrading the Wrapper

To upgrade to a new Gradle version, simply run the Wrapper command again with the new version:

./gradlew wrapper --gradle-version <new-version>

This will update the gradle-wrapper.properties file to point to the new version.

Example: Setting Up and Using the Gradle Wrapper

  1. Generate the Wrapper

    gradle wrapper --gradle-version 8.1.1

  2. Verify Generated Files

    Check the following files are created:

    • gradlew
    • gradlew.bat
    • gradle/wrapper/gradle-wrapper.jar
    • gradle/wrapper/gradle-wrapper.properties

  3. Add Files to Version Control

    git add gradlew gradlew.bat gradle/wrapper/
git commit -m "Add Gradle Wrapper"

  4. Run Build Using the Wrapper

    On Unix-based systems:

    ./gradlew build

    On Windows:

    gradlew.bat build

Conclusion

The Gradle Wrapper is an essential tool for ensuring consistency and convenience in your build process. It can also avoid potential issues with Gradle version mismatches and streamline your development workflow. Follow the steps outlined in this guide to set up and use the Gradle Wrapper effectively in your projects.

Further Reading

Comments

Post a Comment

Leave Comment