skip to content

Plugin<Settings> & Build-Init Plugins

4 roadmaps6 questions

Settings plugins applied in settings.gradle.kts that can configure plugin management, centralized repositories, and included builds. Interviewers ask because some things simply cannot be done from a project plugin.

on this pageshow

explore

questions

6

What is a Settings plugin in Gradle, and how does it differ from a Project plugin?

level: juniorimportance: must knowfreq 55%

answer

  1. Plugin<Settings> vs Plugin<Project>
  2. applied in settings.gradle(.kts)
  3. runs in initialization phase
  4. include/includeBuild/pluginManagement
  5. configures the whole build

basics

~10 s

A Settings plugin implements Plugin<Settings> and is applied in settings.gradle(.kts). It configures the build as a whole (which projects exist, repositories, plugin resolution), unlike a Project plugin that configures one project's tasks and dependencies.

solid answer

~30 s

A Settings plugin implements `Plugin<Settings>` and is applied via the `plugins {}` block (or `apply`) in `settings.gradle(.kts)`. Its `apply(Settings)` receives the `Settings` object, so it runs during the *initialization phase* — before any project is configured. That lets it do things only possible there: call `include`/`includeBuild`, configure `pluginManagement`, `dependencyResolutionManagement`, `enableFeaturePreview`, and register lifecycle hooks. A `Plugin<Project>`, by contrast, gets a `Project` and runs during the configuration phase to set up tasks, dependencies, and extensions for a single project. The two operate on entirely different model objects and lifecycle phases.

code

kotlin · 7 lines
kotlin
// settings.gradle.kts
plugins {
    id("com.example.conventions.settings") version "1.2.0"
}

rootProject.name = "my-app"
include(":core", ":web")

go deeper

for a junior

Name the interface (Plugin<Settings>), where it's applied (settings.gradle), and that it configures the whole build rather than one project.

for a middle

Tie it to the initialization phase and list the Settings-only capabilities: include/includeBuild, pluginManagement, dependencyResolutionManagement.

for a senior

Explain why the phase distinction forces the model split, and when you'd reach for a settings plugin over conventions in buildSrc.

for a principal

Frame it as the org-wide standardization seam: one settings plugin enforces repos, version catalogs, and cache config across many repos.

## The two plugin types Gradle's `Plugin<T>` interface is generic over the object it configures. The two main specializations are: - **`Plugin<Project>`** — the common case. Applied inside a `build.gradle(.kts)`, it receives a `Project` and runs during the **configuration phase**. It registers tasks, declares dependencies, adds extensions, etc. - **`Plugin<Settings>`** — applied inside `settings.gradle(.kts)`, it receives a `Settings` and runs during the **initialization phase**, *before* any project's build script is evaluated. ## Why the distinction matters Gradle has three phases: **initialization → configuration → execution**. The `Settings` object only exists in initialization. Certain things can *only* be done there: - declaring the project structure: `include(":app")`, `includeBuild("../shared")` - `pluginManagement { repositories {} }` — where plugins are resolved from - `dependencyResolutionManagement { repositories {}; versionCatalogs {} }` — centralized repos & version catalogs - `rootProject.name = ...` - `enableFeaturePreview(...)` A `Plugin<Settings>` is therefore the right tool to package and share that cross-build setup — for example, a company "conventions" settings plugin that wires the same repositories, a shared version catalog, and build-cache configuration into every repo. ## Minimal implementation ```kotlin class MySettingsPlugin : Plugin<Settings> { override fun apply(settings: Settings) { settings.pluginManagement { repositories { gradlePluginPortal() } } settings.dependencyResolutionManagement { repositories { mavenCentral() } } } } ``` ## Where it can be applied from A settings plugin must come from somewhere already resolvable when settings is evaluated: an included build via `pluginManagement { includeBuild(...) }`, `buildSrc`, a precompiled script plugin, or a published plugin available in the `pluginManagement` repositories.

  • Why can't a Settings plugin register tasks?
    Tasks belong to a Project, which doesn't exist yet during initialization. The Settings plugin runs before any project is created, so it has no Project to add tasks to.
  • Where must the settings plugin itself be available from?
    It must be resolvable when settings is evaluated — from buildSrc, an included build under pluginManagement, a precompiled settings convention plugin, or a repository declared in pluginManagement.

If a Project plugin furnishes one room, a Settings plugin draws the floor plan: which rooms exist and where everyone shops for materials.

saying these in an interview costs you the question

  • Claiming you apply a settings plugin in build.gradle — it goes in settings.gradle(.kts).
  • Thinking a settings plugin can configure tasks or dependencies of a specific project directly.

context

resolving links…

open as a page

What can a Settings plugin do with the pluginManagement block, and why is it the only place to do it?

level: middleimportance: must knowfreq 50%

basics

~10 s

pluginManagement controls where plugins are resolved (repositories), version/ID resolution rules (resolutionStrategy), and can includeBuild a build that supplies plugins. It must be in settings because plugin resolution happens during initialization, before build scripts run.

open as a page

How does a Settings plugin use dependencyResolutionManagement to centralize repositories and version catalogs?

level: middleimportance: should knowfreq 45%

basics

~10 s

dependencyResolutionManagement in settings declares repositories for all projects and defines version catalogs. A settings plugin calls settings.dependencyResolutionManagement {} to set repositoriesMode, central repositories, and create catalogs like libs once for the whole build.

open as a page

How do you apply a Settings convention plugin, and what makes its bootstrapping tricky?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Apply it via plugins {} in settings.gradle(.kts). The catch: the plugin must already be resolvable when settings is evaluated, so it comes from buildSrc, an included build under pluginManagement, or a published plugin in pluginManagement repositories.

open as a page

How and why would a Settings plugin call includeBuild, and what does composite-build inclusion accomplish?

level: seniorimportance: should knowfreq 38%

basics

~20 s

includeBuild(path) in a settings plugin wires another Gradle build into this one as a composite build. Gradle substitutes published dependencies with the included build's projects, letting you develop and consume a library or plugin together without publishing.

open as a page

What lifecycle hooks and APIs does the Settings object expose that a Settings plugin can use beyond repository/project setup?

level: seniorimportance: nice to knowfreq 25%

basics

~10 s

Beyond include and resolution blocks, a Settings plugin can use settings.gradle hooks like settingsEvaluated, projectsLoaded, and projectsEvaluated, configure buildCache, set rootProject properties, enableFeaturePreview, and iterate rootProject to apply per-project conventions.

open as a page