Saklama kuralları hakkında

Uygulama optimizasyonunu varsayılan ayarlarla 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 gibi 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, bunları saklama kurallarında belirterek 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 durum, uygulamanızın ihtiyaç duyduğu kodun kaldırılmasına ve kilitlenmelere neden olabilir. R8'e bu tür dolaylı olarak kullanılan kodu korumasını söylemek için keep 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ına göre 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 veya 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 dayalıdır. R8, dize tabanlı dinamik yöntem çağrısını göremez. Bu nedenle, optimizasyonları kodunuzu bozabilir.

Bu, saklama kurallarının gerekli olduğu senaryoların tam listesi değildir ancak bu senaryolar, saklama kurallarına ihtiyaç duyabileceğiniz durumların çoğunu kapsar.

Kendi kodunuz yansıtma kullanıyorsa veya JNI'den çağrılıyorsa bu kodu, saklama kurallarını manuel olarak yazmak yerine Jetpack Keep ek açıklamalarıyla ek açıklama olarak belirtebilirsiniz. Gradle eklentisi, derleme sırasında açıklamalardan keep kurallarını oluşturur.

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 tür durumlarda, saklama kurallarını genellikle belirli kitaplık modülünde uygulandıkları kodun yanına yerleştirmek daha iyidir. Kitaplıklar için saklama kurallarını koruma konusundaki 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 Kütüphane yazarları için optimizasyon başlıklı makaleyi inceleyin.

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

Kurallarınızı .keep sonekini içeren bir dosyaya ekleyin. Bu dosyayı src/<variant>/keepRules dizinine yerleştirin. Ö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.
            }
        }
    }
}

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

AGP, bir dizi varsayılan Android platform 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 vermelisiniz. Bu dosya, proguard-common.txt dosyasını temel alır ve bu dosyayla içerik paylaşır.

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 başlıklı makaleyi inceleyin.

  • Koruma kuralları: Koruma kuralları, uygulamanızı yanlışlıkla bozmadan kod optimizasyonunu en üst düzeye çıkarma konusunda doğru dengeyi elde etmenizi sağlamak için dikkatli bir şekilde tasarlanmalıdır. Koruma kurallarını nasıl yazacağınızı öğrenmek için Koruma kuralları ekleme başlıklı makaleyi inceleyin.

Kitaplık yazarları için kuralları koruma

Saklama kurallarıyla ilgili 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.