settings.gradle: nó là gì, include module và pluginManagement

settings.gradle là gì?

settings.gradle (hoặc settings.gradle.kts cho Kotlin DSL) là tệp mà Gradle thực thi trong giai đoạn Initialization. Nó xác định hệ thống phân cấp dự án, bao gồm các module và cấu hình kho lưu trữ cho plugin và phụ thuộc. Nếu không có settings.gradle, Gradle không biết module nào cần xây dựng và plugin nào có sẵn. Trong dự án đơn module, settings.gradle có thể không có — Gradle sử dụng giá trị mặc định, nhưng nó bắt buộc đối với dự án đa module.

Tệp settings.gradle nằm ở thư mục gốc của dự án, bên cạnh build.gradle gốc. Cấu trúc thư mục gốc điển hình: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/. settings.gradle được thực thi trước build.gradle — trong giai đoạn Initialization, Gradle xây dựng cây dự án (Project trong API Gradle). Sau khi Initialization hoàn tất, Configuration bắt đầu — thực thi build.gradle của từng module.

Trong lịch sử, settings.gradle xuất hiện trong Gradle 0.7 (2010) và ban đầu chỉ chứa các chỉ thị include. Khi Gradle phát triển, pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) và versionCatalogs (Gradle 7.4) đã được thêm vào. settings.gradle hiện đại là tệp cấu hình mạnh mẽ, tập trung hóa việc quản lý plugin, kho lưu trữ và phiên bản cho toàn bộ dự án. Google bắt buộc các khả năng này trong Android Gradle Plugin từ AGP 8.0.

settings.gradle so với build.gradle

settings.gradle quản lý cấu trúc dự án và cài đặt toàn cục (plugin, kho lưu trữ). build.gradle quản lý bản dựng (phụ thuộc, cấu hình Android, tác vụ). settings.gradle được thực thi trước và có quyền truy cập vào API Settings. build.gradle được thực thi sau và có quyền truy cập vào API Project. Không có cấu hình cấp module nào (khối android, dependencies) có thể nằm trong settings.gradle — đó sẽ là lỗi.

Bao gồm module qua include

Chỉ thị include là cốt lõi của settings.gradle. Nó cho Gradle biết module nào nên tham gia vào bản dựng. Đối số của include là một chuỗi với đường dẫn module: include(":app") bao gồm module ở cấp gốc, include(":core:network") bao gồm module trong thư mục con core/network/. Dấu hai chấm ở đầu cho biết đường dẫn tương đối so với thư mục gốc dự án. Sau include, Gradle tự động tìm build.gradle trong thư mục được chỉ định và thêm module vào cây dự án.

Mỗi include tạo ra một Project trong API Gradle với tên bằng với chuỗi include. Tên dự án được sử dụng trong implementation(project(":module")) trong tệp build.gradle của các module khác. Nếu một module không được bao gồm qua include, việc tham chiếu đến nó từ module khác sẽ gây ra lỗi “Project not found”. Android Studio IDE cũng sử dụng settings.gradle để hiển thị các module trong bảng Project — module không có include sẽ không hiển thị trong cây tệp.

include hỗ trợ included builds và composite builds qua includeBuild("../library-project"). Điều này cho phép bao gồm toàn bộ dự án Gradle như các module bên ngoài. Included builds hữu ích để phát triển thư viện song song với ứng dụng: các thay đổi trong thư viện hiển thị ngay lập tức trong ứng dụng mà không cần xuất bản lên kho Maven. Trong bản dựng sản xuất, includeBuild được thay thế bằng phụ thuộc Maven thông thường.

// settings.gradle.kts — cấu trúc điển hình
rootProject.name = "MyApp"

// Module ứng dụng
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// Bao gồm thư viện bên ngoài (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

Khối quản lý plugin

Chiến lược giải quyết

pluginManagement là một khối trong settings.gradle xác định nơi tải các plugin Gradle. Nó xuất hiện trong Gradle 6.8 để quản lý tập trung các plugin trước khi áp dụng chúng. Bên trong pluginManagement có: repositories (danh sách kho lưu trữ để tìm plugin), resolutionStrategy (quy tắc giải quyết phiên bản) và plugins (khai báo phiên bản plugin rõ ràng). Nếu pluginManagement không được định nghĩa, Gradle sử dụng kho lưu trữ từ build.gradle — nhưng plugin chỉ được tìm kiếm sau khi được khai báo, dẫn đến lỗi nếu không tìm thấy plugin.

Trong các dự án Android, pluginManagement là bắt buộc nếu sử dụng Version Catalogs hoặc Convention Plugins. Nếu không có pluginManagement, Gradle không thể tìm thấy plugin com.android.application khi áp dụng trong build.gradle.kts. Cấu hình điển hình: repositories chứa google() (plugin Android), mavenCentral() (plugin bên thứ ba) và gradlePluginPortal() (plugin Gradle chính thức).

pluginManagement cũng hỗ trợ plugins — khai báo plugin với phiên bản, sau đó được áp dụng trong build.gradle mà không cần chỉ định phiên bản. Điều này tập trung hóa phiên bản plugin: nếu 10 module áp dụng kotlin-android, phiên bản được chỉ định một lần trong pluginManagement. Quan trọng: pluginManagement.plugins chỉ là khai báo. Plugin tự nó được áp dụng trong build.gradle qua plugins { id("org.jetbrains.kotlin.android") }.

pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
        maven { url = "https://jitpack.io" }
    }

    // Phiên bản plugin — tập trung
    plugins {
        id("com.android.application") version "8.7.0"
        id("com.android.library") version "8.7.0"
        id("org.jetbrains.kotlin.android") version "2.0.21"
        id("com.google.devtools.ksp") version "2.0.21-1.0.25"
    }

    resolutionStrategy {
        // Phiên bản plugin bắt buộc cho tất cả module
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // Áp dụng plugin — apply false (không áp dụng cho gốc)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

Quản lý giải quyết phụ thuộc

Các chế độ repositoriesMode

dependencyResolutionManagement là một khối trong settings.gradle quản lý tập trung các kho lưu trữ cho tất cả module. Nó xuất hiện trong Gradle 7.0 như một giải pháp thay thế cho việc khai báo repositories trong mỗi build.gradle. Bên trong khối, repositoriesMode (chế độ: PREFER_PROJECT, PREFER_SETTINGS hoặc FAIL_ON_PROJECT_REPOS) và repositories (danh sách kho lưu trữ) được đặt. Nếu repositoriesMode = PREFER_SETTINGS, repositories cấp module bị bỏ qua — chỉ danh sách tập trung được sử dụng.

repositoriesMode có thể nhận ba giá trị. PREFER_SETTINGS — kho lưu trữ từ build.gradle bị bỏ qua, chỉ sử dụng từ settings.gradle. PREFER_PROJECT — kho lưu trữ build.gradle có ưu tiên hơn settings.gradle. FAIL_ON_PROJECT_REPOS — nếu module khai báo kho lưu trữ riêng, Gradle sẽ báo lỗi. Đối với dự án mới, PREFER_SETTINGS được khuyến nghị — nó đảm bảo tất cả module sử dụng cùng một kho lưu trữ và loại bỏ sự trùng lặp.

repositoriesMode = FAIL_ON_PROJECT_REPOS đặc biệt hữu ích trong nhóm: nếu nhà phát triển thêm kho lưu trữ chỉ vào một module và các module khác không thấy nó, sẽ gây ra vấn đề “works on my machine”. FAIL_ON_PROJECT_REPOS buộc tất cả kho lưu trữ phải được khai báo tập trung trong settings.gradle, ngăn chặn các tình huống như vậy. Google khuyến nghị FAIL_ON_PROJECT_REPOS cho tất cả dự án Android từ AGP 8.0.

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — tất cả kho lưu trữ chỉ ở đây
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

    repositories {
        google()
        mavenCentral()
        maven { url = "https://jitpack.io" }

        // Kho lưu trữ Maven riêng
        maven {
            url = "https://maven.pkg.github.com/company/internal-lib"
            credentials {
                username = providers.gradleProperty("gpr.user")
                    .getOrNull() ?: System.getenv("GPR_USER") ?: ""
                password = providers.gradleProperty("gpr.key")
                    .getOrNull() ?: System.getenv("GPR_KEY") ?: ""
            }
        }
    }
}

// Trong build.gradle module, repositories không còn cần thiết nữa!
// Tất cả kho lưu trữ được tập trung trong settings.gradle

Danh mục phiên bản trong settings.gradle

Version Catalogs là cách tập trung để quản lý phiên bản phụ thuộc qua tệp TOML. Từ Gradle 7.4, danh mục phiên bản là cơ chế được khuyến nghị cho tất cả dự án Android. Tệp gradle/libs.versions.toml chứa ba phần: [versions] (phiên bản), [libraries] (phụ thuộc), [plugins] (plugin). Trong settings.gradle, danh mục phiên bản được kết nối qua @Suppress("UnstableApiUsage") và enableFeaturePreview("VERSION_CATALOGS") (trong các phiên bản Gradle cũ).

Sau khi kết nối danh mục phiên bản, các phụ thuộc module trong build.gradle được chỉ định qua libs: implementation(libs.retrofit). IDE cung cấp tính năng tự động hoàn thành cho libs. Danh mục tự động tạo ra các accessor an toàn kiểu: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose. Bundles là các nhóm phụ thuộc có thể được bao gồm trong một dòng. Danh mục phiên bản cũng hỗ trợ kế thừa — nhiều tệp TOML có thể được kết nối.

Lợi ích của danh mục phiên bản: một nơi duy nhất cho phiên bản (không cần tìm kiếm trong tất cả tệp build.gradle); truy cập an toàn kiểu (lỗi chính tả trong tên libs được phát hiện tại thời điểm biên dịch, không phải thời gian chạy); cập nhật tự động (Dependabot và Renovate hỗ trợ TOML); tương thích với Convention Plugins. Google Firebase và AndroidX phân phối danh mục TOML riêng của họ. Để di chuyển sang danh mục phiên bản, có các plugin tự động chuyển phiên bản từ build.gradle sang TOML.

# gradle/libs.versions.toml
[versions]
agp = "8.7.0"
kotlin = "2.0.21"
composeBom = "2024.12.01"
retrofit = "2.11.0"
coroutines = "1.9.0"

[libraries]
retrofit = { module = "com.squareup.retrofit2:retrofit", version.ref = "retrofit" }
retrofit-gson = { module = "com.squareup.retrofit2:converter-gson", version.ref = "retrofit" }
kotlin-coroutines = { module = "org.jetbrains.kotlinx:kotlinx-coroutines-core", version.ref = "coroutines" }
compose-bom = { module = "androidx.compose:compose-bom", version.ref = "composeBom" }
compose-ui = { module = "androidx.compose.ui:ui" }

[bundles]
compose = ["compose-ui", "compose-material3"]

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

Cài đặt nâng cao: includeBuild và tính năng thử nghiệm

includeBuild là chỉ thị để tạo bản dựng tổng hợp: bao gồm một dự án Gradle bên ngoài như một phần của bản dựng hiện tại. Khác với include (bao gồm một module), includeBuild bao gồm toàn bộ dự án với settings.gradle, module và plugin riêng của nó. Bản dựng tổng hợp được sử dụng để: phát triển thư viện (phân tích, mạng) song song với ứng dụng; bao gồm Convention Plugins từ kho lưu trữ riêng; tích hợp các module build-logic.

Tính năng thử nghiệm (Incubating Features) là các tùy chọn thử nghiệm của Gradle được kích hoạt qua enableFeaturePreview("FEATURE_NAME"). Trong AGP 8.7+, có sẵn: TYPESAFE_PROJECT_ACCESSORS (truy cập an toàn kiểu vào dự án trong dự án đa module: thay vì project(":core:network"), bạn có thể viết projects.core.network), STABLE_CONFIGURATION_CACHE (bộ nhớ đệm cấu hình ổn định), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (biến đổi artifact). Tính năng thử nghiệm có thể được kích hoạt trong sản xuất, nhưng API có thể thay đổi trong các phiên bản tương lai.

Gradle Enterprise và Build Scan cũng được cấu hình qua settings.gradle: plugins { id("com.gradle.enterprise") } với khối gradleEnterprise. Build Scan là dịch vụ đám mây hiển thị thông tin chi tiết về mỗi bản dựng: thời gian thực thi mỗi tác vụ, bộ nhớ đệm, lỗi. Kích hoạt Build Scan giúp chẩn đoán các vấn đề về tốc độ xây dựng. Build Scan miễn phí cho các dự án mã nguồn mở.

// Tính năng thử nghiệm
enableFeaturePreview("TYPESAFE_PROJECT_ACCESSORS")
enableFeaturePreview("STABLE_CONFIGURATION_CACHE")

// Gradle Enterprise / Build Scan
plugins {
    id("com.gradle.enterprise") version "3.18"
}

gradleEnterprise {
    buildScan {
        termsOfServiceUrl = "https://gradle.com/terms-of-service"
        termsOfServiceAgree = "yes"
        publishAlwaysIf(true)
    }
}

// Sử dụng type-safe project accessors trong build.gradle
// Thay vì: implementation(project(":core:network"))
// Có thể: implementation(projects.core.network)