What is settings.gradle.kts responsible for, and what breaks if a module directory exists but is never included there?
answer
- Settings script runs first; defines structure
- rootProject.name + include(":mod")
- Project path :a:b maps to dir a/b
- pluginManagement + dependencyResolutionManagement
- Not included = invisible, project(:x) fails
basics
~20 ssettings.gradle.kts names the build and lists which subprojects (modules) belong to it via include(...). A folder with a build.gradle.kts that isn't included is invisible to Gradle—it won't build and other modules can't depend on it.
solid answer
~40 s`settings.gradle.kts` is the **settings script**, evaluated once before any build script to define the *structure* of the build. Its core jobs: set `rootProject.name`; declare the participating subprojects with `include(":app", ":core")`; configure where plugins and dependencies are resolved via `pluginManagement { }` and `dependencyResolutionManagement { repositories { } }`; and optionally declare the version catalog and composite builds (`includeBuild`). A directory that contains a `build.gradle.kts` but is never passed to `include(...)` is simply **not part of the build**: Gradle never configures it, it produces no tasks, and no other module can `implementation(project(":that"))` it—you'll get an 'project not found' / unresolved-project error. By default `include(":foo:bar")` maps to the directory `foo/bar`; you can remap with `project(":x").projectDir = file("...")`. The settings file is also where centralized repository and plugin-resolution policy lives in modern Gradle.
code
kotlin · 12 lines// settings.gradle.kts
rootProject.name = "my-app"
dependencyResolutionManagement {
repositories { mavenCentral() }
}
include(":app", ":core", ":feature:login")
// :feature:login -> feature/login/build.gradle.kts
// remap a project's directory if it doesn't match its path
project(":core").projectDir = file("libs/core")go deeper
Knows the settings file lists modules with include() and sets the project name.
Explains path-to-directory mapping, the not-included failure, and that the settings script runs first.
Discusses pluginManagement/dependencyResolutionManagement centralization and directory remapping/composite builds.
Treats settings as the governance point for repository policy and module topology across a large multi-module build.
## What settings.gradle.kts is It is the **settings script** — the very first script Gradle evaluates, before any `build.gradle.kts`. It operates on a `Settings` object and defines the *shape* of the build rather than how to compile any single module. ## Its responsibilities ```kotlin // settings.gradle.kts rootProject.name = "my-app" pluginManagement { repositories { gradlePluginPortal() mavenCentral() } } @Suppress("UnstableApiUsage") dependencyResolutionManagement { repositories { mavenCentral() } } include(":app", ":core", ":data") ``` - **`rootProject.name`** — the build's name (used in reports, publishing, IDE). - **`include(...)`** — registers each subproject by its **project path** (a colon-separated identifier like `:core` or `:feature:login`). This is what makes a directory a Gradle module. - **`pluginManagement { }`** — where plugin requests are resolved from (repositories, plugin version resolution). - **`dependencyResolutionManagement { repositories { } }`** — centralizes dependency repositories for all modules (the modern alternative to repeating `repositories { }` in every build file). - **`includeBuild("...")`** — wires in a separate Gradle build (composite build). ## Project path → directory mapping `include(":data")` looks for the folder `data/` next to the settings file and expects a `build.gradle.kts` there. Nested paths map to nested folders: `include(":feature:login")` → `feature/login/`. You can override the location: ```kotlin include(":legacy") project(":legacy").projectDir = file("../external/legacy") ``` ## What breaks when a module isn't included If `core/build.gradle.kts` exists but `settings.gradle.kts` never calls `include(":core")`: - Gradle **does not configure** `core` — it has no tasks, never compiles, isn't published. - Another module's `dependencies { implementation(project(":core")) }` fails with **"Project with path ':core' could not be found"**. - The IDE may show the folder but not as a Gradle module. The fix is simply to add `include(":core")` (and ensure the directory matches the path or remap it). ## Single-module builds Even a single-module project usually has a `settings.gradle.kts` with just `rootProject.name`. It can omit `include(...)`. Without any settings file, Gradle treats the directory as a standalone single-project build, but having one (with at least the name and resolution management) is the norm. ## Why it is separate from build.gradle.kts Structure must be known *before* per-project configuration runs, so Gradle evaluates settings first. That ordering is why repository/plugin policy and module membership live here, not in a module's build file.
- Why is dependencyResolutionManagement placed in settings rather than each build file?It centralizes repositories for the whole build, avoiding duplicated repositories { } blocks and inconsistent sources; modern Gradle can even fail the build if a module declares its own repositories.
- A folder feature/login has a build file but include(":feature:login") is missing. Symptom?Gradle won't configure it; any project(":feature:login") reference fails with 'project could not be found', and it produces no tasks.
settings.gradle.kts is the building's directory board in the lobby: a tenant (module) not listed on the board can't receive visitors (dependencies) even if their office exists.
saying these in an interview costs you the question
- Confusing settings.gradle.kts with the root build.gradle.kts
- Thinking a folder with a build file is auto-discovered without include()
- Not knowing project paths use ':' and map to directories
- Unaware that repositories can be centralized in settings