build.gradle: Androidにおける構文と設定の完全ガイド

build.gradleとは？

build.gradleは、Groovy（.gradle拡張子）またはKotlin（.gradle.kts）で記述されたビルドスクリプトであり、Androidアプリケーションのコンパイルのすべての側面を管理します。Gradleは、Googleが2013年にAndroidの標準として採用した自動ビルドシステムです。build.gradleは次の内容を記述します：適用されるプラグイン（Android、Kotlin、ライブラリ）、接続される依存関係、使用されるSDKバージョン、アプリケーションの署名方法、公開先。

ビルドプロセスには3つのフェーズがあります：Initialization（モジュールの検出）、Configuration（build.gradleスクリプトの実行）、Execution（タスクの実行）。build.gradleはConfigurationフェーズで実行され、Gradleがタスクグラフを作成します。この時点でBuild Variantsが決定され、依存関係が計算され、タスクが設定されます。重要な点：build.gradleはコードであり、単なる設定ではありません。条件分岐、ループ、メソッド呼び出し、外部スクリプトを使用できます。

Gradleファイルはモジュールルート（app/build.gradle）とプロジェクトルート（build.gradle）に保存されます。さらに、Gradleはapply from — 外部Gradleスクリプトの組み込みをサポートしています。これにより、繰り返しロジックを共有設定ファイルに抽出できます。Convention Plugins（AGP 7+）の登場により、apply fromは非推奨と見なされています — Convention Pluginsはモジュール間で設定を再利用するためのタイプセーフで合成可能な方法を提供します。

build.gradleの進化

2013年以降、build.gradleの構文は動的設定のGroovyからコンパイル時チェックのKotlin DSLへと大きく変化しました。AGPはバージョン1.0から8.7（2025年）に進化しました。主なマイルストーン：AGP 3.0（Java 8 desugar、新しいvariant API）、AGP 4.0（view binding、Java 11）、AGP 7.0（デフォルトでKotlin DSL、Java 11最低）、AGP 8.0（非推移的Rクラス、Kotlinでのビルド設定）、AGP 8.7（kaptの代わりにKSP、高速設定）。

Project-levelとModule-levelのbuild.gradle

Project-level build.gradle（ルート）は、すべてのモジュールに共通のプラグイン、リポジトリ、設定を定義します。主要ブロック：plugins（Gradleプラグイン宣言）、repositories（依存関係ソース：mavenCentral、google、jitpack）。ルートbuild.gradleには通常androidブロックはありません — モジュールに現れます。Project-levelにはすべてのサブプロジェクトの共通設定のためのsubprojectsブロックも含められますが、Convention Pluginsの方が推奨されます。

Module-level build.gradle（例：app/build.gradle）は特定のモジュールを記述します。モジュールがアプリケーションの場合はcom.android.applicationプラグインを適用します。ライブラリの場合はcom.android.libraryを適用します。Module-levelにはandroidブロック（compileSdk、defaultConfig、buildTypes、productFlavors）、dependenciesブロック（モジュール依存関係）、オプションでテストとパッケージング設定のブロックが含まれます。Module-levelはproject-levelの後に実行され、共通設定を上書きできます。

AGP 8.0以降、ルートbuild.gradleは依存関係バージョンの集中管理のためにversion catalogs（libs.versions.toml）を使用できます。version catalogはgradle/ディレクトリにあるファイルで、バージョン、ライブラリ、プラグインを含みます。build.gradleでは依存関係はlibsを介して接続されます：implementation(libs.retrofit)。version catalogsは新しいプロジェクトでは必須であり、3つ以上のモジュールを持つすべてのプロジェクトで推奨されます。

// settings.gradle.kts — プロジェクトルート
pluginManagement {
    repositories {
        google()
        mavenCentral()
        gradlePluginPortal()
    }
}

// build.gradle.kts (project-level)
plugins {
    id("com.android.application") version "8.7.0" apply false
    id("org.jetbrains.kotlin.android") version "2.0.21" apply false
}

// app/build.gradle.kts (module-level)
plugins {
    id("com.android.application")
    id("org.jetbrains.kotlin.android")
    id("com.google.devtools.ksp")
}

android {
    namespace = "com.example.myapp"
    compileSdk = 35

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 1
        versionName = "1.0.0"
    }
}

Groovy vs Kotlin DSL

Groovyは動的JVM言語であり、Gradleの元々の構文でした。Groovyスクリプト（.gradle）は動的型付けを使用します：型を省略したり、引用符あり/なしで文字列を使用したり、コンパイル時に存在しないメソッドを呼び出したりできます。Groovyの柔軟性は欠点でもあります。スクリプトが実行されるまでIDEが構文と型を検証できず、パラメータ名や型の誤りによる実行時エラーが発生します。

Kotlin DSL（.gradle.kts）はKotlinの静的型付けを使用します。IDEが型を検証し、オートコンプリートで利用可能なパラメータを提案し、編集中にエラーを強調表示します。Kotlin DSLはConfigurationフェーズでは遅くなります（.ktsファイルをバイトコードにコンパイルするため）が、Googleは継続的にパフォーマンスを改善しています。AGP 8.5+はGradle Configuration CacheとCaching Kotlin DSL compilationを使用し、差を1〜2秒に縮小しています。

Googleはすべての新規プロジェクトにKotlin DSLを推奨し、既存プロジェクトの段階的な移行を推奨しています。GroovyからKotlin DSLへの移行は簡単です：引用符が括弧に置き換えられ、型が追加され、演算子が関数に変換されます。ほとんどのライブラリはドキュメントでKotlin DSLの例を提供しています。複雑なケース（Custom Plugin、Task Graph）では、Kotlin DSLはタイプセーフなAPIを提供し、Groovyでは実行時にしか発見できないエラーを防止します。Version catalogs（libs.versions.toml）は両方の構文で同じように機能します。

androidブロック：アプリ設定

compileSdk、minSdk、targetSdk

androidブロックはmodule-level build.gradleの中心的な要素です。内部では、namespace（RおよびBuildConfig用）、compileSdk、defaultConfig、buildTypes、productFlavors、sourceSets、compileOptions、packaging、bundleが設定されます。androidブロックのすべてのパラメータはAndroidモジュールにのみ適用されます。モジュールがライブラリの場合、applicationの代わりにライブラリプラグインが使用され、androidブロックにapplicationIdはありません。

compileSdkはコードのコンパイルに使用するSDKバージョンです。最新のAndroid API（執筆時点では35）であるべきです。minSdkはサポートする最小APIバージョンです。targetSdkはアプリケーションがターゲットとするバージョンです（このバージョンの動作変更が適用されます）。compileSdkとtargetSdkの違い：compileSdkは利用可能なAPIを決定し、targetSdkはランタイムの動作を決定します。推奨：compileSdk = 最新、targetSdk = 最新 - 1（新しい変更への適応をテストするため）。

compileOptionsはJava互換性を設定します：sourceCompatibilityとtargetCompatibility。AGP 8+ではコンパイルにJava 17+が必要です。packagingはライブラリからのファイル包含を管理します：META-INF競合解決のためのexclude、merge、pickFirst。buildFeaturesはViewBinding、DataBinding、Composeを有効/無効にします。aaptOptionsはリソース処理を設定します：ignoreAssetsPattern、cruncherEnabled。androidブロックの各要素はビルドの特定の側面を最適化します。

android {
    namespace = "com.example.myapp"
    compileSdk = 35
    buildToolsVersion = "35.0.0"

    defaultConfig {
        applicationId = "com.example.myapp"
        minSdk = 26
        targetSdk = 35
        versionCode = 5
        versionName = "2.3.1"

        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        getByName("debug") { isDebuggable = true }
        getByName("release") {
            isMinifyEnabled = true
            proguardFiles(getDefaultProguardFile("proguard-android-optimize.txt"))
        }
    }

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_17
        targetCompatibility = JavaVersion.VERSION_17
    }

    buildFeatures {
        viewBinding = true
        compose = true
    }
}

依存関係管理

BOM（Bill of Materials）

build.gradleの依存関係は、プロジェクトに接続されるライブラリとモジュールです。dependenciesブロックはandroidブロックと同じレベルにあります。Gradleは複数の設定をサポートしています：implementation（ライブラリはこのモジュール内でのみ利用可能、推移的ではない）、api（ライブラリは依存モジュールに推移的に利用可能）、compileOnly（コンパイルのみ、APKに含まれない）、runtimeOnly（実行時のみ）、annotationProcessor / ksp（アノテーションプロセッサ）、testImplementation（テストのみ）、androidTestImplementation（インストルメンテーションテストのみ）。

AGP 8.0以降、非推移的Rクラス — 各ライブラリが独自のRクラスを持ち、リソースの競合を防止します。dependenciesブロックでは正しい設定を使用することが重要です：implementationは推移的依存関係を公開せず、ビルドを高速化します。apiはそれらを公開します — ライブラリが別のライブラリの型をエクスポートする場合に使用します（例：Retrofitが公開APIでOkHttpの型を使用する場合）。

バージョン管理にはBOM（Bill of Materials）の使用が推奨されます — 互換性のあるライブラリバージョンを定義するビルドファイルです。Firebase BOM：implementation(platform("com.google.firebase:firebase-bom:33.0.0"))。BOMを接続すると、バージョンなしでライブラリ名のみを指定できます — BOMが自動的に互換バージョンを選択します。これにより、異なるライブラリの推移的依存関係間の競合が解消されます。BOMはFirebase、Compose、Kotlin、Ktor、AndroidXで利用可能です。

dependencies {
    // BOM — バージョン管理
    implementation(platform("androidx.compose:compose-bom:2024.12.01"))
    implementation(platform("com.google.firebase:firebase-bom:33.0.0"))

    // AndroidXとCompose
    implementation("androidx.core:core-ktx")
    implementation("androidx.lifecycle:lifecycle-runtime-ktx")
    implementation("androidx.activity:activity-compose")
    implementation("androidx.compose.ui:ui")

    // Network
    implementation("com.squareup.retrofit2:retrofit:2.11.0")
    implementation("com.squareup.okhttp3:okhttp:4.12.0")

    // Firebase（BOMのバージョン）
    implementation("com.google.firebase:firebase-firestore")
    implementation("com.google.firebase:firebase-crashlytics")

    // テスト
    testImplementation("junit:junit:4.13.2")
    androidTestImplementation("androidx.test.ext:junit:1.2.1")
}

マルチモジュールプロジェクトでのbuild.gradle

マルチモジュールプロジェクトでは、各モジュールに独自のbuild.gradleがあります。モジュールを別のモジュールに接続するには、implementation(project(":module-name"))構文を使用します。Gradleは設定が変更されると自動的にモジュールを再ビルドします。マルチモジュールアーキテクチャはビルド時間を改善し（インクリメンタルビルド、並列処理）、フィーチャーモジュール、コアモジュール、ライブラリの責任を分離します。

マルチモジュールプロジェクトの主要な問題は設定の重複です。10個のモジュールが同じminSdk、compileSdk、Compose依存関係を持つ場合、異なるbuild.gradleファイルに10個のコピーが存在します。解決策はConvention Plugins（以前はbuildSrc）です。Convention PluginはKotlinで記述されたGradleプラグインで、モジュールに適用されます：plugins { id("myapp.android.library") }。プラグインは共通設定を含み、変更は即座にすべてのモジュールに適用されます。

Convention Pluginsを組織化するには、プロジェクトルートにbuild-logic/ディレクトリを使用します。settings.gradleにincludeBuildとKotlinプラグインが含まれます。Convention Pluginsはプロジェクト間で再利用するためにmavenリポジトリに公開できます。Googleはマルチモジュールプロジェクトの標準としてConvention Pluginsを推奨し、subprojects { }とapply fromを置き換えます。Convention Pluginsへの移行により、モジュールのbuild.gradleは10〜15行に削減されます。

// build-logic/src/main/kotlin/AndroidLibraryConventionPlugin.kt
class AndroidLibraryConventionPlugin : Plugin<Project> {
    override fun apply(target: Project) {
        with(target) {
            with(plugins) {
                apply("com.android.library")
                apply("org.jetbrains.kotlin.android")
            }
            extensions.configure<CommonExtension<*, *, *, *>> {
                compileSdk = 35
                defaultConfig { minSdk = 26 }
                compileOptions {
                    sourceCompatibility = JavaVersion.VERSION_17
                    targetCompatibility = JavaVersion.VERSION_17
                }
            }
        }
    }
}

// module/build.gradle.kts — Convention Pluginの後
plugins {
    id("myapp.android.library")
}

dependencies {
    implementation(project(":core:network"))
}