Learn the basics of authoring Gradle by developing the Settings File.

In this section, you will:

  • Understand the Settings object

  • Understand the Settings file

  • Understand Gradle scripting

Step 0. Before you Begin

  1. You initialized your Java app in part 1.

  2. You understand the Gradle Build Lifecycle from part 2.

  3. You added a subproject and a separate Build in part3.

Step 1. Gradle scripts

Build scripts and setting files are code. They are written in Kotlin or Groovy.

You use the Kotlin DSL, Groovy DSL and Gradle APIs to write the scripts.

The methods that can be used within a Gradle script primarily include:

  • Gradle APIs - such as getRootProject() from the Settings API

  • Blocks defined in the DSL - such as the plugins{} block from KotlinSettingsScript

  • Extensions defined by Plugins - such as implementation() and api() provided by the java plugin when applied

Step 2. The Settings object

The settings file is the entry point of every Gradle build.

During the initialization phase, Gradle finds the settings file in your project root directory.

When the settings file, settings.gradle(.kts), is found, Gradle instantiates a Settings object.

One of the purposes of the Settings object is to allow you to declare all the projects to be included in the build.

You can use any of the methods and properties on the Settings interface directly in your settings file.

For example:

includeBuild("some-build")                         // Delegates to Settings.includeBuild()
reportsDir = findProject("/myInternalProject")     // Delegates to Settings.findProject()
includeBuild('some-build')                         // Delegates to Settings.includeBuild()
reportsDir = findProject('/myInternalProject')     // Delegates to Settings.findProject()

Step 3. The Settings file

Let’s break down the settings file in our project root directory:

settings.gradle.kts
plugins {                                                                   (1)
    id("org.gradle.toolchains.foojay-resolver-convention") version "0.7.0"  (2)
}

rootProject.name = "authoring-tutorial"                                     (3)

include("app")                                                              (4)
include("lib")

includeBuild("gradle/license-plugin")                                       (5)
1 plugins({}) from the PluginDependenciesSpec API
2 id() method from the PluginDependenciesSpec API
3 getRootProject() method from the Settings API
4 include() method from the Settings API
5 includeBuild() method from the Settings API
settings.gradle
plugins {                                                                   (1)
    id 'org.gradle.toolchains.foojay-resolver-convention' version '0.7.0'   (2)
}

rootProject.name = 'running-tutorial-groovy'                                (3)

include('app')                                                              (4)
include('lib')

includeBuild('gradle/license-plugin')                                       (5)
1 plugins({}) method from KotlinSettingsScript in the Kotlin DSL
2 id() method from the PluginDependenciesSpec API
3 getRootProject() method from the Settings API
4 include() method from the Settings API
5 includeBuild() method from the Settings API

Next Step: Writing a Build Script >>