Saklama kuralları hakkında

Varsayılan ayarlarla uygulama optimizasyonunu etkinleştirdiğinizde R8, performans avantajlarınızı en üst düzeye çıkarmak için kapsamlı optimizasyonlar gerçekleştirir. R8; sınıfları, alanları ve yöntemleri yeniden adlandırma, taşıma ve kaldırma dahil olmak üzere kodda önemli değişiklikler yapar. Bu değişikliklerin hatalara neden olduğunu fark ederseniz kodun hangi bölümlerinin R8 tarafından değiştirilmemesi gerektiğini saklama kurallarında belirtmeniz gerekir.

Saklama kuralları gerektiren yaygın senaryolar

R8, kodunuzdaki tüm doğrudan çağrıları tanımlar ve korur. Ancak R8, dolaylı kod kullanımlarını göremez. Bu nedenle, uygulamanızın ihtiyaç duyduğu kodu kaldırarak kilitlenmelere neden olabilir. R8'e bu tür dolaylı olarak kullanılan kodları korumasını söylemek için saklama kurallarını kullanın. Saklama kurallarına ihtiyaç duyabileceğiniz birkaç yaygın durum aşağıda verilmiştir:

• Yansıma ile erişilen kod: R8, sınıflara, alanlara veya yöntemlere yansıma ile ne zaman erişildiğini belirleyemez. Örneğin R8, Class.getDeclaredMethod() kullanılarak adıyla aranan bir yöntemi veya Class.getAnnotation() ile alınan bir ek açıklamayı tanımlayamaz. Bu gibi durumlarda R8, bu yöntemleri ve ek açıklamaları yeniden adlandırabilir veya tamamen kaldırabilir. Bu da çalışma zamanında ClassNotFoundException ya da NoSuchMethodException hatasına yol açar.
• Java Yerel Arayüzü'nden (JNI) çağrılan kod: Yerel (C veya C++) kod bir Java ya da Kotlin yöntemini çağırdığında veya Java ya da Kotlin kodu JNI ile C++ kodunu çağırdığında çağrı, yöntemin adının dinamik dize aramasına dayanır. R8, dinamik dize tabanlı yöntem çağrısını göremez. Bu nedenle, optimizasyonları kodunuzu bozabilir.

Bu liste, saklama kuralları gerektiren tüm senaryoları içermez ancak saklama kurallarına ihtiyaç duyabileceğiniz durumların çoğunu kapsar.

Kendi kodunuz yansıma kullanıyorsa veya JNI'dan çağrılıyorsa saklama kurallarını manuel olarak yazmak yerine bu kodu Jetpack Keep ek açıklamalarıyla ek açıklama ekleyebilirsiniz. Gradle eklentisi, derleme zamanında ek açıklamalardan saklama kuralları oluşturur.

Not: Modern Android geliştirmede, yansıma kullanımını sınırlamanız ve mümkün olduğunda yerel koddan Java veya Kotlin kodunuza çağrı yapmaktan kaçınmanız gerekir. Bu kod kalıpları performansı etkileyebilir. Uygulamanız için bağımlılıkları seçerken R8 optimizasyonuyla uyumlu kitaplıkları tercih edin. Daha fazla bilgi edinmek için Kitaplıkları akıllıca seçme bölümüne bakın.

Saklama kurallarının optimizasyonu nasıl etkilediğini anlama

R8, kullanılmayan kodları kaldırmak, satır içi yöntemleri uygulamak, sınıfları birleştirmek ve tanımlayıcıları gizlemek için uygulama kodunuzu analiz eden bir tam program optimizasyon aracıdır. Ancak R8 yalnızca tanımladığınız yapılandırma dahilinde optimizasyon yapabilir.

"Sakla" kuralları, optimizasyonu sınırlamaya yönelik açık bir talimatı temsil eder. Bildirdiğiniz her saklama kuralı, R8'in kod tabanınızın ilgili bölümünü dönüştürme yeteneğini kısıtlar. İyi hazırlanmış bir saklama kuralının değeri, spesifik olmasından kaynaklanır:

• Dar kapsamlı saklama kuralları maksimum optimizasyon sağlar: Yalnızca dinamik olarak erişilen tam giriş noktalarını (ör. yansıtıcı bir kurucu veya serileştirilmiş bir alan) hedefleyerek R8'in kodunuzun geri kalanını optimize etmesini sağlarsınız.

• Geniş saklama kuralları optimizasyonu engeller: Paket genelinde kurallar veya geniş joker karakterler tanımlamak, R8'in tüm sınıfları ve tüm üyelerini optimize etmesini engeller. R8 bu kodu kaldıramaz, satır içine alamaz, birleştiremez veya kod karartma uygulayamaz.

Aşırı geniş saklama kuralları, doğrudan DEX ikili dosyalarının şişmesine, uygulamanın bellekte kapladığı yerin artmasına, başlatma sürelerinin (TTID ve TTFD) uzamasına ve ANR oranlarının yükselmesine neden olur. Amacınız sınıfları "her ihtimale karşı" tutmak değil, dinamik yürütme için gereken minimum sözleşmeyi tanımlamak olmalıdır.

Üçüncü taraf kitaplıklarındakiler de dahil olmak üzere geniş kapsamlı veya gereksiz saklama kurallarını bulmak için R8 Configuration Analyzer'ı kullanın. R8'in kodunuzun ne kadarını optimize edebileceğini gösteren küçültme, optimizasyon ve kod karartma puanlarını bildirir.

Uygulamanıza saklama kuralları ekleme

Keep kuralları yapılandırmanız, kullandığınız AGP sürümüne bağlıdır.

Daha büyük uygulamalarda genellikle birden fazla kitaplık modülünde kod bulunur. Bu gibi durumlarda, saklama kurallarını belirli kitaplık modülünde geçerli oldukları kodun yanına koymak genellikle daha iyidir. Kitaplıklar için saklama kurallarını korumadaki en önemli fark, bu kuralları kitaplık modülünüzün build.gradle.kts (veya build.gradle) dosyasında nasıl tanımladığınızdır. Daha fazla bilgi için Kitaplık yazarları için optimizasyon bölümüne bakın.

AGP 9.3 ve sonraki sürümler için

Kurallarınızı src/<variant>/keepRules dizininde .keep son ekine sahip bir dosyaya ekleyin. Örneğin, src/main/keepRules/custom-rules.keep. AGP 9.3 ve sonraki sürümler için güncellenmiş DSL'nin kullanılması hem kod hem de kaynak optimizasyonunu etkinleştirir ve varsayılan Android saklama kuralları dosyasını (proguard-android-optimize.txt) açıkça tanımlamanızı gerektirmez. Bu dosya, açıkça hariç tutulmadığı sürece varsayılan olarak dahil edilir.

Kotlin

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

Modern

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
            }
        }
    }
}

Not: Kod ve kaynak optimizasyonunun ayrı ayrı etkinleştirilmesini gerektiren eski DSL, AGP 9.3 ve sonraki sürümlerde hâlâ desteklenmektedir.

Varsayılan Android platformu saklama kurallarını atla (Gelişmiş)

AGP, bir dizi varsayılan Android platformu kuralı sağlar. Bu kuralları projenizin yapılandırmasından çıkarmak ve tüm saklama kurallarını kendiniz yönetmek için optimization.keepRules.includeDefault değerini false olarak ayarlayın.

Kotlin

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

Modern

android {
    buildTypes {
        release {
            optimization {
                enable = true // Enables code and resource optimizations.
                keepRules {
                    includeDefault = false // The file with optimization
                    // rules for the Android platform is included by
                    // default. To omit this file, set this option to false.
                }
            }
        }
    }
}

9.3'ten eski AGP sürümleri için eski DSL

Kurallarınızı uygulama modülünün kök dizininde bulunan bir proguard-rules.pro dosyasına ekleyin. Dosya zaten orada olabilir ancak yoksa oluşturun. Dosyadaki kuralları uygulamak için dosyayı modül düzeyindeki build.gradle.kts (veya build.gradle) dosyanızda beyan etmeniz gerekir.

Varsayılan olarak, derleme dosyanız proguard-android-optimize.txt dosyasını da içerir. Bu dosya, çoğu Android projesi için gerekli olan kuralları içerir. Bu nedenle, derleme dosyasında kalmasına izin vermeniz gerekir. Bu dosya, proguard-common.txt dosyasını temel alır ve bu dosyayla içerik paylaşır.

Uyarı: Eski Android projelerinin varsayılan R8 yapılandırması olarak proguard-android-optimize.txt yerine hâlâ proguard-android.txt kullandığını görebilirsiniz. Projeniz varsayılan R8 yapılandırması olarak proguard-android.txt dosyasını kullanıyorsa proguard-android-optimize.txt dosyasına geçmeniz gerekir. proguard-android.txt dosyasında, çoğu optimizasyonu engelleyen eski yapılandırmalar var.

Eski DSL (Kotlin)

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true

            proguardFiles(
                // Default file with default optimization rules.
                getDefaultProguardFile("proguard-android-optimize.txt"),
                ...
            )
        }
    }
}

Eski DSL (Groovy)

android {
    buildTypes {
        release {
            minifyEnabled = true
            shrinkResources = true

            // Default file with default optimization rules.
            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')
            ...
        }
    }
}

Saklama kuralı ekleme

Saklama kuralları eklerken genel seçenekleri dahil edebilir ve kendi saklama kurallarınızı tanımlayabilirsiniz.

• Genel seçenekler: Genel seçenekler, R8'in kod tabanınızın tamamında nasıl çalışacağını etkileyen genel yönergelerdir. Daha fazla bilgi edinmek için Genel seçenekler bölümüne bakın.

• Keep kuralları: Keep kuralları, uygulamanızı yanlışlıkla bozmadan kod optimizasyonunu en üst düzeye çıkarma arasında doğru dengeyi kurmak için dikkatlice tasarlanmalıdır. Keep kurallarını nasıl yazacağınızı öğrenmek için Keep kuralları ekleme bölümüne bakın.

Not: Saklama kuralları eklemelidir. Tüm kaynaklardan birleştirilirler. Birleştirilmiş saklama kurallarının istenen etkiyi gösterdiğini doğrulamak için hangi kuralların uygulandığını görebilirsiniz. Daha fazla bilgi edinmek için Hangi kuralların uygulandığını kontrol etme başlıklı makaleyi inceleyin.

Kitaplık yazarları için kuralları saklama

Keep kuralları için genel seçenekler ve söz dizimi hakkında bilgi edindikten sonra daha fazla ayrıntı için Kitaplık yazarları için optimizasyon başlıklı makaleyi inceleyin.