Gradle: build.gradle vs. settings.gradle vs. gradle.properties

1. Overview

In this article, we’ll look at the different configuration files of a Gradle Java project. Also, we’ll see the details of an actual build.

You can check this article for a general introduction to Gradle.

2. build.gradle

Let’s assume that we’re just creating a new Java project by running gradle init –type java-application. This’ll leave us with a new project with the following directory and file structure:

build.gradle
gradle    
    wrapper
        gradle-wrapper.jar
        gradle-wrapper.properties
gradlew
gradlew.bat
settings.gradle
src
    main
        java  
            App.java
    test      
        java
            AppTest.java

We can consider the build.gradle file as the heart or the brain of the project. The resulting file for our example looks like this:

plugins {
    id 'java'
    id 'application'
}

mainClassName = 'App'

dependencies {
    compile 'com.google.guava:guava:23.0'

    testCompile 'junit:junit:4.12'
}

repositories {
    jcenter()
}

It consists of Groovy code, or more precisely, a Groovy-based DSL (domain specific language) for describing the builds. We can define our dependencies here and also add things like Maven repositories used for dependency resolution.

The fundamental building blocks of Gradle are projects and tasks. In this case, since the java plugin is applied, all necessary tasks for building a Java project are defined implicitly. Some of those tasks are assemble, check, build, jar, javadoc, clean and many more.

These tasks are also set up in such a way, that they describe a useful dependency graph for a Java project, meaning it’s generally enough to execute the build task and Gradle (and the Java plugin) will make sure, that all necessary tasks are performed.

If we need additional specialized tasks, like, e.g., building a Docker image, it would also go into the build.gradle file. The easiest possible definition of tasks looks like this:

task hello {
    doLast {
        println 'Hello Baeldung!'
    }
}

We can run a task by specifying it as an argument to the Gradle CLI like this:

$ gradle -q hello
Hello Baeldung!

It’ll do nothing useful, but print out “Hello Baeldung!” of course.

In case of a multi-project build, we’d probably have multiple different build.gradle files, one for each project.

The build.gradle file is executed against a Project instance, with one Project instance created per subproject. The tasks above, which can be defined in the build.gradle file, reside inside the Project instance as part of a collection of Task objects. The Tasks itself consists of multiple actions as an ordered list.

In our previous example, we’ve added a Groovy closure for printing out “Hello Baeldung!” to the end of this list, by calling the doLast(Closure action) on our hello Task object. During the execution of Task, Gradle is executing each of its Actions in order, by calling the Action.execute(T) method.

3. settings.gradle

Gradle also generates a settings.gradle file:

rootProject.name = 'gradle-example'

The settings.gradle file is a Groovy script as well.

In contrast to the build.gradle file, only one settings.gradle file is executed per Gradle build. We can use it to define the projects of a multi-project build.

Besides, we can also possible to register code as part of different life cycle hooks of a build.

The framework requires the existence of the settings.gradle in a multi-project build, while it’s optional for a single-project build.

This file is used after creating the Settings instance of the build, by executing the file against it and thereby configuring it. This means that we’re defining subprojects in our settings.gradle file like this:

include 'foo', 'bar'

and Gradle is calling the void include(String… projectPaths) method on the Settings instance when creating the build.

4. gradle.properties

Gradle doesn’t create a gradle.properties file by default. It can reside in different locations, for example in the project root directory, inside of GRADLE_USER_HOME or in the location specified by the -Dgradle.user.home command line flag.

This file consists of key-value pairs. We can use it to configure the behavior of the framework itself and it’s an alternative to using command line flags for the configuration.

Examples of possible keys are:

• org.gradle.caching=(true,false)
• org.gradle.daemon=(true,false)
• org.gradle.parallel=(true,false)
• org.gradle.logging.level=(quiet,warn,lifecycle,info,debug)

Also, you can use this file to add properties directly to the Project object, e.g., the property with its namespace: org.gradle.project.property_to_set

Another use case is specifying JVM parameters like this:

org.gradle.jvmargs=-Xmx2g -XX:MaxPermSize=256m -XX:+HeapDumpOnOutOfMemoryError -Dfile.encoding=UTF-8

Please note that it needs to launch a JVM process to parse the gradle.properties file. This means these JVM parameters only effect separately launched JVM processes.

5. The Build in a Nutshell

We can summarize the general lifecycle of a Gradle build as follows, assuming we don’t run it as a daemon:

• It launches as a new JVM process
• It parses the gradle.properties file and configures Gradle accordingly
• Next, it creates a Settings instance for the build
• Then, it evaluates the settings.gradle file against the Settings object
• It creates a hierarchy of Projects, based on the configured Settings object
• Finally, it executes each build.gradle file against its project

6. Conclusion

We’ve seen, how different Gradle configuration files fulfill various development purposes. We can use them to configure a Gradle build as well as Gradle itself, based on the needs of our project.