settings.gradle: その概要、モジュールのinclude、pluginManagement

settings.gradleとは？

settings.gradle（Kotlin DSLの場合はsettings.gradle.kts）は、GradleがInitializationフェーズで実行するファイルです。プロジェクト階層を定義し、モジュールを追加し、プラグインと依存関係のリポジトリを設定します。settings.gradleがないと、Gradleはどのモジュールをビルドすべきか、どのプラグインが利用可能かを認識できません。シングルモジュールプロジェクトではsettings.gradleがなくても問題ありませんが、マルチモジュールプロジェクトでは必須です。

settings.gradleファイルはプロジェクトルートにあり、ルートのbuild.gradleと並んで配置されます。典型的なルートプロジェクト構造: settings.gradle.kts、build.gradle.kts、gradle.properties、local.properties、gradle/wrapper/。settings.gradleはbuild.gradleより先に実行されます。Initializationフェーズでは、Gradleがプロジェクトツリー（Gradle APIのProject）を構築します。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はAGP 8.0以降、Android Gradle Pluginでこれらの機能を必須としています。

settings.gradle vs 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は、include文字列と同じ名前のProjectをGradle APIに作成します。プロジェクト名は、他のモジュールのbuild.gradleファイルのimplementation(project(":module"))で使用されます。includeで追加されていないモジュールを参照すると、“Project not found”エラーが発生します。Android Studio IDEも、Projectパネルにモジュールを表示するためにsettings.gradleを使用します。includeされていないモジュールはファイルツリーに表示されません。

includeはincludeBuild("../library-project")によるincluded buildsとcomposite buildsをサポートしています。これにより、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は、Gradleプラグインの読み込み元を指定するsettings.gradleのブロックです。Gradle 6.8で導入され、プラグインを適用する前に集中管理するためのものです。pluginManagement内には、repositories（プラグインを検索するリポジトリのリスト）、resolutionStrategy（バージョン解決ルール）、plugins（明示的なプラグインバージョンの宣言）があります。pluginManagementが定義されていない場合、Gradleはbuild.gradleのリポジトリを使用しますが、プラグインは宣言された後にのみ検索されるため、プラグインが見つからない場合にエラーが発生します。

Androidプロジェクトでは、Version CatalogsやConvention Pluginsを使用する場合、pluginManagementが必須です。pluginManagementがないと、Gradleはbuild.gradle.ktsで適用する際にcom.android.applicationプラグインを見つけられません。一般的な設定: 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で、各build.gradleでrepositoriesを宣言する代わりとして導入されました。ブロック内では、repositoriesMode（モード: PREFER_PROJECT、PREFER_SETTINGS、FAIL_ON_PROJECT_REPOS）とrepositories（リポジトリのリスト）を設定します。repositoriesMode = PREFER_SETTINGSの場合、モジュールレベルのrepositoriesは無視され、集中管理されたリストのみが使用されます。

repositoriesModeは3つの値を取ります。PREFER_SETTINGS — build.gradleのリポジトリは無視され、settings.gradleのもののみが使用されます。PREFER_PROJECT — build.gradleのリポジトリがsettings.gradleより優先されます。FAIL_ON_PROJECT_REPOS — モジュールが独自のリポジトリを宣言すると、Gradleがエラーを発生させます。新しいプロジェクトではPREFER_SETTINGSが推奨されます。これにより、すべてのモジュールが同じリポジトリを使用することが保証され、重複が排除されます。

repositoriesMode = FAIL_ON_PROJECT_REPOSは特にチームで有用です。開発者が1つのモジュールにのみリポジトリを追加し、他のモジュールからは見えない場合、“works on my machine”問題が発生します。FAIL_ON_PROJECT_REPOSはすべてのリポジトリをsettings.gradleで集中宣言することを強制し、このような状況を防ぎます。GoogleはAGP 8.0以降、すべてのAndroidプロジェクトでFAIL_ON_PROJECT_REPOSを推奨しています。

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ファイルには3つのセクションがあります。[versions]（バージョン）、[libraries]（依存関係）、[plugins]（プラグイン）。settings.gradleでは、バージョンカタログは@Suppress("UnstableApiUsage")とenableFeaturePreview("VERSION_CATALOGS")（古いGradleバージョン）を介して接続されます。

バージョンカタログを接続すると、build.gradleのモジュール依存関係はlibsを介して指定されます。implementation(libs.retrofit)のように記述します。IDEはlibsのオートコンプリートを提供します。カタログは自動的に型安全なアクセサを生成します: libs.retrofit、libs.kotlin.coroutines、libs.bundles.compose。Bundlesは1行で追加できる依存関係のグループです。バージョンカタログは継承もサポートしており、複数のTOMLファイルを接続できます。

バージョンカタログの利点: バージョンを一元管理（すべてのbuild.gradleを検索する必要なし）；型安全なアクセス（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は、複合ビルドを作成するためのディレクティブです。現在のビルドの一部として外部のGradleプロジェクトを含めます。include（モジュールを含める）とは異なり、includeBuildは独自のsettings.gradle、モジュール、プラグインを持つプロジェクト全体を含めます。複合ビルドは、アプリケーションと並行してライブラリ（分析、ネットワーキング）を開発する場合、別のリポジトリからConvention Pluginsを含める場合、build-logicモジュールを統合する場合に使用されます。

試験的機能（Incubating Features）は、enableFeaturePreview("FEATURE_NAME")で有効になるGradleの実験的オプションです。AGP 8.7+では、TYPESAFE_PROJECT_ACCESSORS（マルチモジュールプロジェクトでの型安全なプロジェクトアクセス: 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)
    }
}

// build.gradleでの型安全プロジェクトアクセサの使用
// 代わりに: implementation(project(":core:network"))
// 可能: implementation(projects.core.network)