ضبط إعدادات إنشاء الملف الشخصي الأساسي

يسهّل Baseline Profile Gradle Plugin إنشاء ملفات Baseline Profile والحفاظ عليها. تساعدك هذه الميزة في تنفيذ المهام التالية:

توضّح هذه الصفحة كيفية استخدام مكوّن Baseline Profile الإضافي في Gradle لتخصيص عملية إنشاء ملفات Baseline Profile.

متطلبات المكوّن الإضافي

استخدام "الأجهزة المُدارة من Gradle" لإنشاء "ملفات تعريف Baseline"

لاستخدام جهاز افتراضي مُدار من Gradle (GMD) من أجل إنشاء "الملف الأساسي"، أضِف جهازًا في إعداد build.gradle.kts لوحدة إنشاء الملفات الشخصية، والتي من المحتمل أن تكون وحدة اختبار :baselineprofile، كما هو موضّح في المثال التالي:

Kotlin

android {
   testOptions.managedDevices.devices {
       create<com.android.build.api.dsl.ManagedVirtualDevice>("pixel6Api31") {
           device = "Pixel 6"
           apiLevel = 31
           systemImageSource = "aosp"
       }
   }
}

Groovy

android {
   testOptions.managedDevices.devices {
       pixel6Api31(ManagedVirtualDevice) {
           device 'Pixel 6'
           apiLevel = 31
           systemImageSource 'aosp'
       }
   }
}

استخدِم أداة GMD لإنشاء "ملفات تعريف الأداء الأساسية" من خلال إضافتها إلى إعدادات إضافة Gradle الخاصة بـ "ملف تعريف الأداء الأساسي" على النحو التالي، في build.gradle.kts من وحدة اختبار :baselineprofile:

Kotlin

baselineProfile {
    managedDevices += "pixel6Api31"
}

Groovy

baselineProfile {
    managedDevices = ['pixel6Api31']
}

عند استخدام GMD لإنشاء ملفات Baseline Profiles، اضبط useConnectedDevices على false في وحدة اختبار :baselineprofile:

Kotlin

baselineProfile {
    ...
    useConnectedDevices = false
}

Groovy

baselineProfile {
    ...
    useConnectedDevices false
}

إنشاء ملفات Baseline Profile لصيغ مختلفة

يمكنك إنشاء ملفات Baseline Profiles لكل صيغة أو لكل إصدار أو كملف واحد لاستخدامه مع جميع الصيغ. يمكنك التحكّم في هذا السلوك من خلال إعداد الدمج، كما هو موضّح في المثال التالي، في build.gradle.kts من تطبيق أو وحدة مكتبة.

Kotlin

baselineProfile {
    mergeIntoMain = true
}

Groovy

baselineProfile {
    mergeIntoMain true
}

لدمج الملفات الشخصية التي تم إنشاؤها لجميع صيغ المنتج في ملف شخصي واحد، اضبط mergeIntoMain على true. لا يمكن إنشاء ملفات Baseline Profiles لكل صيغة عند ضبط هذا الإعداد على true، لذا يتوفّر مهمة Gradle واحدة باسم generateBaselineProfile. يتم إخراج الملف الشخصي في src/main/generated/baselineProfiles.

لإيقاف الدمج والحصول على ملف واحد لكل صيغة، اضبط قيمة mergeIntoMain على false. في هذه الحالة، تتوفّر مهام Gradle متعددة خاصة بمتغيرات الإصدار. على سبيل المثال، عندما يكون هناك إصداران، مثل الإصدار المجاني والإصدار المدفوع، ونوع واحد من إصدارات البناء، تكون المهام على النحو التالي:

* `generateFreeReleaseBaselineProfile`
* `generatePaidReleaseBaselineProfile`
* `generateReleaseBaselineProfile`

لتحديد سلوك الدمج لكل صيغة، استخدِم الرمز التالي:

Kotlin

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

في المثال السابق، يتم دمج جميع المتغيرات التي تم ضبط العلامة فيها على true في src/main/generated/baselineProfiles، بينما يتم الاحتفاظ بملفات المتغيرات التي تم ضبط العلامة فيها على false في المجلد src/<variant>/generated/baselineProfiles.

يتم ضبط mergeIntoMain تلقائيًا على true للمكتبات وfalse للتطبيقات.

إنشاء "ملفات تعريف الخط الأساس" تلقائيًا عند تجميع إصدار جديد

يمكنك ضبط "ملفات تعريف خط الأساس" ليتم إنشاؤها تلقائيًا مع كل إصدار من الإصدارات، بدلاً من استخدام مهمة generateBaselineProfile يدويًا. باستخدام ميزة الإنشاء التلقائي، يتم تضمين أحدث ملف شخصي في إصدار التطبيق.

لتفعيل الإنشاء التلقائي لإصدارات التطبيق، استخدِم العلامة automaticGenerationDuringBuild:

Kotlin

baselineProfile {
    automaticGenerationDuringBuild = true
}

Groovy

baselineProfile {
    automaticGenerationDuringBuild true
}

يؤدي ضبط العلامة automaticGenerationDuringBuild على true إلى بدء إنشاء ملف تعريف أساسي جديد لكل حزمة إصدار. وهذا يعني أنّ تنفيذ مهمة إنشاء إصدار تجميعي، مثل ./gradlew:app:assembleRelease، يؤدي أيضًا إلى تشغيل :app:generateReleaseBaselineProfile وبدء اختبارات الأجهزة لملف Baseline Profile وإنشاء إصدار ملف Baseline Profile الذي يتم تشغيل الاختبارات عليه. على الرغم من أنّ ميزة الإنشاء التلقائي تساعد المستخدمين في تحقيق أفضل أداء، إلا أنّها تزيد أيضًا من وقت الإنشاء بسبب الإنشاء المزدوج واختبارات الأدوات.

يمكنك أيضًا تحديد هذا السلوك لكل خيار منتج، كما هو موضّح في المثال التالي:

Kotlin

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

في المثال السابق، يتم تنفيذ المهمة generateFreeReleaseBaselineProfile عند بدء assembleFreeRelease. ويكون ذلك مفيدًا عندما يريد المستخدم، على سبيل المثال، إنشاء release لإصدار التوزيع الذي ينشئ الملف الشخصي دائمًا عند الإنشاء، وإنشاء releaseWithoutProfile للاختبار الداخلي.

بدلاً من إضافة صيغة جديدة بدون ملف Baseline Profile، يمكنك أيضًا إيقاف إنشاء الملف من سطر الأوامر على النحو التالي:

./gradlew assembleRelease -Pandroid.baselineProfile.automaticGenerationDuringBuild=false

تخزين ملفات تعريف المرجع في المصادر

يمكنك تخزين ملفات Baseline Profiles في دليل المصدر من خلال العلامة saveInSrc في build.gradle.kts لوحدة التطبيق أو المكتبة:

  • true: يتم تخزين "ملف المرجع" في src/<variant>/generated/baselineProfiles. يتيح لك ذلك إرسال أحدث ملف شخصي تم إنشاؤه مع المستندات المصدر.
  • ‫false: يتم تخزين Baseline Profile في الملفات الوسيطة في دليل الإنشاء. بهذه الطريقة، عند إرسال الرمز البرمجي، لن يتم حفظ أحدث ملف شخصي تم إنشاؤه.

Kotlin

baselineProfile {
    saveInSrc = true
}

Groovy

baselineProfile {
    saveInSrc true
}

يمكنك أيضًا تحديد هذا السلوك لكل خيار منتج:

Kotlin

baselineProfile {
    variants {
        freeRelease {
            saveInSrc = true
        }
    }
}

Groovy

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

إيقاف التحذيرات

تلقائيًا، يحذّرك Baseline Profile Gradle Plugin من الحالات التي قد تتسبّب في حدوث مشاكل. لإيقاف التحذيرات، يمكنك ضبط الخيار ذي الصلة على false في ملف build.gradle.kts. في ما يلي خيارات التحذير:

baselineProfile {
    warnings {

        /**
        * Warn when the Android Gradle Plugin version is higher than the max
        * tested one.
        */
        maxAgpVersion = true

        /**
        * Warn when a benchmark or baseline profile variant has been disabled.
        */
        disabledVariants = true

        /**
        * Warn that running `generateBaselineProfile` with AGP 8.0 doesn't
        * support running instrumentation tests for multiple build types at
        * once.
        */
        multipleBuildTypesWithAgp80 = true

        /**
        * Warn when no baseline profiles are generated after running the
        * generate baseline profile command.
        */
        noBaselineProfileRulesGenerated = true

        /**
        * Warn when no startup profiles are generated after running the generate
        * baseline profile command.
        */
        noStartupProfileRulesGenerated = true
    }
}

فلترة قواعد الملف الشخصي

تتيح لك إضافة Baseline Profile Gradle فلترة قواعد Baseline Profile التي تم إنشاؤها. ويكون ذلك مفيدًا بشكل خاص للمكتبات إذا أردت استبعاد قواعد الملف الشخصي للفئات والطرق التي تشكّل جزءًا من التبعيات الأخرى لتطبيق العيّنة أو المكتبة نفسها. يمكن أن تتضمّن الفلاتر حِزمًا وفئات معيّنة أو تستبعدها. عند تحديد عمليات الاستبعاد فقط، يتم استبعاد قواعد ملفات تعريف خط الأساس المطابقة فقط، ويتم تضمين كل شيء آخر.

يمكن أن تكون مواصفات الفلاتر أيًّا ممّا يلي:

  • اسم الحزمة الذي ينتهي بحرفَي بدل مزدوجَين لمطابقة الحزمة المحدّدة وجميع الحِزم الفرعية على سبيل المثال، تتطابق com.example.** مع com.example.method وcom.example.method.bar.
  • اسم الحزمة الذي ينتهي بحرف بدل لمطابقة الحزمة المحدّدة فقط على سبيل المثال، يتطابق com.example.* مع com.example.method ولكن لا يتطابق مع com.example.method.bar.
  • أسماء الفئات التي يجب مطابقتها مع فئة معيّنة، مثل com.example.MyClass

توضّح الأمثلة التالية كيفية تضمين حِزم معيّنة واستبعادها:

Kotlin

baselineProfile {
    filter {
        include("com.somelibrary.widget.grid.**")
        exclude("com.somelibrary.widget.grid.debug.**")
        include("com.somelibrary.widget.list.**")
        exclude("com.somelibrary.widget.list.debug.**")
        include("com.somelibrary.widget.text.**")
        exclude("com.somelibrary.widget.text.debug.**")
    }
}

Groovy

baselineProfile {
    filter {
        include 'com.somelibrary.widget.grid.**'
        exclude 'com.somelibrary.widget.grid.debug.**'
        include 'com.somelibrary.widget.list.**'
        exclude 'com.somelibrary.widget.list.debug.**'
        include 'com.somelibrary.widget.text.**'
        exclude 'com.somelibrary.widget.text.debug.**'
    }
}

خصِّص قواعد الفلتر للخيارات المختلفة على النحو التالي:

Kotlin

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include("com.myapp.**") }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include("com.myapp.free.**")
            }
        }
        paid {
            filter {
                include("com.myapp.paid.**")
            }
        }
    }
}

// Build-type-specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include("com.myapp.**")
            }
        }
    }
}

Groovy

// Non-specific filters applied to all the variants.
baselineProfile {
    filter { include 'com.myapp.**' }
}

// Flavor-specific filters.
baselineProfile {
    variants {
        free {
            filter {
                include 'com.myapp.free.**'
            }
        }
        paid {
            filter {
                include 'com.myapp.paid.**'
            }
        }
    }
}

// Build-type specific filters.
baselineProfile {
    variants {
        release {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

// Variant-specific filters.
baselineProfile {
    variants {
        freeRelease {
            filter {
                include 'com.myapp.**'
            }
        }
    }
}

يمكنك أيضًا فلترة القواعد باستخدام وسيطة filterPredicate في BaselineProfileRule.collect()، ولكن ننصحك باستخدام إضافة Gradle للفلترة لأنّها توفّر طريقة أبسط لفلترة الحِزم الفرعية ومكانًا واحدًا لإعداد الوحدة بأكملها.

تخصيص أنواع الإصدارات في مقياس الأداء وملف Baseline Profile

ينشئ مكوّن Baseline Profile الإضافي في Gradle أنواعًا إضافية من الإصدارات لإنشاء الملفات الشخصية وتشغيل مقاييس الأداء. يتم وضع البادئة benchmark وnonMinified لأنواع الإصدارات هذه. على سبيل المثال، بالنسبة إلى release نوع الإصدار، ينشئ المكوّن الإضافي نوعَي الإصدار benchmarkRelease وnonMinifiedRelease. يتم ضبط أنواع الإصدارات هذه تلقائيًا لحالة الاستخدام المحدّدة، ولا تحتاج عادةً إلى أي تخصيص. ومع ذلك، هناك بعض الحالات التي قد يكون فيها من المفيد تطبيق بعض الخيارات المخصّصة، مثل تطبيق إعدادات توقيع مختلفة.

يمكنك تخصيص أنواع الإصدارات التي يتم إنشاؤها تلقائيًا باستخدام مجموعة فرعية من خصائص أنواع الإصدارات، ويتم إلغاء الخصائص غير القابلة للاستخدام. يوضّح المثال التالي كيفية تخصيص أنواع الإصدارات الإضافية والخصائص التي يتم تجاهلها:

Kotlin

android {
    buildTypes {
        release {
            ...
        }
        create("benchmarkRelease") {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default
            // it's the same as for the `release` build type).
            signingConfig = signingConfigs.getByName("benchmarkRelease")
        }
        create("nonMinifiedRelease") {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.getByName("nonMinifiedRelease")

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't
            // customize the following properties, which are always overridden to
            // avoid breaking Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false
        }
    }
}

Groovy

android {
    buildTypes {
        release {
            ...
        }
        benchmarkRelease {
            // Customize properties for the `benchmarkRelease` build type here.
            // For example, you can change the signing config (by default it's the
            // same as for the `release` build type.)
            signingConfig = signingConfigs.benchmarkRelease
        }
        nonMinifiedRelease {
            // Customize properties for the `nonMinifiedRelease` build type here.
            signingConfig = signingConfigs.nonMinifiedRelease

            // From Baseline Profile Gradle plugin 1.2.4 and higher, you can't use
            // the following properties, which are always overridden to avoid breaking
            // Baseline Profile generation:
            //
            // isJniDebuggable = false
            // isDebuggable = false
            // isMinifyEnabled = false
            // isShrinkResources = false
            // isProfileable = true
            // enableAndroidTestCoverage = false
            // enableUnitTestCoverage = false       
        }
    }
}

ملاحظات إضافية

عند إنشاء "ملفات تعريف أساسية"، إليك بعض الأمور الإضافية التي يجب الانتباه إليها:

  • يجب أن يكون حجم ملفات تعريف Baseline Profiles المجمَّعة أقل من 1.5 ميغابايت. لا ينطبق ذلك على تنسيق النص في ملفات المصدر، والذي يكون عادةً أكبر بكثير قبل عملية التجميع. تحقَّق من حجم ملف Baseline Profile الثنائي من خلال البحث عنه في العنصر الناتج ضمن assets/dexopt/baseline.prof لحزمة APK أو BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof لحزمة AAB.

  • يمكن أن تؤدي القواعد الواسعة التي تجمع الكثير من التطبيق إلى إبطاء عملية بدء التشغيل بسبب زيادة الوصول إلى القرص. إذا كنت قد بدأت للتوّ في استخدام Baseline Profiles، لا تقلق بشأن ذلك. ومع ذلك، استنادًا إلى تطبيقك وحجم الرحلات وعددها، يمكن أن تؤدي إضافة الكثير من الرحلات إلى أداء دون المستوى المطلوب. اختبِر أداء تطبيقك من خلال تجربة ملفات شخصية مختلفة والتأكّد من عدم تراجع الأداء بعد إضافة الملفات.

الدروس التطبيقية حول الترميز

التعمّق في اختبارات الأداء الشاملة لقياس الأداء
مزيد من المعلومات
إنشاء ملف Baseline Profile مخصّص ومصمّم خصيصًا لتطبيق Android وإثبات فعاليته
مزيد من المعلومات
السابق
إنشاء ملفات شخصية أساسية لمكتبة
التالي
القياس باستخدام مكتبة ماكروبينمارك