Derleme bağımlılıkları ekleme

Android Studio'daki Gradle derleme sistemi, harici ikili dosyaları veya diğer kitaplık modüllerini bağımlı olarak derlemenize dahil etmenize olanak tanır. Bağımlılıklar makinenizde veya uzak bir depoda bulunabilir. Ayrıca, beyan ettikleri tüm geçişli bağımlılıklar da otomatik olarak dahil edilir. Bu sayfada, Android Gradle eklentisine (AGP) özgü davranışlar ve yapılandırmalarla ilgili ayrıntılar da dahil olmak üzere Android projenizle bağımlılıkların nasıl kullanılacağı açıklanmaktadır. Gradle bağımlılıkları hakkında daha ayrıntılı bir kavramsal kılavuz için bağımlılığı yönetmeyle ilgili Gradle kılavuzuna bakın. Ancak Android projenizin yalnızca bu sayfada tanımlanan bağımlılık yapılandırmalarını kullanması gerektiğini unutmayın.

Dikkat: Bağımlılıkları belirtirken 'com.android.tools.build:gradle:3.+' gibi dinamik sürüm numaraları kullanmamanız gerekir. Bu özelliğin kullanılması, beklenmedik sürüm güncellemelerine, sürüm farklılıklarının giderilmesinde zorluklara ve düşük performansa neden olabilir.

Kitaplık veya eklenti bağımlılığı ekleme

Derleme bağımlılıkları eklemenin ve yönetmenin en iyi yolu, yeni projelerin varsayılan olarak kullandığı yöntem olan sürüm kataloglarını kullanmaktır. Bu bölümde, Android projeleri için kullanılan en yaygın yapılandırma türleri ele alınmaktadır. Daha fazla seçenek için Gradle belgelerine bakın. Sürüm kataloglarını kullanan bir uygulama örneği için Android'de kullanıma sunuldu başlıklı makaleyi inceleyin. Sürüm katalogları olmadan derleme bağımlılıkları oluşturduysanız ve çok modüllü bir projeniz varsa taşımanızı öneririz.

Yerel bağımlılıkları (yaygın olmayan) ekleme ve yönetmeyle ilgili yardım için Yerel bağımlılıklar başlıklı makaleyi inceleyin.

Aşağıdaki örnekte, projemize bir uzak ikili bağımlılığı (Jetpack Macrobenchmark kitaplığı), yerel kitaplık modülü bağımlılığı (myLibrary) ve bir eklenti bağımlılığı (Android Gradle eklentisi) ekliyoruz. Bu bağımlılıkları projenize eklemek için genel adımlar şunlardır:

Not: Sürüm kataloglarını ayarlar dosyasında belirtmek mümkün olsa da Android Studio'dan kod önerileri ve vurgulama konusunda daha fazla destek almak için ayrı bir toml dosyası kullanmanızı öneririz.

1. Sürüm katalogu dosyasının [versions] bölümünde, istediğiniz bağımlılık sürümünün libs.versions.toml adlı bir takma adı ekleyin (Proje görünümünde gradle dizininin altında veya Android görünümünde Gradle Komut Dosyaları altında):

   [versions]
   agp = "8.3.0"
   androidx-macro-benchmark = "1.2.2"
   my-library = "1.4"
   
   [libraries]
   ...
   
   [plugins]
   ...
   

   Takma adlar tire veya alt çizgi içerebilir. Bu takma adlar, derleme komut dosyalarında referans verebileceğiniz iç içe yerleştirilmiş değerler oluşturur. Referanslar, libs.versions.toml öğesinin libs kısmı olan katalog adıyla başlar. Tek sürümlü bir katalog kullanırken varsayılan "libs" değerini korumanızı öneririz.

2. libs.versions.toml dosyasının [libraries] (uzak ikili dosyalar veya yerel kitaplık modülleri için) veya [plugins] (eklentiler için) bölümlerine bağımlılık için bir takma ad ekleyin.

   [versions]
   ...
   
   [libraries]
   androidx-benchmark-macro = { group = "androidx.benchmark", name = "benchmark-macro-junit4", version.ref = "androidx-macro-benchmark" }
   my-library = { group = "com.myapplication", name = "mylibrary", version.ref = "my-library" }
   
   [plugins]
   androidApplication = { id = "com.android.application", version.ref = "agp" }
   

   Bazı kitaplıklar, kitaplık ailelerini ve sürümlerini gruplandıran, yayınlanmış bir Malzeme Listesi'nde (BOM) bulunur. Sürüm kataloğunuza ve derleme dosyalarınıza bir BOM ekleyebilir ve bu sürümleri sizin için yönetmesine izin verebilirsiniz. Ayrıntılar için Malzeme Listesi'ni kullanma başlıklı makaleyi inceleyin.

3. Bağımlılığı gerektiren modüllerin derleme komut dosyasına bağımlılık takma adına bir referans ekleyin. Takma ada bir derleme komut dosyasından referans verirken takma addaki alt çizgileri ve kısa çizgileri noktaya dönüştürün. Modül düzeyindeki derleme komut dosyamız şu şekilde görünür:

   Kotlin

   plugins {
     alias(libs.plugins.androidApplication)
   }
   
   dependencies {
     implementation(libs.androidx.benchmark.macro)
     implementation(libs.my.library)
   }

   Groovy

   plugins {
     alias 'libs.plugins.androidApplication'
   }
   
   dependencies {
     implementation libs.androidx.benchmark.macro
     implementation libs.my.library
   }

   Eklenti referansları, katalog adından sonra plugins içerir ve sürüm referansları, katalog adından sonra versions içerir (sürüm referansları yaygın değildir; sürüm referansları örnekleri için Aynı sürüm numaralarına sahip bağımlılar bölümüne bakın.) Kitaplık referansları libraries niteleyicisi içermez. Bu nedenle, kitaplık takma adının başında versions veya plugins kullanamazsınız.

Bağımlılıkları yapılandırma

dependencies bloğunun içinde, çeşitli farklı bağımlı yapılandırmalardan birini (daha önce gösterilen implementation gibi) kullanarak bir kitaplık bağımlılığı beyan edebilirsiniz. Her bağımlılık yapılandırması, Gradle'e bağımlığın nasıl kullanılacağıyla ilgili farklı talimatlar sağlar. Aşağıdaki tabloda, Android projenizde bağımlılık için kullanabileceğiniz yapılandırmaların her biri açıklanmaktadır.

Yapılandırma	Davranış
implementation	Gradle, bağımlılığı derleme sınıf yolu yoluna ekler ve derleme çıkışına paketler. Modülünüz bir implementation bağımlılık yapılandırdığında, modülün derleme zamanında bağımlılık bilgilerini diğer modüllere aktarmasını istemediğinizi Gradle'e bildirir. Yani bağımlılık, mevcut modüle bağlı olan diğer modüllere sunulmaz. api yerine bu bağımlılık yapılandırmasını kullanmak, derleme sisteminin yeniden derlemesi gereken modül sayısını azalttığı için derleme süresinde önemli iyileştirmeler sağlayabilir. Örneğin, bir implementation bağımlılık API'sini değiştirirse Gradle yalnızca bu bağımlılık ve doğrudan bu bağımlılıktan etkilenen modülleri yeniden derleyecektir. Çoğu uygulama ve test modülü bu yapılandırmayı kullanmalıdır.
api	Gradle, bağımlılığı derleme sınıf yolu ve derleme çıkışına ekler. Bir modül api bağımlılık içerdiğinde, Gradle'e bu bağımlılık Bu yapılandırmayı yalnızca diğer yayın öncesi tüketicilere aktarmalı olarak dışa aktarmanız gereken bağımlılıklarla dikkatli bir şekilde kullanın. Bir api bağımlılık, harici API'sini değiştirirse Gradle, derleme sırasında bu bağımlılığa erişimi olan tüm modülleri yeniden derler. Çok sayıda api bağımlılığı olması derleme süresini önemli ölçüde artırabilir. Bir bağımlılık API'sini ayrı bir modüle göstermek istemiyorsanız kitaplık modülleri bunun yerine implementation bağımlılıklarını kullanmalıdır.
compileOnly	Gradle, bağımlılığı yalnızca derleme sınıf yolu yoluna ekler (yani derleme çıkışına eklenmez). Bu, bir Android modülü oluştururken derleme sırasında bağımlılıklara ihtiyaç duyduğunuzda yararlıdır ancak çalışma zamanında mevcut olması isteğe bağlıdır. Örneğin, yalnızca derleme zamanındaki ek açıklamaları içeren bir kitaplığa (genellikle kod oluşturmak için kullanılır ancak genellikle derleme çıkışına dahil edilmez) bağımlıysanız bu kitaplığı compileOnly olarak işaretleyebilirsiniz. Bu yapılandırmayı kullanıyorsanız kitaplık modülünüz, bağımlılıkların kullanılabilir olup olmadığını kontrol etmek için bir çalışma zamanı koşulu içermelidir. Ardından, sağlanmadığında da çalışmaya devam edebilmesi için davranışını uygun şekilde değiştirmelidir. Bu, kritik olmayan geçici bağımlılıklar eklenmediği için nihai uygulamanın boyutunu küçültmeye yardımcı olur. Not: compileOnly yapılandırmasını Android Arşivi (AAR) bağımlılıklarıyla kullanamazsınız.
runtimeOnly	Gradle, bağımlılığı yalnızca derleme çıkışına ekler. Bu bağımlılıklar, çalışma zamanında kullanılır. Yani derleme sınıf yolu listesine eklenmez. Bu, Android'de nadiren kullanılır ancak günlüğe kaydetme uygulamalarını sağlamak için sunucu uygulamalarında yaygın olarak kullanılır. Örneğin, bir kitaplık uygulama içermeyen bir günlük kaydı API'si kullanabilir. Bu kitaplığın kullanıcıları, kitaplığı implementation bağımlılık olarak ekleyebilir ve kullanılacak gerçek günlük kaydı uygulaması için runtimeOnly bağımlılık ekleyebilir.
ksp kapt annotationProcessor	Bu yapılandırmalar, kodunuz derlenmeden önce ek açıklamaları ve diğer sembolleri işleyen kitaplıklar sağlar. Genellikle kodunuzu doğrular veya ek kod oluşturur. Böylece, yazmanız gereken kod miktarını azaltır. Bu tür bir bağımlılığı eklemek için ksp, kapt veya annotationProcessor yapılandırmalarını kullanarak ek açıklama işleyici sınıf yoluna eklemeniz gerekir. Bu yapılandırmaların kullanılması, derleme sınıf yolunu ek açıklama işleyici sınıf yolundan ayırarak derleme performansını artırır. Gradle, derleme sınıf yolu içinde ek açıklama işleyicileri bulursa derlemeyi atlama özelliğini devre dışı bırakır. Bu da derleme süresini olumsuz etkiler (Gradle 5.0 ve sonraki sürümler, derleme sınıf yolu içinde bulunan ek açıklama işleyicilerini yoksayar). Android Gradle eklentisi, JAR dosyası aşağıdaki dosyayı içeriyorsa bağımlığın bir ek açıklama işleyici olduğunu varsayar: META-INF/services/javax.annotation.processing.Processor Eklenti, derleme sınıf yolu üzerinde bir ek açıklama işleyici algılarsa bir derleme hatası oluşturur. ksp, Kotlin sembol işlemcisidir ve Kotlin derleyicisi tarafından çalıştırılır. kapt ve apt, Kotlin veya Java derleyicileri çalıştırmadan önce ek açıklamaları işleyen ayrı araçlardır. Hangi yapılandırmayı kullanacağınıza karar verirken aşağıdakileri göz önünde bulundurun: Bir işlemci Kotlin sembol işleyici olarak kullanılabiliyorsa ksp bağımlılık olarak kullanın. Kotlin simge işleyicilerini kullanmayla ilgili ayrıntılar için kapt'den ksp'ye geçiş başlıklı makaleyi inceleyin. İşlemci Kotlin simgesi işlemcisi olarak kullanılamıyorsa: Projenizde Kotlin kaynağı varsa (Java kaynağı da dahil olabilir) kapt simgesini kullanarak kaynağı dahil edin. Projenizde yalnızca Java kaynağı kullanılıyorsa eklemek için annotationProcessor simgesini kullanın. Ek açıklama işleyicileri kullanma hakkında daha fazla bilgi için Ek açıklama işleyici ekleme başlıklı makaleyi inceleyin.
lintChecks	Android uygulama projenizi derlediğinde Gradle'ın yürütmesini istediğiniz lint kontrollerini içeren bir kitaplık eklemek için bu yapılandırmayı kullanın. lint.jar dosyası içeren AAR'ların, söz konusu lint.jar dosyasında tanımlanan kontrolleri otomatik olarak çalıştıracağını unutmayın. Açık bir lintChecks bağımlılığı eklemeniz gerekmez. Bu, kitaplıkları ve ilişkili lint kontrollerini tek bir bağımlılıkta tanımlamanıza olanak tanır. Böylece, kullanıcılar kitaplığınızı kullandığında kontrollerinizin çalıştırılmasını sağlayabilirsiniz.
lintPublish	Gradle'ın lint.jar dosyasına derlemesini ve AAR'ınıza paketlemesini istediğiniz lint kontrollerini dahil etmek için Android kitaplık projelerinde bu yapılandırmayı kullanın. Bu, AAR'ınızı kullanan projelerin bu lint kontrollerini de uygulamasına neden olur. Daha önce yayınlanan AAR'a lint kontrollerini dahil etmek için lintChecks bağımlılık yapılandırmasını kullanıyorsanız bu bağımlılıkları lintPublish yapılandırmasını kullanmak üzere taşımanız gerekir. Kotlin dependencies { // Executes lint checks from the ":checks" project at build time. lintChecks(project(":checks")) // Compiles lint checks from the ":checks-to-publish" into a // lint.jar file and publishes it to your Android library. lintPublish(project(":checks-to-publish")) } Groovy dependencies { // Executes lint checks from the ':checks' project at build time. lintChecks project(':checks') // Compiles lint checks from the ':checks-to-publish' into a // lint.jar file and publishes it to your Android library. lintPublish project(':checks-to-publish') }

Belirli bir derleme varyantı için bağımlılıkları yapılandırma

Yukarıdaki yapılandırmaların tümü, tüm derleme varyantlarına bağımlılık uygular. Bunun yerine yalnızca belirli bir derleme varyantı kaynak grubu veya test kaynak grubu için bağımlılık beyan etmek istiyorsanız yapılandırma adını büyük harfle yazmalı ve derleme varyantının veya test kaynak grubunun adıyla önek eklemelisiniz.

Örneğin, implementation yapılandırmasını kullanarak yalnızca "ücretsiz" ürün çeşidinize uzak bir ikili bağımlılık eklemek için şunları kullanın:

Kotlin

dependencies {
    freeImplementation("com.google.firebase:firebase-ads:21.5.1")
}

Groovy

dependencies {
    freeImplementation 'com.google.firebase:firebase-ads:21.5.1'
}

Ancak, bir ürün çeşidini ve derleme türünü birleştiren bir varyant için bağımlılık eklemek istiyorsanız yapılandırma adını başlatmanız gerekir:

Kotlin

// Initializes a placeholder for the freeDebugImplementation dependency configuration.
val freeDebugImplementation by configurations.creating

dependencies {
    freeDebugImplementation(project(":free-support"))
}

Groovy

configurations {
    // Initializes a placeholder for the freeDebugImplementation dependency configuration.
    freeDebugImplementation {}
}

dependencies {
    freeDebugImplementation project(":free-support")
}

Yerel testleriniz ve enstrümante edilmiş testleriniz için implementation bağımlılıkları eklemek isterseniz aşağıdaki gibi görünür:

Kotlin

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation("junit:junit:4.12")

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation("androidx.test.espresso:espresso-core:3.6.1")
}

Groovy

dependencies {
    // Adds a remote binary dependency only for local tests.
    testImplementation 'junit:junit:4.12'

    // Adds a remote binary dependency only for the instrumented test APK.
    androidTestImplementation 'androidx.test.espresso:espresso-core:3.6.1'
}

Ancak bu durumda belirli yapılandırmalar anlamlı değildir. Örneğin, diğer modüller androidTest'e bağlı olamayacağından androidTestApi yapılandırmasını kullanırsanız aşağıdaki uyarıyı alırsınız:

WARNING: Configuration 'androidTestApi' is obsolete and has been replaced with
'androidTestImplementation'.

Bağımlılık sırası

Bağımlılıklarınızı listelediğiniz sıra, her birinin önceliğini belirtir: İlk kitaplık ikinci kitaplıktan, ikinci kitaplık üçüncü kitaplıktan daha yüksek önceliğe sahiptir. Bu sıra, kitaplıklardan uygulamanıza kaynakların birleştirilmesi veya manifest öğelerinin birleştirilmesi durumunda önemlidir.

Örneğin, projenizde aşağıdakiler belirtilmişse:

• LIB_A ve LIB_B'a bağımlılık (bu sırayla)
• LIB_A ise LIB_C ve LIB_D'ye bağlıdır (bu sırayla)
• LIB_B ayrıca LIB_C'e bağlıdır.

Bu durumda, sabit bağımlılık sırası aşağıdaki gibi olur:

1. LIB_A
2. LIB_D
3. LIB_B
4. LIB_C

Bu, hem LIB_A hem de LIB_B'in LIB_C'yi geçersiz kılabilmesini sağlar. Ayrıca LIB_A (ona bağlı olduğu için) LIB_B'den daha yüksek önceliğe sahip olduğundan LIB_D, LIB_B'den daha yüksek önceliğe sahip olmaya devam eder.

Farklı proje kaynaklarından/bağımlılıklardan gelen manifest dosyalarının nasıl birleştirildiği hakkında daha fazla bilgi için Birden fazla manifest dosyasını birleştirme başlıklı makaleyi inceleyin.

Play Console için bağımlılık bilgileri

AGP, uygulamanızı oluştururken uygulamanızda derlenen kitaplık bağımlılıklarını açıklayan meta verileri ekler. Play Console, uygulamanızı yüklerken bu meta verileri inceleyerek uygulamanızın kullandığı SDK'lar ve bağımlılıklarla ilgili bilinen sorunlarla ilgili uyarılar sağlar ve bazı durumlarda bu sorunları çözmek için uygulanabilir geri bildirim sunar.

Veriler sıkıştırılır, bir Google Play imzalama anahtarıyla şifrelenir ve yayınlama uygulamanızın imzalama bloğunda depolanır. Güvenli ve olumlu bir kullanıcı deneyimi için bu bağımlılık dosyasını saklamanızı öneririz. Modülünüzün build.gradle.kts dosyasına aşağıdaki dependenciesInfo bloğunu ekleyerek bu özelliği devre dışı bırakabilirsiniz.

android {
    dependenciesInfo {
        // Disables dependency metadata when building APKs.
        includeInApk = false
        // Disables dependency metadata when building Android App Bundles.
        includeInBundle = false
    }
}

Politikalarımız ve bağımlılıklarla ilgili olası sorunlar hakkında daha fazla bilgi için uygulamanızda üçüncü taraf SDK'ları kullanma konulu destek sayfamıza göz atın.

SDK analizleri

Android Studio, aşağıdaki sorunlar geçerli olduğunda sürüm kataloğu dosyasında ve Google Play SDK Dizini'ndeki herkese açık SDK'lar için Proje Yapısı İletişim Kutusu'nda lint uyarıları gösterir:

• SDK'lar, yazarları tarafından güncel olmadığı şekilde işaretlenir.
• SDK'lar Play politikalarını ihlal ediyor.

Bu uyarılar, eski sürümlerin kullanılmasının gelecekte Google Play Console'da yayınlamanızı engelleyebileceği için bu bağımlılıkları güncellemeniz gerektiğini gösterir.

Sürüm katalogları olmadan derleme bağımlılıkları ekleme

Bağımlılıklar eklemek ve yönetmek için sürüm kataloglarını kullanmanızı öneririz ancak basit projelerde bunlara ihtiyaç duyulmayabilir. Sürüm kataloglarını kullanmayan bir derleme dosyası örneği aşağıda verilmiştir:

Kotlin

plugins {
    id("com.android.application")
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation("com.example.android:app-magic:12.3")
    // Dependency on a local library module
    implementation(project(":mylibrary"))
}

Groovy

plugins {
    id 'com.android.application'
}

android { ... }

dependencies {
    // Dependency on a remote binary
    implementation 'com.example.android:app-magic:12.3'
    // Dependency on a local library module
    implementation project(':mylibrary')
}

Bu derleme dosyası, "com.example.android" ad alanını içeren gruptaki "app-magic" kitaplığının 12.3 sürümüne bağımlılık belirtir. Uzak ikili bağımlılık beyanı aşağıdakilerin kısaltmasıdır:

Kotlin

implementation(group = "com.example.android", name = "app-magic", version = "12.3")

Groovy

implementation group: 'com.example.android', name: 'app-magic', version: '12.3'

Derleme dosyası ayrıca "mylibrary" adlı bir Android kitaplık modülüne bağımlılık da bildirir. Bu ad, settings.gradle.kts dosyanızda include: ile tanımlanan kitaplık adıyla eşleşmelidir. Uygulamanızı derlediğinizde derleme sistemi, kitaplık modülünü derler ve derlenen içeriği uygulamaya paketler.

Derleme dosyası, Android Gradle eklentisine (com.application.android) de bağımlılık bildirir. Aynı eklentiyi kullanan birden fazla modülünüz varsa tüm modüller genelinde derleme sınıf yolu için eklentinin yalnızca tek bir sürümüne sahip olabilirsiniz. Modül derleme komut dosyalarının her birinde sürümü belirtmek yerine, eklenti bağımlılığını kök derleme komut dosyasına sürümle birlikte eklemeniz ve uygulanmamasını belirtmeniz gerekir. apply false eklemek, Gradle'e eklenti sürümünü not etmesini ancak kök derlemede kullanmamasını söyler. Kök derleme komut dosyası genellikle bu plugins bloğu dışında boştur.

Kotlin

plugins {
    id("org.jetbrains.kotlin.android") version "1.9.0" apply false
}

Groovy

plugins {
    id ‘com.android.application’ version ‘8.3.0-rc02’ apply false
}

Tek modüllü bir projeniz varsa sürümü modül düzeyindeki derleme komut dosyasında açıkça belirtebilir ve proje düzeyindeki derleme komut dosyasını boş bırakabilirsiniz:

Kotlin

plugins {
    id("com.android.application") version "8.3.0"
}

Groovy

plugins {
    id 'com.android.application' version '8.3.0-rc02'
}