Android Gradle Eklentisi DSL/API taşıma zaman çizelgesi

Android Gradle Eklentisi (AGP), Android uygulamaları için desteklenen derleme sistemidir. Birçok farklı kaynak türünü derlemeyi ve bunları fiziksel bir Android cihazda veya emülatörde çalıştırabileceğiniz bir uygulamada birbirine bağlamayı destekler.

Aşağıdaki bölümde, AGP'nin DSL ve API'sinin planlanan evrimi açıklanmaktadır. Kararlı sürümlerde yeni API'ler kullanıma sunuldukça eski API'ler kullanımdan kaldırıldı olarak işaretlenir. Desteği sonlandırılan bu API'ler, bir sonraki kararlı sürümde kullanılamayacak. Aşağıdaki bölümlerde, her büyük AGP sürümündeki yaklaşan değişiklikler hakkında bilgi verilmektedir.

AGP API desteğinin sonlandırılması veya kaldırılmasıyla ilgili daha ayrıntılı bir günlük için AGP API güncellemeleri başlıklı makaleyi inceleyin.

AGP 10.0 (2026'nın sonlarında)

Android Gradle Eklentisi 10.0'da yapılan API değişiklikleri ve modernizasyon

AGP 10.0, tamamen tembel ve yapılandırma önbelleğiyle uyumlu bir derleme modeline geçişi tamamlıyor. Bu sürüm, eski ve geç yüklemeli olmayan API'leri daha güvenli ve daha yüksek performanslı bir mimariyle değiştirme amacıyla yıllardır sürdürülen çalışmaların sonucudur.

Neden geç derleme modeli?

Eski, geç yüklemeli olmayan derleme modelinde Gradle, her senkronizasyon veya derleme çağrısı sırasında nesneleri hevesle değerlendirir, varyant verilerini sorgular ve tüm proje modüllerinde görevleri yapılandırır. Bu istekli değerlendirme, çalışmayan varyantlar ve görevlerde CPU süresini ve belleği boşa harcar ve karmaşık derleme komut dosyalarında değerlendirme sıralaması çakışmalarına neden olur.

Lazy sağlayıcıları (Provider<T>) ve modern Variant API'yi (androidComponents {}) kullanan tamamen geç yüklemeli bir derleme modeline geçiş yaparak özellikler ve görev bağlantısı yalnızca etkin derleme yürütme grafiği tarafından ihtiyaç duyulduğunda isteğe bağlı olarak geç yüklemeli şekilde hesaplanır.

Bu sürümde kaldırılan eski API'ler, bu modern mimariyle temel olarak uyumsuzdu. Bu görevlerin kaldırılması, AGP'nin Gradle yapılandırma önbelleğini ve proje izolasyonunu tam olarak desteklemesini sağlar. Bu da Android Studio'da derleme hızlarını ve senkronizasyon sürelerini önemli ölçüde iyileştirir.

Temel mimari fark

Eski BaseVariant API'si (applicationVariants.all {}) istekli ve görev odaklıydı. Bu, yapılandırma aşamasında geliştiricilere Gradle görevlerine ve dahili yapılandırmalara doğrudan erişim sağlıyordu. Bu da modern Gradle performans özelliklerini doğal olarak bozuyordu.

Yeni Variant API (androidComponents {}) geç yüklemeli ve yapay ürün merkezlidir. Gradle'ın Property API'sini kapsamlı bir şekilde kullanır ve Task ile TaskProvider referanslarını tamamen kaldırır. Bu nedenle, temel görevlerin kendileri yerine giriş ve çıkışlarla (Variant.artifacts) temiz bir şekilde etkileşim kurmanız gerekir.

Kaldırılan ve değiştirilen özellikler

Eski DSL'de ve eski Variant API'de kullanılan tüm önceki arayüzler ve sınıflar silinir. Derleme komut dosyalarınızı ve özel eklentilerinizi hazırlamak için aşağıdaki kullanım ömrü sonu API'lerinden ve işaretlerinden geçiş yapın:

Tüm değiştirme DSL'sine ve Variant API (androidComponents {}) arayüzlerine ve sınıflarına erişmek için özel Gradle eklentileri veya derleme mantığı geliştirirken her zaman gradle-api yapısını kullanın.

Taşıma adımları

AGP 10.0'a sorunsuz ve öngörülebilir bir şekilde geçiş yapmak için aşağıdaki taşıma uygulamalarını kullanın:

1. AGP Upgrade Assistant'ı çalıştırın: Doğrudan 10.0'a yükseltmeden önce Android Studio'da (Tools > AGP Upgrade Assistant) resmi AGP Upgrade Assistant'ı çalıştırın. Bu araç, çeşitli yaygın DSL ve derleme komut dosyası geçişlerini otomatikleştirir ve mevcut derleme davranışlarının korunmasına yardımcı olur.
2. Android Studio'da Temsilci Modu becerilerini kullanma: Android Studio'da karmaşık derleme mantığını ve DSL'leri taşımayı otomatikleştirmek ve basitleştirmek için yapay zeka yükseltme becerilerinden (ör. Android beceri deposunda bulunan AGP yükseltme becerileri) yararlanın.
3. Öncelikle AGP 9.x'teki kullanımdan kaldırma uyarılarını düzeltin: Projenizi en son AGP 9.x sürümüne yükseltin ve mevcut tüm kullanımdan kaldırma uyarılarını çözün. Projeniz 9.x sürümünde android.newDsl=false veya android.builtInKotlin=false'ye bağlı kalmadan ve uyarı vermeden çalıştığında 10.0 sürümüne sorunsuz bir şekilde geçebilirsiniz.
4. Üçüncü taraf Gradle eklentilerini denetleyin: Üçüncü taraf eklentilerin AGP 10.0 ile uyumlu sürümlere yükseltildiğinden emin olun. Hâlâ eski uzantı türlerini kullanan eklentiler, ClassCastException: ... cannot be cast to class BaseExtension gibi derleme hatalarına neden olur.
5. Resmi taşıma tariflerini kullanın: Gerçek dünyadaki karmaşık taşıma örnekleri ve yan yana karşılaştırmalar için resmi gradle-recipes GitHub deposuna bakın.

Aşağıda, androidComponents {} kullanarak eski varyantları istekli bir şekilde sorgulamaktan varyantları geç yapılandırmaya nasıl geçileceğini gösteren bir öncesi-sonrası karşılaştırması yer almaktadır:

Önce: Eski Variant API (AGP 10.0'da kaldırıldı)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

Sonra: Modern Variant API (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

AGP 9.x'te AGP 10.0 davranışını test etme

Derleme davranışlarını test etmeye ve uyumluluğu doğrulamaya başlamak için AGP 10.0 sürümünün yayınlanmasını beklemeniz gerekmez. AGP 9.x sürümünde çalışırken, gradle.properties dosyanızın devre dışı bırakma işlemlerini devre dışı bıraktığını ve aşağıdaki katı davranış işaretlerini ayarladığını doğrulayarak AGP 10.0 davranışını açıkça zorunlu kılabilirsiniz:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

android.newDsl=true ve android.builtInKotlin=true'yi zorunlu kılarak özel derleme mantığınızın ve üçüncü taraf eklentilerinizin AGP 10.0'ın katı API şartlarıyla tamamen uyumlu olduğunu doğrulayabilirsiniz.

Taşıma sırasında alt projeleri seçerek taşıma kapsamı dışında bırakma

Modern davranışları test etmek için projenizde android.newDsl=true özelliğini genel olarak etkinleştirmek istiyorsanız ancak belirli alt projeleri taşımak için daha fazla zamana ihtiyacınız varsa AGP 9.4.0-alpha04'ten itibaren tek tek modülleri devre dışı bırakabilirsiniz. Proje yollarını belirterek android.newDsl.optOut öğesini gradle.properties öğesine ekleyin:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

Modül başına seçici yerleşik Kotlin devre dışı bırakma

Projenizde yerleşik Kotlin'i genel olarak etkinleştirmek istiyorsanız (android.builtInKotlin=true) ancak belirli alt projeleri kotlin-android'den taşımak (veya Kotlin kodu içermeyen modüller için) için daha fazla zamana ihtiyacınız varsa bu modülleri proje düzeyinde değil, DSL düzeyinde yapılandırın. Modülün derleme dosyasında enableKotlin = false öğesini ayarlayın:

android {
    enableKotlin = false
}

Geri bildirim ve hata bildirme iş akışı

Yeni Variant API'nin gerekli kullanım alanlarınızı desteklediğinden emin olmak istiyoruz. Yeni Variant API'nin kullanım alanınızı desteklemediği eski API'lerden geçiş yaparken sorun yaşarsanız geri bildirimde bulunmak için aşağıdaki adımları uygulayın:

1. Mevcut öğeleri kontrol edin: Öncelikle, taşıma engelinizin zaten bilinen bir sorun olup olmadığını görmek için AGP 10.0 Variant API Global Tracking Bug'ı kontrol edin ve soruna +1 ekleyin.
2. Eksik API'leri bildirin: Kullanım alanınız benzersizse inceleyip yardımcı olabilmemiz için özel Varyant API şablonumuzu kullanarak yeni bir özellik isteği gönderin.

(Deneme aşamasında) Özel dahili AGP sınıflarına erişim kaldırıldı

gradle yapıtına bağımlılık, artık tüm dahili sınıfları gizliyor ve derleme erişimini yalnızca gradle-api yapıtında bulunan arayüzler ve sınıflarla sınırlıyor. Bu durum, eklenti derlemesini etkiler.

Dahili sınıflara erişmek için bağımlılığı manuel olarak eklemek mümkün değildir.

AGP 9.0 (Ocak 2026)

Yeni Variant API'ler kararlı sürümde, eski API'ler ise kullanımdan kaldırıldı

4.1 ve 4.2'de geliştirme aşamasında olan Variant API'leri artık kararlı sürümde ve gradle-api yapısında yer alıyor. Eski Variant API'de kullanılan önceki arayüzler ve sınıflar artık kullanımdan kaldırıldı ve kullanılabilmesi için açıkça etkinleştirilmesi gerekiyor.

Yeni DSL arayüzleri kararlı, eski arayüzler ise kullanımdan kaldırıldı

4.1, 4.2 ve 7.0'da geliştirme aşamasında olan DSL arayüzleri artık kararlı ve gradle-api yapısında yer alıyor. DSL'de kullanılan önceki arayüzler ve sınıflar artık kullanımdan kaldırıldı ve kullanılabilmesi için açıkça etkinleştirilmesi gerekiyor.

Özel dahili AGP sınıflarına erişmeye devam edebilirsiniz.

Diğer yapıtlar içinde bulunan AGP'den gelen özel dahili sınıflara, derleme dosyalarının ve eklentilerin derlenmesi sırasında erişilebilir ancak bu sınıflar herhangi bir zamanda önemli ölçüde değişebileceğinden bunları kullanmanızı önermiyoruz.