Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 36 ยท Projects and Tasks

Projects and settings.gradle: Naming and Including Projects

Learn how settings.gradle(.kts) defines a Gradle build: rootProject.name, include, project paths, the Project object, and what a build script can see.

A Gradle build is made of one or more projects. A project is not necessarily an "app": it is a unit of build logic with its own build script, its own tasks and its own dependencies. A small program is one project; a big product might be fifty. The file that defines which projects exist is settings.gradle (Groovy) or settings.gradle.kts (Kotlin). In this lesson you will learn what goes into the settings file, how project paths work, and what the project object gives you in a build script.

The Gradle code is read-only; the runnable stand-ins model project paths and the include logic in plain Java.

The settings file

Every build has exactly one settings file, in the root folder. It is the first thing Gradle runs (the initialization phase from the build lifecycle).

Kotlin
// settings.gradle.kts
rootProject.name = "shop"

include("api")
include("core")
include("libs:payments", "libs:inventory")
  • rootProject.name is the name of the whole build. If you omit it, Gradle uses the folder name, which breaks when a CI server clones into a random folder. Always set it.
  • include("api") adds a subproject found in the folder api/.
  • include("libs:payments") adds payments nested in libs/. A colon separates levels.

The resulting tree:

TEXT
shop                 (root project, path ":")
  api                (path ":api")
  core               (path ":core")
  libs
    payments         (path ":libs:payments")
    inventory        (path ":libs:inventory")

Note that libs itself becomes a project too (an empty one, with the path :libs) because Gradle creates the intermediate levels.

Project paths

A project path is how you refer to a project from the command line and from other scripts:

Path Meaning
: the root project
:api the api project
:libs:payments nested project
Terminal
./gradlew :api:test
./gradlew :libs:payments:build

Task paths add the task name: :api:test is the test task of project :api. Use ./gradlew projects to print the tree.

Other things settings can do

The settings file is not just a list of folders. You will meet these in later lessons:

Kotlin
pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}

dependencyResolutionManagement {
    repositoriesMode = RepositoriesMode.FAIL_ON_PROJECT_REPOS
    repositories {
        mavenCentral()
    }
}

include("api", "core")
project(":core").projectDir = file("modules/core")
  • pluginManagement says where plugins come from.
  • dependencyResolutionManagement centralizes repositories for all projects.
  • project(":core").projectDir = ... maps a project to a folder with a different name.

Many builds also apply the org.gradle.toolchains.foojay-resolver-convention plugin here so JDKs can be provisioned automatically.

The Project object

When Gradle configures a build script it creates a Project object for it, and the script body runs with that object as its receiver. That is why you can write version = "1.0" or tasks.register(...) without any prefix; they are properties and methods of Project.

Commonly used members:

Kotlin
println(project.name)          // "api"
println(project.path)          // ":api"
println(project.projectDir)    // folder of this project
println(project.layout.buildDirectory.get())  // .../api/build
println(project.rootProject.name)
println(project.parent?.name)  // "shop" for :api

group = "com.example.shop"
version = "2.1.0"
description = "Public HTTP API"

group, name and version together identify what the project produces, like Maven's coordinates group:name:version. They become the coordinates when you publish.

Project properties vs the build script

A build script for a subproject lives in that subproject's folder:

TEXT
shop/
  settings.gradle.kts
  build.gradle.kts        # root project (optional)
  api/build.gradle.kts    # configures :api
  core/build.gradle.kts   # configures :core

The root build.gradle.kts is optional and often empty or absent in modern builds. Shared configuration is done with convention plugins in buildSrc or an included build (see Plugins and the multi-project chapter later).

A runnable stand-in: include and project paths

This program is not Gradle. It takes include(...) arguments, builds the tree of projects (creating the intermediate levels like Gradle does) and prints the paths.

Java Stand-in: build the project tree from include() calls

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

You will see that libs appears as a project of its own. That is exactly the behaviour you get from include("libs:payments").

A runnable stand-in: name, group and version

Coordinates matter when you publish a library. This stand-in models them with a small record.

Java Stand-in: group, name, version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The same pattern is what you see in Gradle: the JAR file is named <project name>-<version>.jar by default.

Common mistakes

  • Folder and project name mismatch. include("core") expects a folder core/. Use projectDir to map it elsewhere.
  • Forgetting rootProject.name. The name then depends on the clone folder.
  • Putting build logic in the settings file. Keep it to structure, repositories and plugin management.
  • Two settings files in nested folders. A nested settings.gradle creates a separate build; run Gradle from the root you intend.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does include("libs:payments") do in settings.gradle.kts?

    A colon-separated name creates a nested project with that path (and an intermediate project :libs).
  2. 2. Why should you always set rootProject.name?

    Without it, the folder name is used, so the build's identity depends on where it was cloned.
  3. 3. Which task path runs the test task only in the api project?

    A task path is the project path followed by the task name: :api:test.
  4. 4. Which file is evaluated first in every Gradle build?

    The initialization phase evaluates the settings file to decide which projects exist.

Summary

  • A build has one settings file and one or more projects.
  • rootProject.name names the build; include("a", "b:c") adds subprojects and their intermediate levels.
  • Project paths start with :; task paths append the task name (:api:test).
  • A build script runs with a Project object as receiver: name, path, projectDir, group, version.
  • group:name:version become the coordinates when you publish.
  • Settings also configure pluginManagement and dependencyResolutionManagement.

Next: Tasks: Registering and Running