Derleme bağımlılıkları ekleme

Android Studio'daki Gradle derleme sistemi, derlemenize bağımlılık olarak harici ikili programlar veya diğer kitaplık modüllerini eklemenize olanak tanır. Bağımlılıklar makinenizde veya uzak bir depoda bulunabilir. Bildirdikleri 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 projenizde bağımlılıkları nasıl kullanacağınız açıklanmaktadır. Gradle bağımlılıkları hakkında daha ayrıntılı kavramsal kılavuz için Bağımlılık yönetimi için Gradle rehberini de incelemeniz gerekir. Ancak Android projenizin yalnızca bu sayfada tanımlanan bağımlılık yapılandırmalarını kullanması gerektiğini unutmayın.

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

Derleme bağımlılıklarını eklemenin ve yönetmenin en iyi yolu, yeni projelerin varsayılan olarak kullandığı 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 dokümanlarına bakın. Sürüm kataloglarını kullanan bir uygulama örneği için Now in Android bölümüne bakın. Sürüm katalogları olmadan oluşturduğunuz derleme bağımlılıkları varsa ve çok modüllü bir projeniz varsa taşımanızı öneririz.

Yerel bağımlılıkları ekleme ve yönetme hakkında yardım için (yaygın değildir) Yerel bağımlılıklar bölümüne bakın.

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

  1. Sürüm kataloğu dosyasının [versions] bölümünde libs.versions.toml (Proje görünümündeki gradle dizini veya Android görünümündeki Gradle Komut Dosyaları altında) bağımlılığın istediğiniz sürümü için bir takma ad ekleyin:

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

    Takma adlar, kısa çizgi 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 kataloğun adıyla, libs.versions.toml öğesinin libs kısmıyla başlar. Tek sürüm kataloğu kullanırken varsayılan "libs" değerini korumanızı öneririz.

  2. libs.versions.toml dosyasının [libraries] (uzaktan ikili programlar veya yerel kitaplık modülleri için) veya [plugins] (eklentiler için) bölümlerinde 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 bunların sürümlerini gruplandıran, yayınlanmış bir Malzeme Listesi (BOM) kapsamındadır. 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 Listesini Kullanma bölümüne bakın.

  3. Bağımlılık gerektiren modüllerin derleme komut dosyasına bağımlılık takma adına bir referans ekleyin. Takma ada derleme komut dosyasından başvurduğunuzda takma adın alt çizgilerini ve kısa çizgilerini noktalara dönüştürün. Modül düzeyinde derleme komut dosyamız şöyle görünecektir:

    Kotlin

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

    Modern

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

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

Bağımlılıkları yapılandırın

dependencies bloğunun içinde, birkaç farklı bağımlılık yapılandırmasından birini (önceden gösterilen implementation gibi) kullanarak bir kitaplık bağımlılığı bildirebilirsiniz. Her bir bağımlılık yapılandırması, Gradle'a bu bağımlılığın nasıl kullanılacağı konusunda farklı talimatlar sunar. Aşağıdaki tabloda, Android projenizde bir bağımlılık için kullanabileceğiniz yapılandırmaların her biri açıklanmaktadır.

Yapılandırma Davranış
implementation Gradle, bu bağımlılığı derleme sınıf yoluna ekler ve bağımlılığı derleme çıkışına paketler. Modülünüz bir implementation bağımlılığını yapılandırdığında, derleme sırasında modülün bağımlılığı diğer modüllere sızdırmasını istemediğinizi Gradle'a bildirir. Diğer bir deyişle, bağımlılık mevcut modüle bağlı diğer modüller tarafından kullanılamaz.

api yerine bu bağımlılık yapılandırmasının kullanılması, derleme sisteminin yeniden derlemesi için gereken modüllerin sayısını azalttığından derleme süresinde önemli iyileştirmeler sağlayabilir. Örneğin, bir implementation bağımlılığı API'sini değiştirirse Gradle yalnızca bu bağımlılığı ve doğrudan ona bağlı olan modülleri yeniden derler. Çoğu uygulama ve test modülü bu yapılandırmayı kullanmalıdır.

api Gradle, derleme sınıf yoluna ve derleme çıkışına bağımlılığı ekler. Bir modül api bağımlılığı içerdiğinde, modülün bu bağımlılığı diğer modüllere geçişli olarak dışa aktarmak istediğini Gradle'a bildirir. Böylece, hem çalışma zamanında hem de derleme zamanında bu bağımlılar tarafından kullanılabilir.

Bu yapılandırmayı dikkatli bir şekilde ve yalnızca diğer yukarı akış müşterilerine geçişli olarak aktarmanız gereken bağımlılıklarla kullanın. Bir api bağımlılığı 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ığının olması, derleme süresini önemli ölçüde artırabilir. Bir bağımlılığın API'sini ayrı bir modüle göstermek istemediğiniz sürece 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 yoluna ekler (yani derleme çıkışına eklenmez). Bu özellik, bir Android modülü oluşturduğunuzda ve derleme sırasında bağımlılığa ihtiyacınız olduğunda yararlı olur ancak çalışma zamanında mevcut olması isteğe bağlıdır. Örneğin, yalnızca derleme zamanı ek açıklamalarının bulunduğu bir kitaplığa bağımlıysanız (genellikle kod oluşturmak için kullanılır ancak genellikle derleme çıkışına dahil edilmez) bu kitaplığı compileOnly olarak işaretleyebilirsiniz.

Bu yapılandırmayı kullanırsanız kitaplık modülünüz, bağımlılığın mevcut olup olmadığını kontrol etmek için bir çalışma zamanı koşulu içermelidir. Ardından, sağlanmadığı durumlarda da çalışabilmesi için davranışını incelikle değiştirmelidir. Bu, kritik olmayan geçici bağımlılıkları eklemeyerek 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, çalışma zamanında kullanılmak üzere bağımlılığı yalnızca derleme çıkışına ekler. Yani derleme sınıf yoluna eklenmez. Bu, Android'de nadiren kullanılır, ancak günlük kaydı uygulamaları sağlamak için sunucu uygulamalarında yaygın olarak kullanılır. Örneğin bir kitaplık, uygulama içermeyen bir Logging API kullanabilir. Bu kitaplığın kullanıcıları, kitaplığı implementation bağımlılığı olarak ekleyebilir ve kullanılacak gerçek günlük kaydı uygulamasının kullanımı için runtimeOnly bağımlılığı dahil edebilir.
ksp
kapt
annotationProcessor

Bu yapılandırmalar, kodunuz derlenmeden önce ek açıklamaları ve diğer sembolleri işleyen kitaplıklar sağlar. Bunlar genellikle kodunuzu doğrular veya ek kod oluşturarak yazmanız gereken kodu azaltır.

Böyle bir bağımlılığı eklemek için ksp, kapt veya annotationProcessor yapılandırmalarını kullanarak ek açıklama işlemcisi sınıf yoluna eklemeniz gerekir. Bu yapılandırmaların kullanılması, derleme sınıf yolunu ek açıklama işlemcisi sınıf yolundan ayırarak derleme performansını iyileştirir. Gradle, derleme sınıf yolunda ek açıklama işlemcileri bulursa derleme süresini olumsuz etkileyen derleme önlemeyi devre dışı bırakır (Gradle 5.0 ve sonraki sürümler, derleme sınıf yolunda bulunan ek açıklama işlemcilerini yoksayar).

Android Gradle eklentisi, JAR dosyasının aşağıdaki dosyayı içermesi durumunda bağımlılığın ek açıklama işlemcisi olduğunu varsayar:

META-INF/services/javax.annotation.processing.Processor

Eklenti, derleme sınıf yolunda bulunan bir ek açıklama işlemcisi algılarsa yapı hatasına neden olur.

ksp bir Kotlin Sembol İşlemcisidir ve Kotlin derleyicisi tarafından çalıştırılır.

kapt ve apt, ek açıklamaları Kotlin veya Java derleyicileri yürütmeden önce işleyen ayrı araçlardır.

Hangi yapılandırmanın kullanılacağına karar verirken aşağıdakileri göz önünde bulundurun:

  • Kotlin Sembol İşlemcisi olarak kullanılabilen bir işlemci varsa bunu ksp bağımlılığı olarak kullanın. Kotlin Sembol İşlemcilerini kullanmayla ilgili ayrıntılar için Kapt'tan ksp'ye Geçiş bölümüne bakın.
  • İşlemci, Kotlin Simgesi İşlemci olarak kullanılamıyorsa:
    • Projeniz Kotlin kaynağı içeriyorsa (ancak Java kaynağı da içerebiliyorsa) bu kaynağı dahil etmek için kapt kullanın.
    • Projenizde yalnızca Java kaynağı kullanılıyorsa bu kaynağı eklemek için annotationProcessor kullanın.

Ek açıklama işlemcilerini kullanma hakkında daha fazla bilgi için Ek açıklama işlemcileri ekleme bölümüne bakın.

lintChecks

Gradle'ın Android uygulama projenizi oluştururken yürütmesini istediğiniz lint kontrollerini içeren kitaplığı eklemek için bu yapılandırmayı kullanın.

lint.jar dosyası içeren AAR'lerin, 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 denetimlerini tek bir bağımlılıkta tanımlamanızı sağlayarak tüketiciler kitaplığınızı kullandığında kontrollerinizin çalıştırılmasını sağlar.

lintPublish Gradle'ın AAR'nizdeki bir lint.jar dosyası ve pakette derlemesini istediğiniz lint kontrollerini eklemek için Android kitaplık projelerinde bu yapılandırmayı kullanın. Bu, AAR'nizi kullanan projelerin bu hata analizi kontrollerini de uygulamasına neden olur. Yayınlanan AAR'ye lint kontrollerini dahil etmek için daha önce lintChecks bağımlılık yapılandırmasını kullandıysanız bu bağımlılıkları taşımak yerine lintPublish yapılandırmasını kullanmanı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"))
}

Modern

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

Önceki 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 kümesi veya test kaynağı grubu için bağımlılık bildirmek isterseniz yapılandırma adını büyük harfle yazmalı ve önüne derleme varyantının veya test kaynağı kümesinin adını koymanız gerekir.

Örneğin, implementation yapılandırmasını kullanarak yalnızca "ücretsiz" ürün türünüze uzaktan ikili program bağımlılığı eklemek için şunu kullanın:

Kotlin

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

Modern

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

Ancak ürün çeşidiyle derleme türünü birleştiren bir varyant için bağımlılık eklemek isterseniz yapılandırma adını ilk kullanıma hazırlamanız gerekir:

Kotlin

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

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

Modern

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

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

Yerel ve enstrümanlı testlerinize implementation bağımlılıkları eklemek için yöntem şu şekilde 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.5.1")
}

Modern

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.5.1'
}

Ancak belirli yapılandırmalar bu durumda anlamlı olmaz. Örneğin, diğer modüller androidTest öğesine bağlı olamayacağı için 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 gösterir: İlk kitaplık ikinciden daha önceliklidir, ikincisi üçüncüden daha önceliklidir ve bu şekilde devam eder. Bu sıra, kaynakların birleştirilmesi veya kitaplıklardan uygulamanıza manifest öğelerinin birleştirilmesi durumunda önemlidir.

Örneğin, projenizde aşağıdakiler tanımlanıyorsa:

  • LIB_A ve LIB_B bağımlılıkları (bu sırayla)
  • LIB_A ise LIB_C ve LIB_D öğelerine (bu sırayla) bağlıdır
  • Ayrıca LIB_B, LIB_C aracına da bağlıdır

Ardından, 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 sayede hem LIB_A hem de LIB_B, LIB_C değerini geçersiz kılabilir. Ayrıca LIB_A (buna bağlıdır) LIB_B ile karşılaştırıldığında daha yüksek önceliğe sahip olduğundan LIB_D yine LIB_B önceliğine göre daha önceliklidir.

Farklı proje kaynaklarından/bağımlılıklarından gelen manifestlerin nasıl birleştirildiği hakkında daha fazla bilgi için Birden fazla manifest dosyasını birleştirme bölümüne bakın.

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

Uygulamanızı oluştururken AGP, uygulamanızda derlenen kitaplık bağımlılıklarını açıklayan meta veriler içerir. Play Console, uygulamanızı yüklerken bu meta verileri inceleyerek uygulamanızın kullandığı bağımlılıklar ve SDK'larla ilgili bilinen sorunlar hakkında uyarı verir ve bazı durumlarda bu sorunları çözmek için uygulanabilir geri bildirimler sağlar.

Veriler sıkıştırılır, bir Google Play imzalama anahtarıyla şifrelenir ve sürüm uygulamanızın imzalama bloğunda saklanı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 kapsam dışında kalmayı seçebilirsiniz.

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 bakın.

SDK analizleri

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

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

Uyarılar, bu bağımlılıkları güncellemeniz gerektiğini gösteren sinyallerdir. Zira eski sürümlerin kullanılması, gelecekte Google Play Console'da içerik yayınlamanızı engelleyebilir.

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 derleme dosyası örneğini burada bulabilirsiniz:

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"))
}

Modern

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ı grubu içinde "app-magic" kitaplığının 12.3 sürümüne bağımlılık bildirir. Uzak ikili program bağımlılık beyanı, aşağıdakilerin kısaltmasıdır:

Kotlin

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

Modern

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

Derleme dosyası ayrıca "mylibrary" adlı Android kitaplık modülüne bağımlılık 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 elde edilen derlenen içeriği uygulamada paketler.

Derleme dosyası ayrıca Android Gradle eklentisine (com.application.android) olan bir bağımlılığı da belirtiyor. Aynı eklentiyi kullanan birden çok modülünüz varsa tüm modüllerdeki derleme sınıfı yolunda 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ı sürümle birlikte kök derleme komut dosyasına eklemeniz ve uygulamamayı belirtmeniz gerekir. apply false eklendiğinde, Gradle'a eklentinin sürümünü not etmesini ancak kök derlemede kullanmamasını bildirir. Bu plugins bloğu hariç genellikle kök derleme komut dosyası boştur.

Kotlin

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

Modern

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"
}

Modern

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