compileSdkVersion：基本、新しいAPI、Gradleの設定

AndroidのcompileSdkVersionとは？

compileSdkVersionはbuild.gradleの整数パラメーターで、コードをコンパイルするAndroid SDKのバージョンを指定します。android.*やandroidx.*のクラスを使用してコードを書くとき、コンパイラは指定されたcompileSdkバージョンで利用可能なAPIと照合します。メソッドがAPI 36で導入され、compileSdk = 35の場合、コードはコンパイルされません。compileSdk = 36の場合、コードはコンパイルされますが、チェックなしでAPI 35のデバイスでそのメソッドを呼び出すとクラッシュします。

compileSdkVersionは、Android StudioのSDK ManagerからインストールされたAndroid SDK Platformから読み込まれます。各APIレベルには独自のプラットフォームがあります：android-21、android-29、android-34、android-35、android-36。プラットフォームにはandroid.jarが含まれています。これはKotlin/Javaコンパイラが使用するクラス、メソッド、定数のセットです。プラットフォームがインストールされていない場合、Gradleは最初のビルド時にsdkmanagerを介して自動的にダウンロードします。

AGP（Android Gradle Plugin）バージョン8.7+は、Kotlin DSLでandroid-プレフィックスなしでcompileSdk = 36として整数でcompileSdkを指定することを推奨しています。compileSdkはGroovy DSLでcompileSdkVersion 36を使用して、またはプレリリースSDKバージョン（デベロッパープレビュー）用にcompileSdkPreviewを使用して設定することもできます。compileSdkPreviewは、公式リリース前の今後のAPIレベルのテストに使用されます。

// build.gradle.kts — compileSdkVersionの設定
android {
    namespace = "com.example.myapp"

    // compileSdk = 36 — 最新の安定APIレベル（Android 16）
    compileSdk = 36

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

// 代替：プレビュー版にはcompileSdkPreview
// compileSdkPreview = "Baklava"

この例では、compileSdk = 36がすべてのAndroid 16（Baklava）APIへのアクセスを提供します。Android SDK Platform 36はSDK Managerにインストールする必要があります。"Baklava"という名前のcompileSdkPreviewは、公式プラットフォームリリース前に不安定なAPIをテストするために使用できます。リリース後、プレビューは安定版のcompileSdk = 36に置き換えられます。

compileSdkVersion vs targetSdkVersion vs minSdkVersion

build.gradleの3つのAPIレベルパラメーター — compileSdkVersion、targetSdkVersion、minSdkVersion — はよく混同されます。それぞれが互換性の異なる側面を担当し、その値はcompileSdk >= targetSdk >= minSdkのルールに従う必要があります。minSdkは下限です：これを下回るデバイスはアプリを認識しません。targetSdkはテストポイントです：このレベルまでの動作変更が有効になります。compileSdkは天井です：このレベルより上のAPIはコンパイラが使用できません。

重要な実践ルール：compileSdkはデバイステストなしで引き上げることができます。これはコンパイラに新しいバージョンのandroid.jarを提供するだけの安全な操作です。唯一のリスクは、新しいプラットフォームバージョンで削除される可能性のある非推奨APIですが、これはコンパイル時に検出され簡単に修正できます。一方、targetSdkの引き上げには完全なQAサイクルが必要です。

compileSdkがtargetSdkより高くなる理由は？Android 16（API 36）が新しいAPIとともにリリースされ、コードで使用したいが、API 36の動作変更をまだテストしていないとします。compileSdk = 36（新しいAPIが利用可能）、targetSdk = 35（API 36の動作変更を無効）と設定します。コードはコンパイルされ、SDK_INTチェックのもとで新しいメソッドを使用し、targetSdk = 35のためAPI 36の動作変更はアプリを壊しません。

正しい組み合わせの例

compileSdk = 36、targetSdk = 36、minSdk = 26 — 最新のAPIと動作変更との完全な互換性、デバイスの85%をカバー。compileSdk = 36、targetSdk = 34、minSdk = 26 — 新しいAPIが利用可能、動作変更はAPI 34までのみ。compileSdk = 35、targetSdk = 36 — 不正：compileSdkがtargetSdkより低く、API 36は利用不可だが36の動作変更はアクティブ。

compileSdkVersionの更新方法：ステップバイステップガイド

compileSdkVersionの更新は、Androidプロジェクトで最もシンプルで安全な操作の1つです。targetSdkとは異なり、動作変更の広範なテストは必要ありません。ただし、コンパイルエラーや非推奨警告を避けるために従うべきいくつかの手順があります。

ステップ1 — Android StudioのSDK Managerから新しいプラットフォームをインストール：Tools → SDK Manager → SDK Platforms → 新しいAPIレベルを選択。プラットフォームをインストールしない場合、Gradleは自動的にダウンロードを試みますが、最初のビルドが遅くなる可能性があります。ステップ2 — build.gradleのcompileSdkを新しい値に変更。ステップ3 — ビルド（Build → Make Project）してコンパイルエラーを修正。

ステップ4 — 非推奨APIを確認。compileSdkを上げた後、一部のメソッドが@Deprecated（「API Xで削除されました」の注釈付き）とマークされる場合があります。Android Studioは取り消し線で強調表示し、警告を表示します。非推奨の呼び出しを新しい代替手段に置き換えます。代替手段にminSdkより高いAPIレベルが必要な場合は、ランタイムチェックを追加します。ステップ5 — 依存関係を確認：一部のライブラリは特定のcompileSdkバージョンを必要とする場合があります。AGP 8.7+はcompileSdk = 36を推奨しています。

// compileSdkアップグレード後：非推奨APIの置き換え
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.os.Process
import android.app.ActivityManager

class CompileSdkMigration {

    // 変更前：非推奨メソッド（新しいAPIで削除される可能性あり）
    @Suppress("DEPRECATION")
    fun getMemoryClassOld(context: android.content.Context): Int {
        val am = context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
        return am.memoryClass  // API 36で非推奨になる可能性あり
    }

    // 変更後：新しい代替手段（利用可能な場合）
    fun getMemoryClassNew(context: android.content.Context): Int {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // compileSdk 36の新しいAPI
            val am = context.getSystemService(
                android.content.Context.ACTIVITY_SERVICE
            ) as ActivityManager
            return am.getMemoryClassSafe()  // 新しいAPIの例
        }
        @Suppress("DEPRECATION")
        return context.getSystemService(
            android.content.Context.ACTIVITY_SERVICE
        ) as ActivityManager
            .memoryClass
    }
}

CompileSdkMigrationクラスは正しい移行パターンを示しています。古いメソッドmemoryClassは新しいAPIで削除される可能性があり、コンパイラがエラーを出します。新しい代替手段getMemoryClassSafeはAPI 36+でのみ利用可能なため、SDK_INT >= BAKLAVAチェックのもとで呼び出されます。古いデバイスでは、@Suppress("DEPRECATION")を使用したフォールバックが使用されます。

新しいAPIの使用：条件付きチェックとフォールバック

新しいAPIはcompileSdkVersionのアップグレードにより利用可能になりますが、minSdkVersionがそのAPIレベルより低い場合、直接呼び出すことはできません。ランタイムチェックがないと、古いデバイスでAbstractMethodError、NoSuchMethodError、VerifyErrorが発生してアプリがクラッシュします。主要な保護メカニズムはBuild.VERSION.SDK_INTをチェックし、APIレベルが十分な場合のみ新しいAPIを呼び出し、古いバージョンにはフォールバックを提供することです。

AndroidXは多くの新しいAPIのバックポートを提供し、低いcompileSdkでも最新のメソッドを使用できるようにします。たとえば、androidx.activity:activity-ktx:1.9.3のActivity Result APIはAPI 14以降のすべてのAndroidバージョンで動作します。AndroidXのNotificationCompatは古いAPIで最新の通知を可能にします。PhotoPickerはAPI 34+以降、ActivityResultContracts.PickVisualMediaを介して利用可能です。

// compileSdk 36とminSdk 26での新しいAPIの安全な呼び出し
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.graphics.Color

class NewApiHelper {

    // API 36+：色を扱う新しいメソッド
    fun formatColor(colorInt: Int): String {
        if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // compileSdk 36の新しいAPI — API 36+が必要
            return Color.toArgbHexString(colorInt)
        }
        // フォールバック：古いAPIの手動フォーマット
        return String.format(
            "#%08X", (0xFFFFFFFF toLong() and colorInt.toLong())
        )
    }

    // AndroidX：バックポート不要 — SDK_INTチェック
    fun isEdgeToEdgeAvailable(): Boolean {
        return VERSION.SDK_INT >= VERSION_CODES.VANILLA_ICE_CREAM
    }
}

// Activityでの使用
class ColorActivity : android.app.Activity() {
    override fun onCreate(savedInstanceState: android.os.Bundle?) {
        super.onCreate(savedInstanceState)
        val helper = NewApiHelper()
        val colorStr = helper.formatColor(0xFF6200EE)
        println("Color: $colorStr")
    }
}

NewApiHelperクラスは、古いバージョン用のフォールバックフォーマットを使用した新しいAPI Color.toArgbHexString（架空のAPI 36）の安全な呼び出しを示しています。重要な原則：compileSdkはコード内で新しいメソッドを呼び出すアクセスを提供しますが、ランタイムのSDK_INTチェックが古いデバイスでのクラッシュから保護します。SDK_INTチェックがないと、minSdk 26、compileSdk 36のアプリはAndroid 8-15でクラッシュします。

AGP（Android Gradle Plugin）とcompileSdkVersion

Android Gradle Plugin（AGP）はAndroidアプリケーションの主要なビルドツールです。各AGPバージョンは特定の範囲のcompileSdkVersionをサポートしています。AGP 8.7.x（2026年リリース）はcompileSdk >= 34を必要とし、compileSdk = 36を推奨しています。AGP 8.5.xはcompileSdk 33-35をサポートしています。compileSdkがAGPの最小値を下回る場合、ビルドはエラーで失敗します：「The SDK platform (X) is not supported by this version of the Android Gradle Plugin」。

NDK（Native Development Kit）もcompileSdkVersionに関連付けられています。プロジェクトがNDKを介してC/C++のネイティブコードを使用する場合、compileSdkはヘッダーファイルとライブラリのバージョンを決定します。NDK r27+はcompileSdk 36を推奨しています。.soファイルを含むライブラリの場合、compileSdkはApplication.mkのAPP_MIN_SDK_VERSIONを介してネイティブコードの最小APIレベルに影響します。

Gradle（7.6+）とKotlin（2.0+）もcompileSdkの互換性に影響します。AGP 8.7+にはGradle 8.9+とKotlin 2.0+が必要です。compileSdkをアップグレードする際は、AGP、Gradle、Kotlinを最新の安定バージョンに更新することをお勧めします。公式のAndroid Gradle Plugin互換性テーブルで互換性を確認してください。

compileSdkアップグレード時の一般的な問題

compileSdkVersionアップグレード時の問題は3つのカテゴリに分類されます：コンパイルエラー、非推奨警告、ランタイム非互換性。コンパイルエラー — メソッドがAPIから削除され、コードがコンパイルされない。非推奨警告 — メソッドが@Deprecatedとマークされ、コードは警告付きでコンパイルされる。ランタイム非互換性 — 新しいAPIが特定の機能に必要で、デバイスのAPIレベルが不十分な場合にエラーが発生する。

最初の一般的な問題 — 「Cannot resolve symbol X」。これは、クラスまたはメソッドが新しいSDKバージョンのパブリックAPIから削除されたことを意味します。解決策：新しいプラットフォームで代替手段を見つけるか、AndroidX相当品を使用します。たとえば、AsyncTaskLoaderクラスはAPI 28で非推奨になり、新しいバージョンでパブリックAPIから削除されました。代替手段にはKotlin CoroutinesやWorkManagerがあります。

2番目の問題 — メソッドシグネチャの変更。新しいAPIバージョンで、メソッドのパラメーターの数や型が変更される場合があります。Kotlin/Javaコンパイラがエラーを出します：「None of the following functions can be called with the arguments supplied」。解決策：新しいシグネチャに合わせてメソッド呼び出しを更新するか、古いデバイス用に古いシグネチャ呼び出しを伴うSDK_INTチェックを追加します。

// compileSdkアップグレード時の問題解決
import android.os.Build
import android.os.Build.VERSION
import android.os.Build.VERSION_CODES
import android.content.pm.PackageManager

class CompileSdkProblemFixer {

    // 問題：メソッドhasSystemFeatureがAPI 36でシグネチャを変更
    fun hasCamera(pm: PackageManager): Boolean {
        return if (VERSION.SDK_INT >= VERSION_CODES.BAKLAVA) {
            // 新しいシグネチャ：hasSystemFeature(String, FeatureType)
            pm.hasSystemFeature(
                PackageManager.FEATURE_CAMERA,
                PackageManager.FEATURE_TYPE_BACK
            )
        } else {
            // 古いシグネチャ：hasSystemFeature(String)
            @Suppress("DEPRECATION")
            pm.hasSystemFeature(PackageManager.FEATURE_CAMERA)
        }
    }

    // 問題：クラスが削除されたのでAndroidX相当品を使用
    fun loadFragment(manager: androidx.fragment.app.FragmentManager) {
        // android.app.FragmentManager（削除済み）の代わりに使用
        // androidx.fragment.app.FragmentManager
        val fragment = CustomFragment()
        manager.beginTransaction()
            .replace(android.R.id.content, fragment)
            .commit()
    }
}

CompileSdkProblemFixerクラスは一般的な問題を解決します：hasSystemFeatureの変更されたシグネチャ（API 36での架空の変更）は、正しいバージョンのメソッドを呼び出すSDK_INTチェックを介して処理されます。削除されたクラスandroid.app.FragmentManagerはAndroidX相当品に置き換えられます。代替手段がない古い呼び出しについては、@Suppress("DEPRECATION")が、それを維持する理由を説明するコメントとともに使用されます。