Android kitaplığı oluşturma

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

Ancak bir cihazda çalışan bir APK'ya derlenmek yerine, Android kitaplığı bir Android Arşivi (AAR) dosyasına derlenir. Bu dosyayı bir Android uygulama modülü için bağımlılık olarak kullanabilirsiniz. JAR dosyalarından farklı olarak, AAR dosyaları Android uygulamaları için aşağıdaki işlevleri sunar:

  • AAR dosyaları, Kotlin veya Java sınıfları ve yöntemlerinin yanı sıra düzenler ve çizilebilir öğeler gibi paylaşılan kaynakları paketlemenize olanak tanıyan bir manifest dosyası ve Android kaynakları içerebilir.
  • 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 bazı bileşenleri aynı olan birden fazla uygulama oluştururken
  • Temel bileşenleri paylaşan ücretsiz ve ücretli sürüm gibi birden fazla APK varyantı olan 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 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 bir JAR dosyası oluşturan Kotlin veya Java kitaplığı oluşturma seçeneği de vardır. JAR dosyası, özellikle kodu diğer platformlarla paylaşmak istediğinizde birçok proje için yararlı olsa da Android kaynaklarını veya manifest dosyalarını eklemenize izin vermez. Bu dosyalar, Android projelerinde kodun yeniden kullanılması açısından çok faydalıdır. Bu kılavuz, Android kitaplıkları oluşturmaya odaklanmaktadır.

  3. Kitaplığınıza bir ad verin ve kitaplıktaki kod için minimum SDK sürümünü seçin, ardından Bitir'i 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 kod içeren mevcut bir uygulama modülünüz varsa bunu aşağıdaki gibi bir 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 aşağıdaki gibi 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ı kaydedin ve File > Sync Project with Gradle Files'ı (Dosya > Projeyi Gradle Dosyalarıyla Senkronize Et) tıklayın.

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

AAR dosyasını oluşturmak istediğinizde Project (Proje) penceresinde kitaplık modülünü seçip Build > Build APK'yı (Oluştur > APK Oluştur) 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çindeki 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. Declared Dependencies (Bildirilen Bağımlılıklar) sekmesinde simgesini tıklayın ve menüden Module Dependency'yi (Modül Bağımlılığı) 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ı iletişim kutusunda modül bağımlılığı ekleme

  5. Bu bağımlılığı gerektiren yapılandırmayı veya tüm yapılandırmalar için geçerliyse uygulamayı 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:

Groovy

  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şmanın önerilen yolu, Maven Central gibi bir hizmette veya yerel diskinizdeki bir dizin yapısında barındırılan bir Maven deposu kullanmaktı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ılıklarının tüketen derlemeye dahil edilmesi için meta veriler eklenir. Bu, kitaplığın birden fazla yerde kullanılması durumunda otomatik olarak yinelenen öğelerin kaldırılmasını sağlar.

Android kitaplığınızın kodunu 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. Declared Dependencies (Bildirilmiş Bağımlılıklar) sekmesinde simgesini tıklayın ve menüden Library Dependency'yi (Kitaplık Bağımlılığı) seçin.

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

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

  4. Bu bağımlılığı gerektiren yapılandırmayı veya tüm yapılandırmalar için geçerliyse uygulamayı seçip 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ğıdakileri yapın:

  1. Dosya > Proje Yapısı > Bağımlılıklar'a gidin.
  2. Declared Dependencies (Bildirilmiş Bağımlılıklar) sekmesinde simgesini tıklayın ve menüden Jar Dependency'yi (Jar Bağımlılığı) seçin.

  3. Add Jar/Aar Dependency (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 için uygulama yapılandırmasını seçin.

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

    Aşağıdakine benzer bir bildirimin 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 bağımlılık içe aktarmak için uygulamanızın build.gradle veya build.gradle.kts dosyasına bağımlılığın yolunu ekleyin. Örneğin:

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 kaynak bildirme

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ı örtülü olarak özel hale getirmek için en az bir özelliği herkese açık olarak tanımlamanız gerekir.

Herkese açık bir kaynak bildirmek için kitaplığınızın public.xml dosyasına <public> bildirimi ekleyin. Daha önce herkese açık kaynaklar 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ına sahip 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ızın kullanıcılarının yalnızca dahili kullanım için tasarlanmış kaynaklara erişmesini önlemek amacıyla, bir veya daha fazla herkese açık kaynak bildirerek bu otomatik özel atama mekanizmasını kullanın. Alternatif olarak, boş bir <public /> etiketi ekleyerek tüm kaynakları gizli yapabilirsiniz. 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örmeye devam etmesini istediğiniz tüm kaynaklar herkese açık hale getirilmelidir.

Özellikleri örtülü olarak gizli hale getirmek, 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 kod tamamlama işleminden filtrelenir ve lint aracı, özel bir kaynağa referans vermeye çalıştığınızda 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ı içinde paketlenir.

Kitaplık modülleriyle ilgili geliştirme hususları

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. Kitaplıklar, derleme sırasında en düşük öncelikli olandan en yüksek öncelikli olana doğru sırayla uygulamayla birleştirilir.

    Kitaplıktaki kaynak referansları, kitaplık kaynağını değil, birleştirilmiş kaynağı ifade eder. Aynı ada sahip kaynaklar olduğunda bir kitaplık modülü, kendi kaynaklarının uygulamanın veya diğer kitaplıkların kaynaklarına göre kullanılmasını zorunlu kılamaz.

  • 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 adı her iki modülde de tanımlanmışsa uygulamadaki kaynak kullanılır.

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

    Kaynak çakışmalarını önlemek için modüle özgü (veya tüm proje modüllerinde benzersiz) bir önek ya da başka bir tutarlı adlandırma şeması kullanmayı düşünebilirsiniz.

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

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

    Ancak projeniz bir uygulama modülü tarafından kullanılan bir kitaplık modülü içeriyorsa 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'ı kullanan uygulama modülü tarafından işlenir ve kitaplık modülü tarafından işlenmez. Bu, kitaplık kodundaki değişikliklerden kaynaklanan artımlı derlemeleri hızlandırır.

    Yerel JAR bağımlılıklarından kaynaklanan tüm Java kaynağı ç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, harici kitaplığı içeren bir hedefe göre oluşturulmalıdır.

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

  • Uygulama modülünün minSdkVersion, kitaplık tarafından tanımlanan sürümle aynı veya 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'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 oluşturduğunuzda kitaplık modülleri bir AAR dosyası halinde derlenir ve 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ü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 gereken tüm paketlerde oluşturulur.

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

    AAR oluşturup 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. 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ğlı uygulama modüllerinin kitaplığınızı kullanmak için ProGuard dosyalarını manuel olarak güncellemesi gerekmediğinden emin olabilirsiniz. Android Studio derleme sistemi uygulamanızı derlerken hem uygulama modülündeki hem de kitaplıktaki yönergeleri kullanır. Bu nedenle, kitaplıkta ayrı bir adımda kod küçültü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ğundaki consumerProguardFiles özelliğiyle dosyanın adını belirtin.

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

    Groovy

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

    Kotlin

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

    Ancak kitaplık modülünüz, bir APK'ya 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 bunların kullanımı hakkında daha fazla bilgi edinmek için Uygulamanızı küçültme, karartma ve optimize etme başlıklı makaleyi inceleyin.

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

    Aradaki temel fark, kitaplığın ve bağımlılıklarının test APK'sının bağımlılıkları olarak otomatik olarak dahil edilmesidir. Bu nedenle, test APK'sı yalnızca kendi kodunu değil, 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).

    Birden fazla manifest dosyası birleştirilirken Gradle, varsayılan öncelik sırasını izler 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ısı türü de aar'dir. Dosyanın kendisi bir ZIP dosyasıdır. Tek zorunlu giriş /AndroidManifest.xml'dır.

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