Gradle User Guide

What is Gradle?

Gradle is an open-source build automation tool flexible enough to build almost any type of software. Gradle makes few assumptions about what you’re trying to build or how to build it. This makes Gradle particularly flexible.

Design

Gradle bases its design on the following fundamentals:

High performance

Gradle avoids unnecessary work by only running tasks that need to do work because inputs or outputs have changed. Gradle uses various caches to reuse outputs from previous builds. With a shared build cache, you can even reuse outputs from other machines.

JVM foundation

Gradle runs on the JVM. This is a bonus for users familiar with Java since build logic can use the standard Java APIs. It also makes it easy to run Gradle on different platforms.

Conventions

Gradle makes common types of projects easy to build through conventions. Plugins set sensible defaults to keep build scripts minimal. But these conventions don’t limit you: you can configure settings, add your own tasks, and make many other customizations in your builds.

Extensibility

Most builds have special requirements that require custom build logic. You can readily extend Gradle to provide your own build logic with custom tasks and plugins. See Android builds for an example: they add many new build concepts such as flavors and build types.

IDE support

Several major IDEs provide interaction with Gradle builds, including Android Studio, IntelliJ IDEA, Eclipse, VSCode, and NetBeans. Gradle can also generate the solution files required to load a project into Visual Studio.

Insight

Build Scan™ provides extensive information about a build that you can use to identify issues. You can use Build Scans to identify problems with a build’s performance and even share them for debugging help.

Terminology

It’s helpful to know the following terminology before you dive into the details of Gradle.

Projects

Projects are the things that Gradle builds. Projects contain a build script, which is a file located in the project’s root directory usually named build.gradle or build.gradle.kts. Builds scripts define tasks, dependencies, plugins, and other configuration for that project. A single build can contain one or more projects and each project can contain their own subprojects.

Tasks

Tasks contain the logic for executing some work—compiling code, running tests or deploying software. In most use cases, you’ll use existing tasks. Gradle provides tasks that implement many common build system needs, like the built-in Java Test task that can run tests. Plugins provide even more types of tasks.

Tasks themselves consist of:

• Actions: pieces of work that do something, like copy files or compile source
• Inputs: values, files and directories that the actions use or operate on
• Outputs: files and directories that the actions modify or generate

Plugins

Plugins allow you to introduce new concepts into a build beyond tasks, files and dependency configurations. For example, most language plugins add the concept of source sets to a build.

Plugins provide a means of reusing logic and configuration across multiple projects. With plugins, you can write a task once and use it in multiple builds. Or you can store common configuration, like logging, dependencies, and version management, in one place. This reduces duplication in build scripts. Appropriately modeling build processes with plugins can greatly improve ease of use and efficiency.

Build Phases

Gradle evaluates and executes build scripts in three build phases of the Build Lifecycle:

Initialization

Sets up the environment for the build and determine which projects will take part in it.

Configuration

Constructs and configures the task graph for the build. Determines which tasks need to run and in which order, based on the task the user wants to run.

Execution

Runs the tasks selected at the end of the configuration phase.

Builds

A build is an execution of a collection of tasks in a Gradle project. You run a build via the command line interface (CLI) or an IDE by specifying task selectors. Gradle configures the build and selects the tasks to run. Gradle runs the smallest complete set of tasks based on the requested tasks and their dependencies.