Gradle build.gradle Build File

Gradle describes build processing in a file named build.gradle. This page explains the basics of that build file.

build.gradle Contents and Plugins

In Gradle, tasks such as compileJava and run are executed based on the contents written in the build file.

build.gradle contents

The generated build.gradle file looks like this.

/*
 * This build file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample Java project to get you started.
 * For more details take a look at the Java Quickstart chapter in the Gradle
 * user guide available at https://docs.gradle.org/4.1/userguide/tutorial_java_projects.html
 */

// Apply the java plugin to add support for Java
apply plugin: 'java'

// Apply the application plugin to add support for building an application
apply plugin: 'application'

// In this section you declare where to find the dependencies of your project
repositories {
    // Use jcenter for resolving your dependencies.
    // You can declare any Maven/Ivy/file repository here.
    jcenter()
}

dependencies {
    // This dependency is found on compile classpath of this component and consumers.
    compile 'com.google.guava:guava:22.0'

    // Use JUnit test framework
    testCompile 'junit:junit:4.12'
}

// Define the main class for the application
mainClassName = 'App'

build.gradle is written in Groovy. Like Java, Groovy can use // and /* */ comments. If the comments are removed, the file is not especially difficult to read.

Adding the Java plugin

apply plugin: 'java'

apply plugin: enables a Gradle plugin. The java plugin provides features for Java programs. The compileJava task used earlier is provided by this plugin.

Adding the Application plugin

apply plugin: 'application'

The application plugin provides features for building and running applications. The run task used earlier is provided by this plugin.

Main class name

mainClassName = 'App'

mainClassName is used by the application plugin and specifies the main class. The application can be run with run because this main class is configured.

Java plugin

To use the Java plugin in a project, add the following to build.gradle.

apply plugin: 'java'

Basic project layout

Test source code is not included when distributing the application.

Repositories

The build file also contains configuration for dependency libraries. Gradle can automatically download and integrate libraries required by the program. For that reason, repositories are important.

A repository is a location where program libraries are stored. The build file specifies which repositories Gradle should use.

repositories {
    // repository settings
}

The repository configuration is written inside this block. Gradle commonly uses the following repository services.

Maven Central

mavenCentral()

This configures Gradle to use Apache Maven Central. Gradle can use Maven Central directly.

JCenter

jcenter()

JCenter is another public repository that was often used by Maven, Gradle, and other build tools. To use it, write jcenter() inside repositories.

mavenCentral() and jcenter() are Gradle methods. Calling them inside repositories enables the corresponding repository.

Dependency Libraries

The dependencies block specifies libraries to use from repositories.

dependencies {
    // library settings
}

The generated file contains two dependency declarations.

Compile-time dependency

compile 'com.google.guava:guava:22.0'

This specifies a library used at compile time. Writing compile indicates that the library is referenced during compilation.

Test compile-time dependency

testCompile 'junit:junit:4.12'

This specifies a library used when compiling unit tests. Writing testCompile indicates that the library is referenced during test compilation.

Other configurations can also specify dependency libraries for different processing phases. One important concept to remember is the classpath.

classpath '... library ...'

This adds the specified library to the classpath. It is used for libraries required from compilation through execution.

Specifying Libraries

The sample uses two libraries.

'com.google.guava:guava:22.0'
'junit:junit:4.12'

The format is generally as follows.

'group:name:version'

The group represents the company, organization, or group that owns the library. The name is the library name.

For example:

'com.google.guava:guava:22.0'
group: com.google.guava
name: guava
version: 22.0

'junit:junit:4.12'
group: junit
name: junit
version: 4.12

This makes it clear which libraries are being used.

Specifying each part separately

Writing all library information as one string is simple, but it can be hard to read and mistakes can be difficult to find. Gradle also supports separating group, name, and version.

group:'group', name:'name', version:'version'

For the sample libraries, this can be written as follows.

compile 'com.google.guava:guava:22.0'
// becomes
compile group:'com.google.guava', name:'guava', version:'22.0'

testCompile 'junit:junit:4.12'
// becomes
testCompile group:'junit', name:'junit', version:'4.12'

This style makes each value easier to identify. It is often clearer than placing all values in a single string.