settings.gradle: คืออะไร การรวมโมดูลและ pluginManagement

settings.gradle คืออะไร?

settings.gradle (หรือ settings.gradle.kts สำหรับ Kotlin DSL) คือไฟล์ที่ Gradle ดำเนินการระหว่างเฟส Initialization โดยจะกำหนดลำดับชั้นของโปรเจกต์ รวมโมดูล และกำหนดค่าที่เก็บข้อมูลสำหรับปลั๊กอินและการพึ่งพา หากไม่มี settings.gradle Gradle จะไม่รู้ว่าโมดูลใดที่ต้องสร้างและปลั๊กอินใดที่พร้อมใช้งาน ในโปรเจกต์โมดูลเดียว settings.gradle อาจไม่มีอยู่ได้ — Gradle จะใช้ค่าเริ่มต้น แต่จำเป็นสำหรับโปรเจกต์หลายโมดูล

ไฟล์ settings.gradle อยู่ในรากของโปรเจกต์ ถัดจาก build.gradle ราก โครงสร้างรากโปรเจกต์ทั่วไป: settings.gradle.kts, build.gradle.kts, gradle.properties, local.properties, gradle/wrapper/ settings.gradle จะถูกดำเนินการก่อน build.gradle — ในระหว่างเฟส Initialization Gradle จะสร้างโครงสร้างต้นไม้ของโปรเจกต์ (Project ใน Gradle API) หลังจาก Initialization เสร็จสิ้น Configuration จะเริ่มต้นขึ้น — การดำเนินการ build.gradle ของแต่ละโมดูล

ในอดีต settings.gradle ปรากฏใน Gradle 0.7 (2010) และเริ่มแรกมีเพียงคำสั่ง include เท่านั้น เมื่อ Gradle พัฒนาขึ้น pluginManagement (Gradle 6.8), dependencyResolutionManagement (Gradle 7.0) และ versionCatalogs (Gradle 7.4) ก็ถูกเพิ่มเข้ามา settings.gradle สมัยใหม่เป็นไฟล์คอนฟิกูเรชันที่ทรงพลังซึ่งรวมศูนย์การจัดการปลั๊กอิน ที่เก็บข้อมูล และเวอร์ชันสำหรับทั้งโปรเจกต์ Google กำหนดความสามารถเหล่านี้ใน Android Gradle Plugin ตั้งแต่ AGP 8.0

settings.gradle เปรียบเทียบกับ build.gradle

settings.gradle จัดการโครงสร้างโปรเจกต์และการตั้งค่าระดับโลก (ปลั๊กอิน ที่เก็บข้อมูล) build.gradle จัดการบิลด์ (การพึ่งพา การกำหนดค่า Android งาน) settings.gradle จะถูกดำเนินการก่อนและสามารถเข้าถึง Settings API build.gradle จะถูกดำเนินการทีหลังและสามารถเข้าถึง Project API ไม่มีการกำหนดค่าระดับโมดูลใดๆ (บล็อก android, dependencies) ที่สามารถอยู่ใน settings.gradle ได้ — นั่นจะเป็นข้อผิดพลาด

การรวมโมดูลผ่าน include

คำสั่ง include เป็นหัวใจของ settings.gradle โดยบอก Gradle ว่าโมดูลใดควรมีส่วนร่วมในบิลด์ อาร์กิวเมนต์ของ include คือสตริงที่มีพาธของโมดูล: include(":app") รวมโมดูลที่ระดับราก include(":core:network") รวมโมดูลในไดเรกทอรีย่อย core/network/ เครื่องหมายโคลอนที่จุดเริ่มต้นบ่งชี้ว่าพาธสัมพันธ์กับรากโปรเจกต์ หลังจาก include Gradle จะค้นหา build.gradle ในไดเรกทอรีที่ระบุโดยอัตโนมัติและเพิ่มโมดูลลงในโครงสร้างต้นไม้ของโปรเจกต์

แต่ละ include จะสร้าง Project ใน Gradle API โดยมีชื่อเท่ากับสตริง include ชื่อโปรเจกต์ถูกใช้ใน implementation(project(":module")) ในไฟล์ build.gradle ของโมดูลอื่น หากโมดูลไม่ถูกรวมผ่าน include การอ้างอิงถึงโมดูลนั้นจากโมดูลอื่นจะทำให้เกิดข้อผิดพลาด “Project not found” Android Studio IDE ยังใช้ settings.gradle เพื่อแสดงโมดูลในแผง Project — โมดูลที่ไม่มี include จะไม่ปรากฏในโครงสร้างต้นไม้ไฟล์

include รองรับ included builds และ composite builds ผ่าน includeBuild("../library-project") ซึ่งช่วยให้รวมโปรเจกต์ Gradle ทั้งหมดเป็นโมดูลภายนอก Included builds มีประโยชน์สำหรับการพัฒนาไลบรารีควบคู่ไปกับแอปพลิเคชัน: การเปลี่ยนแปลงในไลบรารีจะปรากฏในแอปพลิเคชันทันทีโดยไม่ต้องเผยแพร่ไปยังที่เก็บ Maven ในบิลด์สำหรับการผลิต includeBuild จะถูกแทนที่ด้วยการพึ่งพา Maven ปกติ

// settings.gradle.kts — โครงสร้างทั่วไป
rootProject.name = "MyApp"

// โมดูลแอปพลิเคชัน
include(":app")
include(":core:network")
include(":core:database")
include(":core:ui")
include(":feature:home")
include(":feature:profile")
include(":feature:settings")

// การรวมไลบรารีภายนอก (composite build)
includeBuild("../my-analytics-lib") {
    dependencySubstitution {
        substitute(module("com.example:analytics"))
            .using(project(":analytics"))
    }
}

บล็อกการจัดการปลั๊กอิน

กลยุทธ์การแก้ไข

pluginManagement คือบล็อกใน settings.gradle ที่กำหนดว่าจะโหลดปลั๊กอิน Gradle จากที่ใด ปรากฏใน Gradle 6.8 สำหรับการจัดการปลั๊กอินแบบรวมศูนย์ก่อนที่จะนำไปใช้ ภายใน pluginManagement ประกอบด้วย: repositories (รายการที่เก็บข้อมูลสำหรับค้นหาปลั๊กอิน), resolutionStrategy (กฎการแก้ไขเวอร์ชัน) และ plugins (การประกาศเวอร์ชันปลั๊กอินอย่างชัดเจน) หากไม่ได้กำหนด pluginManagement Gradle จะใช้ที่เก็บข้อมูลจาก build.gradle — แต่ปลั๊กอินจะถูกค้นหาหลังจากประกาศเท่านั้น ซึ่งนำไปสู่ข้อผิดพลาดหากไม่พบปลั๊กอิน

ในโปรเจกต์ Android จำเป็นต้องมี pluginManagement หากใช้ Version Catalogs หรือ Convention Plugins หากไม่มี pluginManagement Gradle จะไม่สามารถค้นหาปลั๊กอิน com.android.application เมื่อนำไปใช้ใน build.gradle.kts การกำหนดค่าทั่วไป: repositories ประกอบด้วย google() (ปลั๊กอิน Android), mavenCentral() (ปลั๊กอินของบริษัทอื่น) และ gradlePluginPortal() (ปลั๊กอิน Gradle อย่างเป็นทางการ)

pluginManagement ยังรองรับ plugins — การประกาศปลั๊กอินพร้อมเวอร์ชันซึ่งจะถูกนำไปใช้ใน build.gradle โดยไม่ต้องระบุเวอร์ชัน ซึ่งจะรวมศูนย์เวอร์ชันของปลั๊กอิน: หาก 10 โมดูลใช้ kotlin-android เวอร์ชันจะถูกระบุครั้งเดียวใน pluginManagement สำคัญ: pluginManagement.plugins เป็นเพียงการประกาศ ตัวปลั๊กอินจะถูกนำไปใช้ใน build.gradle ผ่าน plugins { id("org.jetbrains.kotlin.android") }

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

    // เวอร์ชันปลั๊กอิน — แบบรวมศูนย์
    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 {
        // เวอร์ชันปลั๊กอินบังคับสำหรับทุกโมดูล
        eachPlugin {
            if (requested.id.id == "com.google.gms.google-services") {
                useVersion("4.4.2")
            }
        }
    }
}

plugins {
    // การนำปลั๊กอินไปใช้ — apply false (ไม่นำไปใช้กับราก)
    id("com.android.application") apply false
    id("org.jetbrains.kotlin.android") apply false
}

การจัดการการแก้ไขการพึ่งพา

โหมดของ repositoriesMode

dependencyResolutionManagement คือบล็อกใน settings.gradle ที่จัดการที่เก็บข้อมูลแบบรวมศูนย์สำหรับทุกโมดูล ปรากฏใน Gradle 7.0 เป็นทางเลือกแทนการประกาศ repositories ในแต่ละ build.gradle ภายในบล็อกจะตั้งค่า repositoriesMode (โหมด: PREFER_PROJECT, PREFER_SETTINGS หรือ FAIL_ON_PROJECT_REPOS) และ repositories (รายการที่เก็บข้อมูล) หาก repositoriesMode = PREFER_SETTINGS ที่เก็บข้อมูลระดับโมดูลจะถูกละเว้น — จะใช้เฉพาะรายการแบบรวมศูนย์เท่านั้น

repositoriesMode สามารถรับค่าได้สามค่า PREFER_SETTINGS — ที่เก็บข้อมูลจาก build.gradle จะถูกละเว้น ใช้เฉพาะจาก settings.gradle เท่านั้น PREFER_PROJECT — ที่เก็บข้อมูล build.gradle มีลำดับความสำคัญเหนือ settings.gradle FAIL_ON_PROJECT_REPOS — หากโมดูลประกาศที่เก็บข้อมูลของตัวเอง Gradle จะแสดงข้อผิดพลาด สำหรับโปรเจกต์ใหม่ แนะนำให้ใช้ PREFER_SETTINGS ซึ่งรับประกันว่าโมดูลทั้งหมดใช้ที่เก็บข้อมูลเดียวกันและกำจัดการซ้ำซ้อน

repositoriesMode = FAIL_ON_PROJECT_REPOS มีประโยชน์โดยเฉพาะในทีม: หากนักพัฒนาเพิ่มที่เก็บข้อมูลในโมดูลเดียวเท่านั้นและโมดูลอื่นไม่เห็น จะเกิดปัญหา “works on my machine” FAIL_ON_PROJECT_REPOS บังคับให้ที่เก็บข้อมูลทั้งหมดถูกประกาศแบบรวมศูนย์ใน settings.gradle ป้องกันสถานการณ์ดังกล่าว Google แนะนำ FAIL_ON_PROJECT_REPOS สำหรับโปรเจกต์ Android ทั้งหมดตั้งแต่ AGP 8.0

dependencyResolutionManagement {
    // FAIL_ON_PROJECT_REPOS — ที่เก็บข้อมูลทั้งหมดอยู่ที่นี่เท่านั้น
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)

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

        // ที่เก็บ Maven ส่วนตัว
        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") ?: ""
            }
        }
    }
}

// ใน build.gradle ของโมดูล ไม่จำเป็นต้องใช้ repositories อีกต่อไป!
// ที่เก็บข้อมูลทั้งหมดรวมศูนย์ใน settings.gradle

แค็ตตาล็อกเวอร์ชันใน settings.gradle

Version Catalogs คือวิธีการจัดการเวอร์ชันการพึ่งพาแบบรวมศูนย์ผ่านไฟล์ TOML ตั้งแต่ Gradle 7.4 แค็ตตาล็อกเวอร์ชันเป็นกลไกที่แนะนำสำหรับโปรเจกต์ Android ทั้งหมด ไฟล์ gradle/libs.versions.toml ประกอบด้วยสามส่วน: [versions] (เวอร์ชัน), [libraries] (การพึ่งพา), [plugins] (ปลั๊กอิน) ใน settings.gradle แค็ตตาล็อกเวอร์ชันจะเชื่อมต่อผ่าน @Suppress("UnstableApiUsage") และ enableFeaturePreview("VERSION_CATALOGS") (ใน Gradle เวอร์ชันเก่า)

หลังจากเชื่อมต่อแค็ตตาล็อกเวอร์ชันแล้ว การพึ่งพาโมดูลใน build.gradle จะถูกระบุผ่าน libs: implementation(libs.retrofit) IDE จะให้การเติมข้อความอัตโนมัติสำหรับ libs แค็ตตาล็อกจะสร้าง accessor แบบ type-safe โดยอัตโนมัติ: libs.retrofit, libs.kotlin.coroutines, libs.bundles.compose Bundles คือกลุ่มของการพึ่งพาที่สามารถรวมได้ในบรรทัดเดียว แค็ตตาล็อกเวอร์ชันยังรองรับการสืบทอด — สามารถเชื่อมต่อไฟล์ TOML หลายไฟล์ได้

ข้อดีของแค็ตตาล็อกเวอร์ชัน: ตำแหน่งเดียวสำหรับเวอร์ชัน (ไม่ต้องค้นหาในไฟล์ build.gradle ทั้งหมด); การเข้าถึงแบบ type-safe (ข้อผิดพลาดในชื่อ libs จะถูกตรวจจับขณะคอมไพล์ ไม่ใช่ขณะรันไทม์); การอัปเดตอัตโนมัติ (Dependabot และ Renovate รองรับ TOML); ความเข้ากันได้กับ Convention Plugins Google Firebase และ AndroidX เผยแพร่แค็ตตาล็อก TOML ของตัวเอง สำหรับการย้ายไปยังแค็ตตาล็อกเวอร์ชัน มีปลั๊กอินที่ถ่ายโอนเวอร์ชันจาก build.gradle ไปยัง 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" }

การตั้งค่าขั้นสูง: includeBuild และคุณลักษณะทดลอง

includeBuild คือคำสั่งสำหรับสร้าง composite build: การรวมโปรเจกต์ Gradle ภายนอกเป็นส่วนหนึ่งของบิลด์ปัจจุบัน แตกต่างจาก include (ซึ่งรวมโมดูล) includeBuild จะรวมโปรเจกต์ทั้งหมดที่มี settings.gradle โมดูล และปลั๊กอินของตัวเอง Composite builds ใช้สำหรับ: การพัฒนาไลบรารี (การวิเคราะห์ เครือข่าย) ควบคู่ไปกับแอปพลิเคชัน; การรวม Convention Plugins จากที่เก็บข้อมูลแยกต่างหาก; การรวมโมดูล build-logic

คุณลักษณะทดลอง (Incubating Features) คือตัวเลือกทดลองของ Gradle ที่เปิดใช้งานผ่าน enableFeaturePreview("FEATURE_NAME") ใน AGP 8.7+ มีคุณลักษณะที่พร้อมใช้งาน: TYPESAFE_PROJECT_ACCESSORS (การเข้าถึงโปรเจกต์แบบ type-safe ในโปรเจกต์หลายโมดูล: แทนที่จะใช้ project(":core:network") สามารถเขียน projects.core.network), STABLE_CONFIGURATION_CACHE (แคชการกำหนดค่าที่เสถียร), ARTIFACT_TRANSFORM_FOR_INTERNAL_TEST (การแปลงอาร์ติแฟกต์) คุณลักษณะทดลองสามารถเปิดใช้งานในการผลิตได้ แต่ API อาจเปลี่ยนแปลงในเวอร์ชันอนาคต

Gradle Enterprise และ Build Scan ยังถูกกำหนดค่าผ่าน settings.gradle: plugins { id("com.gradle.enterprise") } พร้อมบล็อก gradleEnterprise Build Scan คือบริการคลาวด์ที่แสดงข้อมูลโดยละเอียดเกี่ยวกับแต่ละบิลด์: เวลาดำเนินการของแต่ละงาน แคช ข้อผิดพลาด การเปิดใช้งาน Build Scan ช่วยวินิจฉัยปัญหาความเร็วของบิลด์ Build Scan ฟรีสำหรับโปรเจกต์โอเพนซอร์ส

// คุณลักษณะทดลอง
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)
    }
}

// การใช้ type-safe project accessors ใน build.gradle
// แทนที่: implementation(project(":core:network"))
// สามารถ: implementation(projects.core.network)