Kitaplık yazarları için optimizasyon

Kitaplık yazarı olarak, uygulama geliştiricilerin kitaplığınızı uygulamalarına kolayca entegre edebilmelerini ve yüksek kaliteli bir son kullanıcı deneyimi sunabilmelerini sağlamanız gerekir. Bu, kitaplığınızın geliştiricinin ek kurulum yapmasına gerek kalmadan Android optimizasyonuyla (R8) uyumlu olması veya kitaplığın Android'de kullanıma uygun olmayabileceğini belirten bir belge içermesi gerektiği anlamına gelir. Android'de kullanılmak üzere tasarlanan kitaplıkların, önemli uygulama optimizasyonlarını engellememesi ve ek optimizasyon şartlarına uyması çok önemlidir.

Bu doküman, yayınlanan kitaplıkların geliştiricilerine yöneliktir ancak büyük, modüler bir uygulamadaki dahili kitaplık modüllerinin geliştiricileri için de yararlı olabilir.

Uygulama geliştiriciyseniz ve Android uygulamanızı optimize etme hakkında bilgi edinmek istiyorsanız Uygulama optimizasyonunu etkinleştirme başlıklı makaleyi inceleyin. Hangi kitaplıkların kullanıma uygun olduğunu öğrenmek için Kitaplıkları akıllıca seçme başlıklı makaleyi inceleyin.

Saklama kuralı türlerini anlama

Kitaplıklarda iki farklı türde saklama kuralı kullanabilirsiniz:

  • Tüketici saklama kuralları, kitaplığın yansıttığı her şeyi saklayan kuralları belirtmelidir. Bir kitaplık, kodunu veya istemci uygulaması tarafından tanımlanan kodu çağırmak için yansıma ya da JNI kullanıyorsa bu kuralların hangi kodun saklanması gerektiğini açıklaması gerekir. Kitaplıklar, uygulama saklama kurallarıyla aynı biçimi kullanan tüketici saklama kurallarını paketlemelidir. Bu kurallar, kitaplık yapıları (AAR'ler veya JAR'lar) halinde paketlenir ve kitaplık kullanıldığında Android uygulaması optimizasyonu sırasında otomatik olarak kullanılır. Bu kurallar, build.gradle.kts (veya build.gradle) dosyanızdaki consumerProguardFiles özelliğiyle belirtilen dosyada tutulur. Daha fazla bilgi edinmek için Tüketici saklama kuralları yazma başlıklı makaleyi inceleyin.
  • Kitaplık derleme saklama kuralları, kitaplığınız derlendiğinde uygulanır. Bunlar yalnızca derleme sırasında kitaplığınızı kısmen optimize etmeye karar verirseniz gereklidir. Kitaplığın herkese açık API'sinin kaldırılmasını önlemeleri gerekir. Aksi takdirde, herkese açık API kitaplık dağıtımında yer almaz. Bu da uygulama geliştiricilerin kitaplığı kullanamayacağı anlamına gelir. Bu kurallar, build.gradle.kts (veya build.gradle) dosyanızdaki proguardFiles özelliğiyle belirtilen dosyada tutulur. Daha fazla bilgi için AAR kitaplığı derlemesini optimize etme başlıklı makaleyi inceleyin.

Optimizasyon koşulları ve yönergeleri

Kitaplıklardaki R8 yapılandırması, tüketen uygulamanın nihai ikili program boyutu ve performansı üzerinde genel bir etkiye sahiptir. Kitaplık yazarları, genel saklama kuralı en iyi uygulamalarının yanı sıra belirli şartlara uymalı ve ek yönergeleri dikkate almalıdır.

Optimizasyon koşullarına uyma

Kitaplıklardaki verimsizlik; uygulama şişkinliğine, bellek israfına, yavaş başlatmalara ve ANR'lere (Uygulama Yanıt Vermiyor hataları) önemli ölçüde katkıda bulunur. Kitaplıklar, uygulama kalitesini ve kullanıcı deneyimini önemli ölçüde düşürmemek için aşağıdaki şartları ihlal etmekten kaçınmalıdır.

  • Geniş kapsamlı veya paket genelinde saklama kuralları olmamalıdır: Kitaplığınız, kitaplığınızdaki veya başka bir kitaplıktaki kodun çoğunu saklayan geniş kapsamlı saklama kuralları içermemelidir. Geniş kapsamlı saklama kuralları, kilitlenmeleri kısa vadede çözebilir ancak kitaplığınızı kullanan tüm uygulamaların boyutunu artırır.

    Kitaplığınızdaki veya referans verilen diğer kitaplıklardaki paketler için paket genelinde saklama kuralları (ör. -keep class com.mylibrary.** {*; }) eklemeyin. Bu tür kurallar, kitaplığınızı kullanan tüm uygulamalarda bu paketlerin optimizasyonunu sınırlar.

    Kitaplığınızın kullandığı üçüncü taraf bağımlılıkları için geniş kapsamlı saklama kuralları eklemeyin (ör. -keep public class com.google.android.gms.** { *; }). Birçok harici kitaplık, kendi tüketici saklama kurallarıyla birlikte gelir. Paket genelinde bir kural eklemek, bu kuralların yerini alır ve R8'i, uygulamanın tamamında referans verilmeyen bağımlılık kodunu saklamaya zorlar.

  • Uygunsuz genel kurallar yok: -dontobfuscate veya -allowaccessmodification gibi genel seçenekleri asla kullanmayın.

  • Mümkün olduğunda yansıma yerine kod oluşturma kullanma: Mümkün olduğunda yansıma yerine kod oluşturma (codegen) kullanın. Kod oluşturma ve yansıma, programlama sırasında ortak metin kodundan kaçınmak için kullanılan yaygın yaklaşımlardır ancak kod oluşturma, R8 gibi bir uygulama optimizasyon aracıyla daha uyumludur.

    Kod oluşturma sayesinde kod, derleme işlemi sırasında analiz edilir ve değiştirilir. Derleme süresinden sonra önemli bir değişiklik yapılmadığından optimize edici, sonuçta hangi kodun gerekli olduğunu ve hangisinin güvenle kaldırılabileceğini bilir.

    Yansıma ile kod, çalışma zamanında analiz edilir ve değiştirilir. Kod, yürütülene kadar gerçekten son haline getirilmediğinden optimize edici, hangi kodun güvenli bir şekilde kaldırılabileceğini bilmez. Bu işlem, çalışma zamanında yansıma yoluyla dinamik olarak kullanılan kodu kaldırabilir ve bu da kullanıcılar için uygulama kilitlenmelerine neden olabilir.

    Birçok modern kitaplık, yansıma yerine codegen kullanır. Room, Hilt ve diğer birçok araç tarafından kullanılan ortak bir giriş noktası için KSP'ye bakın.

  • R8 tam modunu destekleme: R8 tam modu etkinleştirildiğinde kitaplığınız kilitlenmemelidir. R8'in tam modu, R8'i kullanmak için önerilen moddur ve 2023'te kararlı hale getirilen AGP 8.0'dan beri varsayılan moddur. Kitaplığınız R8 altında kilitleniyorsa çözüm, belirli yansıma veya JNI giriş noktasını belirleyip hedeflenen bir kural eklemektir, tüm paketi saklamak değildir. Bu giriş noktalarındaki ek açıklamalardan hedeflenen kurallar oluşturmak için Jetpack Keep'i kullanın.

Ek öneriler

Optimizasyon koşullarının yanı sıra aşağıdaki ek öneriler de dikkate alınmalıdır.

  • Kitaplığınızın tüketici saklama kuralları dosyasında -repackageclasses kullanmayın. Tüketici saklama (keep) kuralları, kitaplığınızı kullanan her uygulamanın R8 yapılandırmasıyla birleştirilir. Bu nedenle, bu genel seçenek uygulamanın tamamı için geçerlidir ve uygulama geliştiricinin kendi yeniden paketleme ayarlarını geçersiz kılar. AGP 9.0'dan itibaren, tüketici saklama kuralları genel seçenekler içeriyorsa kitaplığın yayınlanması varsayılan olarak başarısız olur. Daha fazla bilgi için AGP 9.0 sürüm notlarını inceleyin.

    Kitaplık derlemenizi optimize etmek için kitaplığınızın derleme saklama kuralları dosyasında <your.library.package>.internal gibi dahili bir paket adıyla -repackageclasses kullanabilirsiniz. Bu, kitaplığınızın optimize edilmemiş uygulamalardaki verimliliğini artırabilir ancak uygulamaların da optimize edilmesi gerektiğinden genellikle gerekli değildir.

  • proguard-android-optimize.txt içinde tanımlanan özelliklerle çakışma olsa bile kitaplığınızın çalışması için gereken tüm özellikleri kitaplığınızın saklama kuralları dosyalarında beyan edin.

  • Kitaplık dağıtımınızda aşağıdaki özelliklere ihtiyacınız varsa bunları kitaplığınızın tüketici saklama kuralları dosyasında değil, kitaplığınızın derleme saklama kuralları dosyasında saklayın:

    • AnnotationDefault
    • EnclosingMethod
    • Exceptions
    • InnerClasses
    • RuntimeInvisibleAnnotations
    • RuntimeInvisibleParameterAnnotations
    • RuntimeInvisibleTypeAnnotations
    • RuntimeVisibleAnnotations
    • RuntimeVisibleParameterAnnotations
    • RuntimeVisibleTypeAnnotations
    • Signature
  • Kitaplık yazarları, çalışma zamanında ek açıklamalar kullanılıyorsa tüketici saklama kurallarında RuntimeVisibleAnnotations özelliğini saklamalıdır.

  • Kitaplık yazarları, tüketici saklama kurallarında aşağıdaki genel seçenekleri kullanmamalıdır. -repackageclasses gibi bu seçenekler de yalnızca kitaplığınızın kodunu değil, uygulamanın tüm R8 derlemesini yapılandırır. Bu nedenle, bunları uygulama geliştiriciye bırakın:

    • -include
    • -basedirectory
    • -injars
    • -outjars
    • -libraryjars
    • -repackageclasses
    • -flattenpackagehierarchy
    • -allowaccessmodification
    • -renamesourcefileattribute
    • -ignorewarnings
    • -addconfigurationdebugging
    • -printconfiguration
    • -printmapping
    • -printusage
    • -printseeds
    • -applymapping
    • -obfuscationdictionary
    • -classobfuscationdictionary
    • -packageobfuscationdictionary

Yansıma ne zaman kabul edilebilir?

Yansıma kullanmanız gerekiyorsa yalnızca aşağıdakilerden birine yansıtmanız gerekir:

  • Belirli hedeflenen türler (belirli arayüz uygulayıcıları veya alt sınıflar)
  • Belirli bir çalışma zamanı ek açıklamasını kullanan kod

Yansımayı bu şekilde kullanmak, çalışma zamanı maliyetini sınırlandırır ve hedeflenen tüketici saklama kuralları yazmayı sağlar.

Bu özel ve hedeflenmiş yansıma biçimi, hem Android çerçevesinde (ör. etkinlikleri, görünümleri ve çizilebilir öğeleri şişirirken) hem de AndroidX kitaplıklarında (ör. WorkManager ListenableWorkers veya RoomDatabases oluştururken) görebileceğiniz bir kalıptır. Buna karşılık, Gson'un açık uçlu yansıması Android uygulamalarında kullanıma uygun değildir.

Yaygın yanlış kanılar

Sık karşılaşılan birkaç yanlış bilgi, R8'i yanlış yapılandırmanıza neden olabilir. Bu politikalar aşağıdakileri içerir:

  • R8'in optimizasyonlarının yanlış anlaşılması: Yaygın inanışın aksine, R8'in optimizasyonları yalnızca kod karartmayla sınırlı değildir. Ayrıca kod daraltma ve yöntem satır içi ekleme ile sınıf birleştirme tekniklerini kullanan mantıksal optimizasyonları da içerir. Daha fazla bilgi için R8 optimizasyonuna genel bakış başlıklı makaleyi inceleyin.

  • Karartılmış kitaplıkların optimizasyonunu atlama: Sık karşılaşılan bir hata, bir kitaplığın AAR (Android Arşivi) veya JAR (Java Arşivi) olarak derlenirken optimize edilmesi ya da karartılması nedeniyle optimizasyonun dışında bırakılmasıdır. Kitaplık derleme süresi boyunca optimizasyonlar sınırlıdır ve uygulamanız, kitaplığı bir saklama kuralına dahil ederek kitaplığın optimizasyonunu devre dışı bırakmamalıdır. Daha fazla bilgi için AAR kitaplığı derlemesini optimize etme başlıklı makaleyi inceleyin.

  • -keep seçeneğinin yanlış anlaşılması -keep kuralı, R8'in optimizasyon adımlarından herhangi birini çalıştırmasını engeller. Daha fazla bilgi için Doğru saklama seçeneğini belirleme başlıklı makaleyi inceleyin.

Tüketici saklama kuralı kalitesini doğrulama

Kitaplığınızın bir uygulamaya yerleştirildiğinde çok fazla kod optimizasyonunu engellemediğini doğrulamak için bir kitaplık örneği veya entegrasyon testi uygulaması kullanın. R8'i etkinleştirin ve R8 Yapılandırma Analiz Aracı ile uygulamanın genel R8 yapılandırma kalitesini inceleyin.

Tüketici kurallarınızın, kitaplığınızın kodunun büyük bölümlerinde optimizasyonu sınırladığı gösteriliyorsa bu, tüketici kurallarınızın iyileştirilmesi gerektiği anlamına gelir. Tüketici kurallarını daraltın ve kitaplığınızın etkilenen tüm yönlerini R8'in etkin olduğu bir uygulamada test edin.

Kural paketlemeyi yapılandırma

Tüketici saklama kurallarınızın doğru şekilde uygulandığından emin olmak için bunları kitaplık biçiminize uygun şekilde paketlemeniz gerekir.

Kitaplığınızın yansıma ve JNI kullanımını bildirmek için Jetpack Keep'i kullanırsanız Gradle eklentisi, oluşturulan kuralları sizin için tüketici saklama kuralları olarak paketleyebilir.

AAR kitaplıkları

AAR kitaplığı için tüketici kuralları eklemek istiyorsanız Android kitaplık modülünün derleme komut dosyasında consumerProguardFiles seçeneğini kullanın. Daha fazla bilgi için kitaplık modülleri oluşturmayla ilgili kılavuzumuzu inceleyin.

Kotlin

android {
    defaultConfig {
        consumerProguardFiles("consumer-proguard-rules.pro")
    }
    ...
}

Modern

android {
    defaultConfig {
        consumerProguardFiles 'consumer-proguard-rules.pro'
    }
    ...
}

JAR kitaplıkları

Kuralları JAR olarak gönderilen Kotlin veya Java kitaplığınızla paketlemek için kurallar dosyanızı nihai JAR'ın META-INF/proguard/ dizinine herhangi bir dosya adıyla yerleştirin. Örneğin, kodunuz <libraryroot>/src/main/kotlin dizinindeyse tüketici kuralları dosyasını <libraryroot>/src/main/resources/META-INF/proguard/consumer-proguard-rules.pro dizinine yerleştirin. Kurallar, çıkış JAR'ınızda doğru konuma paketlenir.

Kuralların META-INF/proguard dizininde olduğunu kontrol ederek nihai JAR'ın kuralları doğru şekilde paketlediğini doğrulayın.

AAR kitaplığı derlemesini optimize etme (gelişmiş)

Kitaplık derleme sırasında yapılabilecek optimizasyonlar çok sınırlı olduğundan, genellikle kitaplık derlemesini doğrudan optimize etmeniz gerekmez. Kitaplık geliştiricisi olarak, optimizasyonun birden fazla aşamasını düşünmeniz ve kitaplığı optimize etmeden önce hem kitaplık hem de uygulama derleme zamanında davranışı korumanız gerekir.

Kitaplığınızı derleme sırasında optimize etmek istiyorsanız bu işlem Android Gradle eklentisi tarafından desteklenir.

Kotlin

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
        configureEach {
            consumerProguardFiles("consumer-rules.pro")
        }
    }
}

Modern

android {
    buildTypes {
        release {
            minifyEnabled true
            proguardFiles
                getDefaultProguardFile('proguard-android-optimize.txt'),
                'proguard-rules.pro'
        }
        configureEach {
            consumerProguardFiles "consumer-rules.pro"
        }
    }
}

proguardFiles davranışının consumerProguardFiles davranışından çok farklı olduğunu unutmayın:

  • proguardFiles, derleme sırasında genellikle getDefaultProguardFile("proguard-android-optimize.txt") ile birlikte kullanılır ve kitaplık derlemesi sırasında kitaplığınızın hangi bölümünün saklanması gerektiğini tanımlar. En azından, herkese açık API'niz budur.
  • consumerProguardFiles ise kitaplığınızın kullanıldığı bir uygulamanın derlenmesi sırasında daha sonra hangi optimizasyonların yapılacağını etkilemek için kitaplığa paketlenir.

Örneğin, kitaplığınız dahili sınıflar oluşturmak için yansıma kullanıyorsa saklama kurallarını hem proguardFiles hem de consumerProguardFiles içinde tanımlamanız gerekebilir.

Kitaplığınızın derlemesinde -repackageclasses kullanıyorsanız sınıfları kitaplığınızın paketinin içindeki bir alt pakette yeniden paketleyin. Örneğin, -repackageclasses 'internal' yerine -repackageclasses 'com.example.mylibrary.internal' kullanın.

Farklı R8 sürümlerini destekleme (gelişmiş)

Kuralları, R8'in belirli sürümlerini hedefleyecek şekilde özelleştirebilirsiniz. Bu sayede kitaplığınız, daha yeni R8 sürümlerini kullanan projelerde en iyi şekilde çalışırken mevcut kurallar, daha eski R8 sürümlerini kullanan projelerde kullanılmaya devam edebilir.

Hedeflenen R8 kurallarını belirtmek için bunları bir AAR'nin META-INF/com.android.tools içindeki classes.jar dizinine veya bir JAR'ın META-INF/com.android.tools dizinine eklemeniz gerekir.

In an AAR library:
    proguard.txt (legacy location, the file name must be "proguard.txt")
    classes.jar
    └── META-INF
        └── com.android.tools (location of targeted R8 rules)
            ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
            └── ... (more directories with the same name format)

In a JAR library:
    META-INF
    ├── proguard/<ProGuard-rule-files> (legacy location)
    └── com.android.tools (location of targeted R8 rules)
        ├── r8-from-<X>-upto-<Y>/<R8-rule-files>
        └── ... (more directories with the same name format)

META-INF/com.android.tools dizininde, kuralların hangi R8 sürümleri için yazıldığını belirtmek amacıyla r8-from-<X>-upto-<Y> biçiminde adlara sahip birden fazla alt dizin olabilir. Her alt dizinde, R8 kurallarını içeren bir veya daha fazla dosya bulunabilir. Bu dosyaların adları ve uzantıları herhangi bir şey olabilir.

-from-<X> ve -upto-<Y> bölümlerinin isteğe bağlı olduğunu, <Y> sürümünün özel olduğunu ve sürüm aralıklarının genellikle sürekli olduğunu ancak çakışabileceğini unutmayın.

Örneğin, r8, r8-upto-8.0.0, r8-from-8.0.0-upto-8.2.0 ve r8-from-8.2.0, hedeflenen bir dizi R8 kuralını temsil eden dizin adlarıdır. r8 dizini altındaki kurallar tüm R8 sürümleri tarafından kullanılabilir. r8-from-8.0.0-upto-8.2.0 dizinindeki kurallar, 8.0.0 sürümünden 8.2.0 sürümüne kadar (8.2.0 hariç) R8 tarafından kullanılabilir.

Android Gradle eklentisi, mevcut R8 sürümü tarafından kullanılabilecek tüm kuralları seçmek için bu bilgileri kullanır. Bir kitaplık, hedeflenen R8 kurallarını belirtmiyorsa Android Gradle eklentisi, kuralları eski konumlardan (AAR için proguard.txt veya JAR için META-INF/proguard/<ProGuard-rule-files>) seçer.