Android kitaplığı oluşturma

Android kitaplıkları, yapısal olarak Android uygulama modülleriyle aynıdır. Kaynak kod, kaynak dosyalar ve Android manifesti dahil olmak üzere uygulama oluşturmak için gereken her şeyi içerir.

Ancak Android kitaplıkları, cihazda çalışan bir APK yerine Android uygulama modülü için bağımlı olarak kullanabileceğiniz bir Android Arşivi (AAR) dosyasına derlenir. JAR dosyalarının aksine, AAR dosyaları Android uygulamaları için aşağıdaki işlevleri sunar:

  • AAR dosyaları Android kaynakları ve bir manifest dosyası içerebilir. Bu sayede Kotlin veya Java sınıf ve yöntemlerinin yanı sıra düzenler ve çizilebilir öğeler gibi paylaşılan kaynakları da paketleyebilirsiniz.
  • AAR dosyaları, uygulama modülünün C/C++ kodu tarafından kullanılacak C/C++ kitaplıkları içerebilir.

Kitaplık modülü aşağıdaki durumlarda yararlıdır:

  • Etkinlikler, hizmetler veya kullanıcı arayüzü düzenleri gibi bazı ortak bileşenleri kullanan birden fazla uygulama oluştururken
  • Temel bileşenleri paylaşan birden fazla APK varyantında (ör. ücretsiz ve ücretli sürüm) bulunan bir uygulama oluştururken

Her iki durumda da, yeniden kullanmak istediğiniz dosyaları bir kitaplık modülüne taşıyın ve ardından kitaplığı her uygulama modülü için bağımlılık olarak ekleyin.

Bu sayfada, Android kitaplık modülünün nasıl oluşturulacağı ve kullanılacağı açıklanmaktadır. Kitaplığınızı yayınlama hakkında bilgi edinmek için Kitaplığınızı yayınlama başlıklı makaleyi inceleyin.

Kitaplık modülü oluşturma

Projenizde yeni bir kitaplık modülü oluşturmak için aşağıdaki adımları uygulayın:

  1. Dosya > Yeni > Yeni Modül'ü tıklayın.
  2. Görüntülenen Yeni Modül Oluştur iletişim kutusunda Android Kitaplığı'nı, ardından İleri'yi tıklayın.

    Geleneksel JAR dosyası oluşturan bir Kotlin veya Java kitaplığı oluşturma seçeneği de vardır. JAR dosyaları birçok proje için faydalıdır (özellikle de kodları diğer platformlarla paylaşmak istediğinizde). Ancak Android projelerinde kodları yeniden kullanmak için çok faydalı olan Android kaynaklarını veya manifest dosyalarını eklemenize izin vermez. Bu kılavuzda Android kitaplıkları oluşturma üzerinde durulur.

  3. Kitaplığınıza bir ad verin ve kitaplıktaki kod için minimum SDK sürümünü seçin, ardından Son'u tıklayın.

Gradle proje senkronizasyonu tamamlandıktan sonra kitaplık modülü Proje bölmesinde görünür. Yeni modül klasörünü görmüyorsanız bölmede Android görünümünün gösterildiğinden emin olun.

Uygulama modülünü kitaplık modülüne dönüştürme

Yeniden kullanmak istediğiniz kodu içeren mevcut bir uygulama modülünüz varsa aşağıdaki adımları uygulayarak kitaplık modülüne dönüştürebilirsiniz:

  1. Groovy kullanıyorsanız modül düzeyindeki build.gradle dosyasını, Kotlin komut dosyası kullanıyorsanız build.gradle.kts dosyasını açın.
  2. applicationId satırını silin. Bunu yalnızca bir Android uygulama modülü tanımlayabilir.
  3. Dosyanın üst kısmında şuna benzer bir şekilde görünen "plugins" bloğunu bulun:

    Groovy

      plugins {
      id 'com.android.application'
  }

    Kotlin

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

    Aşağıdaki şekilde değiştirin:

    Groovy

      plugins {
      id 'com.android.library'
  }

    Kotlin

      plugins {
      id("com.android.library")
  }
  4. Dosyayı kaydedip Dosya > Projeyi Gradle Dosyalarıyla Senkronize Et'i tıklayın.

Modülün yapısı aynı kalır ancak artık Android kitaplığı olarak çalışır. Derleme, APK yerine bir AAR dosyası oluşturur.

AAR dosyasını derlemek istediğinizde Proje penceresinde kitaplık modülünü seçin ve Derle > APK Oluştur'u tıklayın.

Proje Yapısı iletişim kutusuyla bağımlılık ekleme

Projenize bağımlılık eklemek için Proje Yapısı iletişim kutusunu kullanabilirsiniz. Aşağıdaki bölümlerde, bağımlılıkları eklemek için iletişim kutusunun nasıl kullanılacağı açıklanmaktadır.

Kitaplığınızı aynı projeden kullanma

Yeni Android kitaplığınızın kodunu aynı projedeki başka bir uygulamada veya kitaplık modülünde kullanmak için proje düzeyinde bir bağımlılık ekleyin:

  1. Dosya > Proje Yapısı > Bağımlılıklar'a gidin.
  2. Kitaplığı eklemek istediğiniz modülü seçin.
  3. Belirtilen Bağımlılıklar sekmesinde simgesini tıklayın ve menüden Modül Bağımlılığı'nı seçin.

  4. Modül Bağımlılığı Ekle iletişim kutusunda kitaplık modülünüzü seçin.

    Proje Yapısı iletişim kutusunda modül bağımlılığı ekleme

  5. Bu bağımlılığı gerektiren yapılandırmayı seçin veya tüm yapılandırmalar için geçerliyse uygulamayı seçin, ardından Tamam'ı tıklayın.

Android Studio, bağımlılığı eklemek için modülünüzün build.gradle veya build.gradle.kts dosyasını aşağıdaki biçimde düzenler:

Groovy

  implementation project(path: ":example-library")

Kotlin

  implementation(project(":example-library"))

Kitaplığınızı diğer projelerde kullanma

Bağımlılıkları (JAR ve AAR) paylaşmanın önerilen yolu, Maven Central gibi bir hizmette barındırılan bir Maven deposu veya yerel diskinizdeki bir dizin yapısıdır. Maven depolarını kullanma hakkında daha fazla bilgi için Uzak depolar başlıklı makaleyi inceleyin.

Bir Android kitaplığı Maven deposunda yayınlandığında, kitaplığın bağımlılarının kitaplığı kullanan derlemeye dahil edilmesi için meta veriler eklenir. Bu, kitaplığın birden fazla yerde kullanılması durumunda otomatik olarak tekilleştirilmesini sağlar.

Android kitaplığınızdaki kodu farklı bir projedeki başka bir uygulama modülünde kullanmak için aşağıdaki adımları uygulayın:

  1. Dosya > Proje Yapısı > Bağımlılıklar'a gidin.
  2. Beyan Edilen Bağımlılıklar sekmesinde simgesini tıklayın ve menüden Kitaplık Bağımlılığı'nı seçin.

  3. Kitaplık Bağımlılığı Ekle iletişim kutusunda, eklemek istediğiniz kitaplığı bulmak için arama kutusunu kullanın. Bu form, settings.gradle veya settings.gradle.kts dosyasında dependencyResolutionManagement { repositories {...}} bloğunda belirtilen depoları arar.

    Proje Yapısı iletişim kutusunda kitaplık bağımlılığı ekleme

  4. Bu bağımlılığı gerektiren yapılandırmayı seçin veya tüm yapılandırmalar için geçerliyse uygulamayı seçin, ardından Tamam'ı tıklayın.

Aşağıdakine benzer bir beyanın göründüğünü onaylamak için uygulamanızın build.gradle veya build.gradle.kts dosyasını kontrol edin (seçtiğiniz derleme yapılandırmasına bağlı olarak):

Groovy

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

  implementation("com.example:examplelibrary:1.0.0")

AAR veya JAR dosyanızı bağımlılık olarak ekleme

Android kitaplığınızın kodunu başka bir uygulama modülünde kullanmak için aşağıdaki adımları uygulayın:

  1. Dosya > Proje Yapısı > Bağımlılıklar'a gidin.
  2. Beyan Edilen Bağımlılıklar sekmesinde simgesini tıklayın ve menüden Jar Bağımlılığı'nı seçin.

  3. Jar/Aar Bağımlılığı Ekle iletişim kutusunda AAR veya JAR dosyanızın yolunu girin, ardından bağımlılığın geçerli olduğu yapılandırmayı seçin. Kitaplığın tüm yapılandırmalarda kullanılabilmesi gerekiyorsa uygulama yapılandırmasını seçin.

    Proje Yapısı iletişim kutusuna AAR bağımlılığı ekleme

    Aşağıdakine benzer bir beyanın göründüğünü onaylamak için uygulamanızın build.gradle veya build.gradle.kts dosyasını kontrol edin (seçtiğiniz derleme yapılandırmasına bağlı olarak):

    Groovy

      implementation files('my_path/my_lib.aar')

    Kotlin

      implementation(files("my_path/my_lib.aar"))

Android Studio dışında çalışan Gradle derlemesine bir bağımlılık içe aktarmak için uygulamanızın build.gradle veya build.gradle.kts dosyasına bağımlılık yolunu ekleyin. Örnek:

Groovy

dependencies {
    implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
}

Kotlin

dependencies {
    implementation(fileTree(mapOf("dir" to "libs", "include" to listOf("*.jar", "*.aar"))))
}

Gradle bağımlılıkları ekleme hakkında daha fazla bilgi için Derleme bağımlılıkları ekleme başlıklı makaleyi inceleyin.

Herkese açık bir kaynak beyan etme

Kaynaklar, projenizin res/ dizinindeki tüm dosyaları (ör. resimler) içerir. Kitaplıktaki tüm kaynaklar varsayılan olarak herkese açıktır. Tüm kaynakları dolaylı olarak özel yapmak için en az bir özelliği herkese açık olarak tanımlamanız gerekir.

Herkese açık bir kaynağı bildirmek için kitaplığınızın public.xml dosyasına bir <public> beyanı ekleyin. Daha önce herkese açık kaynak eklemediyseniz kitaplığınızın res/values/ dizininde public.xml dosyasını oluşturmanız gerekir.

Aşağıdaki örnek kod, mylib_app_name ve mylib_public_string adlarıyla iki herkese açık dize kaynağı oluşturur:

<resources>
    <public name="mylib_app_name" type="string"/>
    <public name="mylib_public_string" type="string"/>
</resources>

Kitaplığınızdaki kullanıcıların yalnızca şirket içinde kullanılmak üzere tasarlanmış kaynaklara erişmesini önlemek için bir veya daha fazla herkese açık kaynak tanımlayarak bu otomatik gizlilik atama mekanizmasını kullanın. Alternatif olarak, boş bir <public /> etiketi ekleyerek tüm kaynakları gizli hale getirebilirsiniz. Bu işlem hiçbir şeyi herkese açık olarak işaretlemez ve tüm kaynakları özel yapar.

Kitaplığınızı kullanan geliştiricilerin görebileceği tüm kaynaklar herkese açık olmalıdır.

Özellikleri örtülü olarak gizli hale getirmek, kitaplığınızdaki kullanıcıların dahili kitaplık kaynaklarından kod tamamlama önerileri almasını engeller ve kullanıcıların kitaplığınızdaki istemcileri bozmadan özel kaynakları yeniden adlandırmasına veya kaldırmasına olanak tanır. Gizli kaynaklar kod tamamlama işleminde filtrelenir ve gizli bir kaynağa referans vermeye çalıştığınızda lint aracı sizi uyarır.

Android Gradle eklentisi, kitaplık oluştururken herkese açık kaynak tanımlarını alır ve bunları public.txt dosyasına çıkarır. Bu dosya daha sonra AAR dosyasına paketlenir.

Kitaplık modülleri için geliştirmeyle ilgili dikkat edilmesi gereken noktalar

Kitaplık modüllerinizi ve bağımlı uygulamalarınızı geliştirirken aşağıdaki davranışlara ve sınırlamalara dikkat edin.

  • Kitaplıklar, öncelik sırasına göre birleştirilir.

    Android uygulama modülünüze kitaplık modüllerine referanslar ekledikten sonra bunların göreceli önceliğini ayarlayabilirsiniz. Derleme sırasında, öncelik sırasına göre en düşükten en yükseğe doğru kütüphaneler uygulamayla tek tek birleştirilir.

  • Kaynak birleştirme çakışmalarını önleyin.

    Derleme araçları, bir kitaplık modülündeki kaynakları bağımlı uygulama modülündeki kaynaklarla birleştirir. Belirli bir kaynak kimliği her iki modülde de tanımlanmışsa uygulamadaki kaynak kullanılır.

    Birden fazla AAR kitaplığı arasında çakışma meydana gelirse bağımlılık listesinde ilk listelenen kitaplıktaki (dependencies bloğunun en üstüne en yakın olan) kaynak kullanılır.

    Kaynak çakışmalarını önlemek için geçişsiz R sınıfları kullanın. Bu mümkün değilse ön ek veya modüle özgü (veya tüm proje modülleri arasında benzersiz) tutarlı bir adlandırma şeması kullanmayı düşünün.

  • Çok modüllü derlemelerde JAR bağımlılıkları geçişli bağımlılık olarak değerlendirilir.

    AAR çıkışı veren bir kitaplık projesine JAR bağımlılığı eklediğinizde JAR, kitaplık modülü tarafından işlenir ve AAR ile birlikte paketlenir.

    Ancak projenizde bir uygulama modülü tarafından kullanılan bir kitaplık modülü varsa uygulama modülü, kitaplığın yerel JAR bağımlılığını geçişli bağımlılık olarak değerlendirir. Bu durumda yerel JAR, kütüphane modülü tarafından değil, onu kullanan uygulama modülü tarafından işlenir. Bu, kitaplığın kodunda yapılan değişikliklerden kaynaklanan artımlı derlemeleri hızlandırır.

    Yerel JAR bağımlılıklarından kaynaklanan Java kaynak çakışmaları, kitaplığı kullanan uygulama modülünde çözülmesi gerekir.

  • Kitaplık modülü, harici bir JAR kitaplığına bağlı olabilir.

    Harici bir kitaplığa bağımlı bir kitaplık modülü geliştirebilirsiniz. Bu durumda, bağımlı modül harici kitaplığı içeren bir hedefe göre derlenmelidir.

    Hem kitaplık modülünün hem de bağımlı uygulamanın, harici kitaplığı manifest dosyalarında <uses-library> öğesinde belirtmesi gerektiğini unutmayın.

  • Uygulama modülünün minSdkVersion değeri, kitaplıkta tanımlanan sürümle aynı veya bu sürümden daha yüksek olmalıdır.

    Kitaplıklar, bağımlı uygulama modülünün bir parçası olarak derlenir. Bu nedenle, kitaplık modülünde kullanılan API'ler, uygulama modülünün desteklediği platform sürümüyle uyumlu olmalıdır.

  • Her kitaplık modülü kendi R sınıfını oluşturur.

    Bağımlı uygulama modüllerini derlediğinizde kitaplık modülleri bir AAR dosyasında derlenir ve ardından uygulama modülüne eklenir. Bu nedenle, her kitaplığın kendi R sınıfı vardır ve bu sınıf, kitaplığın paket adına göre adlandırılır.

    Ana modül ve kitaplık modülünden oluşturulan R sınıfı, ana modülün paketi ve kitaplıkların paketleri dahil olmak üzere gereken tüm paketlerde oluşturulur.

  • Kitaplık modülleri kendi ProGuard yapılandırma dosyalarını içerebilir.

    AAR derlemek ve yayınlamak için kullandığınız bir kitaplık projeniz varsa kitaplığınızın derleme yapılandırmasına ProGuard yapılandırma dosyası ekleyebilirsiniz. Bu durumda Android Gradle eklentisi, belirttiğiniz ProGuard kurallarını uygular. Derleme araçları bu dosyayı kitaplık modülü için oluşturulan AAR dosyasına yerleştirir. Kitaplığı bir uygulama modülüne eklediğinizde kitaplığın ProGuard dosyası, uygulama modülünün ProGuard yapılandırma dosyasına (proguard.txt) eklenir.

    Kitaplık modülünüze bir ProGuard dosyası yerleştirerek, kitaplığınıza bağımlı uygulama modüllerinin kitaplığınızı kullanmak için ProGuard dosyalarını manuel olarak güncellemesi gerekmediğinden emin olursunuz. Android Studio derleme sistemi, uygulamanızı derlediğinde hem uygulama modülündeki hem de kitaplıktaki talimatları kullanır. Bu nedenle, kitaplıkta ayrı bir adımda kod sıkıştırıcı çalıştırmanız gerekmez.

    ProGuard kurallarını kitaplık projenize eklemek için kitaplığınızın build.gradle veya build.gradle.kts dosyasının defaultConfig bloğunda consumerProguardFiles mülküyle dosyanın adını belirtin.

    Örneğin, aşağıdaki snippet'te lib-proguard-rules.txt, kitaplığın ProGuard yapılandırma dosyası olarak ayarlanmıştır:

    Groovy

    android {
    defaultConfig {
        consumerProguardFiles 'lib-proguard-rules.txt'
    }
    ...
}

    Kotlin

    android {
    defaultConfig {
        consumerProguardFiles("lib-proguard-rules.txt")
    }
    ...
}

    Ancak kitaplık modülünüz, APK olarak derlenen ve AAR oluşturmayan çok modüllü bir derlemenin parçasıysa yalnızca kitaplığı kullanan uygulama modülünde kod küçültme işlemini çalıştırın. ProGuard kuralları ve kullanımları hakkında daha fazla bilgi edinmek için Uygulamanızı küçültme, karartma ve optimize etme başlıklı makaleyi okuyun.

  • Kitaplık modülünü test etmek, uygulamayı test etmekle neredeyse aynıdır.

    Temel fark, kitaplığın ve bağımlılıklarının test APK'sının bağımlılıklarına otomatik olarak dahil edilmesidir. Bu, test APK'sının yalnızca kendi kodunu değil, kitaplığın AAR'ını ve tüm bağımlılıklarını da içerdiği anlamına gelir. Test altında ayrı bir uygulama olmadığından androidTest görevi yalnızca test APK'sını yükler (ve kaldırır).

    Birden fazla manifest dosyasını birleştirirken Gradle, varsayılan öncelik sırasını uygular ve kitaplığın manifestini test APK'sının ana manifestiyle birleştirir.

AAR dosyasının anatomisi

AAR dosyasının dosya uzantısı .aar, Maven yapı türü de aar'dur. Dosya bir ZIP dosyasıdır. Yalnızca /AndroidManifest.xml zorunlu giriştir.

AAR dosyası, aşağıdaki isteğe bağlı girişlerden birini veya daha fazlasını da içerebilir: