A multi-project build is a build where you build more than one project during a single execution of Gradle. You have to declare the projects taking part in the multi-project build in the settings file.

Project locations

Multi-project builds are always represented by a tree with a single root. Each element in the tree represents a project. A project has a path which denotes the position of the project in the multi-project build tree. In most cases the project path is consistent with the physical location of the project in the file system. However, this behavior is configurable. The project tree is created in the settings.gradle file. The location of the settings file is also the location of the root project.

Building the tree

In the settings file you can use the include method to build the project tree.

Example 1. Project layout
settings.gradle
include 'project1', 'project2:child', 'project3:child1'
settings.gradle.kts
include("project1", "project2:child", "project3:child1")

The include method takes project paths as arguments. The project path is assumed to be equal to the relative physical file system path. For example, a path 'services:api' is mapped by default to a folder 'services/api' (relative from the project root). You only need to specify the leaves of the tree. This means that the inclusion of the path 'services:hotels:api' will result in creating 3 projects: 'services', 'services:hotels' and 'services:hotels:api'. More examples of how to work with the project path can be found in the DSL documentation of Settings.include(java.lang.String[]).

Modifying elements of the project tree

The multi-project tree created in the settings file is made up of so called project descriptors. You can modify these descriptors in the settings file at any time. To access a descriptor you can do:

Example 2. Lookup of elements of the project tree
settings.gradle
include('project-a')
println rootProject.name
println project(':project-a').name
settings.gradle.kts
println(rootProject.name)
println(project(":project-a").name)

Using this descriptor you can change the name, project directory and build file of a project.

Example 3. Modification of elements of the project tree
settings.gradle
rootProject.name = 'main'
include('project-a')
project(':project-a').projectDir = file('../my-project-a')
project(':project-a').buildFileName = 'project-a.gradle'
settings.gradle.kts
rootProject.name = "main"
project(":project-a").projectDir = file("../my-project-a")
project(":project-a").buildFileName = "project-a.gradle"

Look at the ProjectDescriptor class in the API documentation for more information.