Android kitaplığı oluşturma

Android kitaplığı yapısal olarak Android uygulama modülüyle aynıdır. Bir uygulama oluşturmak için gereken her şeyi içerir. Buna kaynak kodu, kaynak dosyaları ve Android manifesti de dahildir.

Ancak, bir cihazda çalışan APK'da derleme yapmak yerine, Android kitaplığı bir Android uygulama modülüne bağımlılık olarak kullanabileceğiniz bir Android Arşivi (AAR) dosyası olarak derlenir. JAR dosyalarından farklı olarak, AAR dosyaları Android uygulamaları için aşağıdaki işlevleri sunar:

  • AAR dosyaları, Android kaynaklarını ve bir manifest dosyasını içerebilir. Böylece, Kotlin veya Java sınıfları ve yöntemlerinin yanı sıra düzenler ve çekilebilir kaynaklar gibi paylaşılan kaynaklarda paket oluşturabilirsiniz.
  • AAR dosyaları, uygulama modülünün C/C++ kodu tarafından kullanılmak üzere 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 aynı bileşenleri kullanan birden fazla uygulama oluştururken
  • Temel bileşenleri paylaşan, ücretsiz ve ücretli sürüm gibi birden fazla APK varyasyonunda 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ık yayınlama konusunda yardım için Kitaplığınızı yayınlama bölümüne bakın.

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ı ve ardından İleri'yi tıklayın.

    Dilerseniz geleneksel bir JAR dosyası oluşturan Kotlin veya Java kitaplığı oluşturma seçeneğiniz de vardır. JAR dosyaları birçok proje için kullanışlı olsa da (özellikle de kodu diğer platformlarla paylaşmak istediğinizde) Android kaynakları veya manifest dosyalarını eklemenize izin vermez. Bu da kodun Android projelerinde yeniden kullanılması açısından oldukça kullanışlıdır. Bu kılavuzda, Android kitaplıkları oluşturmaya odaklanılmaktadır.

  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.

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

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

  1. Groovy kullanıyorsanız modül düzeyindeki build.gradle dosyasını veya Kotlin komut dosyası kullanıyorsanız build.gradle.kts dosyasını açın.
  2. applicationId hattını silin. Bunu yalnızca bir Android uygulama modülü tanımlayabilir.
  3. Dosyanın en üstünde aşağıdakine benzer "eklentiler" bloğunu bulun:

    Modern

      plugins {
          id 'com.android.application'
      }
      

    Kotlin

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

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

    Modern

      plugins {
          id 'com.android.library'
      }
      

    Kotlin

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

Modülün yapısı değişmemiştir ancak şu anda bir Android kitaplığı olarak çalışmaktadır. Derleme bir APK yerine AAR dosyası oluşturur.

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

Proje Yapısı iletişim kutusunu kullanarak 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ık eklemek için iletişim kutusunun nasıl kullanılacağı açıklanmaktadır.

Kitaplığınızı aynı proje içinde kullanma

Yeni Android kitaplığınızın kodunu aynı proje içinde başka bir uygulama veya kitaplık modülünde kullanmak için proje düzeyinde 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. Bildirilen Bağımlılıklar sekmesinde simgesini tıklayıp menüden Modül Bağımlılığı'nı seçin.

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

    Proje Yapısı İletiş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 uygulama'yı seçip 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:

Modern

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

Kotlin

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

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

Bağımlılıkları (JAR'lar ve AAR'ler) paylaşmak için önerilen yol, Maven Central gibi bir hizmette barındırılan bir Maven deposu veya yerel diskinizde bir dizin yapısı oluşturmaktır. Maven depolarını kullanma hakkında daha fazla bilgi için Uzak depolar bölümünü inceleyin.

Bir Android kitaplığı Maven deposunda yayınlandığında, kitaplığın bağımlılıklarının tüketen derlemeye dahil edilmesi için meta veriler dahil edilir. Böylece, kitaplık birden fazla yerde kullanılıyorsa kitaplığı otomatik olarak tekilleştirilir.

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

  1. Dosya > Proje Yapısı > Bağımlılıklar'a gidin.
  2. Belirtilen Bağımlılıklar sekmesinde öğesini tıklayıp menüden Kitaplık Bağımlılığı'nı seçin.

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

    Proje Yapısı İletişim Kutusuna 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 uygulama'yı seçip Tamam'ı tıklayın.

Uygulamanızın build.gradle veya build.gradle.kts dosyasını kontrol ederek aşağıdakine benzer bir bildirimin göründüğünü onaylayın (seçtiğiniz derleme yapılandırmasına bağlı olarak):

Modern

  implementation 'com.example:examplelibrary:1.0.0'

Kotlin

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

AAR veya JAR'ınızı bağımlılık olarak ekleyin

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. Belirtilen Bağımlılıklar sekmesinde simgesini tıklayıp menüden Jar Bağımlılığı'nı seçin.

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

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

    Uygulamanızın build.gradle veya build.gradle.kts dosyasını kontrol ederek aşağıdakine benzer bir bildirimin göründüğünü onaylayın (seçtiğiniz derleme yapılandırmasına bağlı olarak):

    Modern

      implementation files('my_path/my_lib.aar')
    

    Kotlin

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

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

Modern

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 bölümüne bakın.

Genel kaynak bildirin

Kaynaklar, projenizin res/ dizinindeki resimler gibi tüm dosyaları içerir. Kitaplıktaki tüm kaynaklar varsayılan olarak herkese açıktır. Tüm kaynakları dolaylı olarak gizli hale getirmek için en az bir belirli ö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 <public> bildirimi ekleyin. Daha önce herkese açık kaynaklar eklemediyseniz public.xml dosyasını kitaplığınızın res/values/ dizininde oluşturmanız gerekir.

Aşağıdaki örnek kod, mylib_app_name ve mylib_public_string adında 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 dahili kullanıma yönelik kaynaklara erişmesini engellemek için bir veya daha fazla herkese açık kaynak bildirerek bu otomatik özel tanımlama 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ı gizli hale getirir.

Kitaplığınızı kullanan geliştiricilerin görmesini istediğiniz tüm kaynaklar herkese açık hale getirilmelidir.

Özniteliklerin üstü kapalı olması, kitaplığınızın kullanıcılarının dahili kitaplık kaynaklarından kod tamamlama önerileri almasını engeller ve kullanıcıların, kitaplığınızın istemcilerini bozmadan özel kaynakları yeniden adlandırmasına veya kaldırmasına olanak tanır. Özel kaynaklar filtrelenerek kod tamamlamasının dışında bırakılır ve lint aracı, özel bir kaynağa referans vermeye çalıştığınızda sizi uyarır.

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

Kütüphane modüllerini geliştirmeyle ilgili dikkat edilmesi gereken noktalar

Kitaplık modüllerinizi ve bağımlı uygulamalarınızı geliştirirken aşağıdaki davranış ve sınırlamaları göz önünde bulundurun.

  • 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öreli önceliklerini ayarlayabilirsiniz. Derleme sırasında kitaplıklar, en düşük öncelikli olandan en yüksek öncelikli olana doğru teker teker uygulamayla birleştirilir.

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

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

    Birden fazla AAR kitaplığı arasında çakışma oluşursa bağımlılıklar listesinde ilk sırada (dependencies bloğunun en üstüne en yakın) listelenen kitaplıktaki kaynak kullanılır.

    Kaynak çakışmalarını önlemek için geçişsiz R sınıflarını kullanın. Bu mümkün değilse modüle özel (veya tüm proje modüllerinde benzersiz) bir önek veya tutarlı başka bir adlandırma düzeni kullanabilirsiniz.

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

    AAR oluşturan bir kitaplık projesine JAR bağımlılığı eklediğinizde, JAR, kitaplık modülü tarafından işlenir ve AAR'si ile paketlenir.

    Bununla birlikte, projenizde uygulama modülü tarafından kullanılan bir kitaplık modülü bulunuyorsa uygulama modülü, kitaplığın yerel JAR bağımlılığını geçişli bir bağımlılık olarak değerlendirir. Bu durumda yerel JAR, kitaplık modülü tarafından değil, onu kullanan uygulama modülü tarafından işlenir. Böylece kitaplık kodunda yapılan değişikliklerden kaynaklanan artımlı derlemeler hızlanır.

    Yerel JAR bağımlılıklarının neden olduğu tüm Java kaynak çakışmaları, kitaplığı kullanan uygulama modülünde çözülmelidir.

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

    Harici bir kitaplığa bağlı bir kitaplık modülü geliştirebilirsiniz. Bu durumda bağımlı modülün harici kitaplığı içeren bir hedef üzerinde derlemesi gerekir.

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

  • Uygulama modülünün minSdkVersion özelliği, kitaplık tarafından tanımlanan sürüme eşit veya bundan daha büyük olmalıdır.

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

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

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

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

  • Bir kitaplık modülü kendi ProGuard yapılandırma dosyasını içerebilir.

    AAR oluşturmak ve yayınlamak için kullandığınız bir kitaplık projeniz varsa kitaplığınızın derleme yapılandırmasına bir ProGuard yapılandırma dosyası ekleyebilirsiniz. Bunu yaparsanız 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ğlı uygulama modüllerinin, kitaplığınızı kullanmak için ProGuard dosyalarını manuel olarak güncellemesinin gerekmediğinden emin olmanıza yardımcı olursunuz. Android Studio derleme sistemi uygulamanızı derlerken hem uygulama modülündeki hem de kitaplıktaki yönergeleri kullanır. Dolayısıyla kitaplıkta ayrı bir adımda kod küçültücü çalıştırmanıza gerek yoktur.

    Kitaplık projenize ProGuard kurallarını eklemek için dosyanın adını, kitaplığınızın build.gradle veya build.gradle.kts dosyasındaki defaultConfig bloğundaki consumerProguardFiles özelliğiyle belirtin.

    Örneğin, aşağıdaki snippet lib-proguard-rules.txt öğesini kitaplığın ProGuard yapılandırma dosyası olarak ayarlar:

    Modern

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

    Kotlin

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

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

  • Bir 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 otomatik olarak test APK'sının bağımlılıkları olarak dahil edilmesidir. Yani test APK'sı yalnızca kendi kodunu değil, aynı zamanda kitaplığın AAR'sini ve tüm bağımlılıklarını da içerir. Test edilen ayrı bir uygulama olmadığından, androidTest görevi yalnızca test APK'sını yükler (ve kaldırır).

    Gradle, birden fazla manifest dosyasını birleştirirken 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 şeklindedir ve Maven yapısı türü de aar şeklindedir. Dosyanın kendisi bir ZIP dosyasıdır. Tek zorunlu giriş /AndroidManifest.xml.

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