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

يسهِّل المكوّن الإضافي Gradle لملف الأداء الأساسي إنشاء ملفات الأداء الأساسي وصيانتها. يساعدك ذلك في تنفيذ المهام التالية:

• أنشئ ملفات شخصية جديدة للمرجع لتطبيقك.
• إنشاء ملفات شخصية جديدة للمرجع لمكتبتك
• تخصيص عملية إنشاء "الملف الشخصي الأساسي"

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

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

• ‫AGP 8.0 أو إصدار أحدث
• الاعتماد على أحدث إصدار من المكوّن الإضافي لنظام Gradle

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

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

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

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

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

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

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

baselineProfile {
    ...
    useConnectedDevices = false
}

baselineProfile {
    ...
    useConnectedDevices false
}

إنشاء ملفات شخصية مرجعية للصيغ المختلفة

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

baselineProfile {
    mergeIntoMain = true
}

baselineProfile {
    mergeIntoMain true
}

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

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

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

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

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

baselineProfile {
    variants {
        freeRelease {
            mergeIntoMain true
        }
    }
}

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

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

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

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

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

baselineProfile {
    automaticGenerationDuringBuild = true
}

baselineProfile {
    automaticGenerationDuringBuild true
}

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

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

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

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

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

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

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

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

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

يمكنك أيضًا تحديد هذا السلوك لكلّ سعر متغير:

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

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

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

يُنبهك تلقائيًا مكوّن Gradle الإضافي لملف الإصدار الأساسي بشأن الحالات التي قد تؤدي إلى حدوث مشاكل. لإيقاف التحذيرات، يمكنك ضبط الخيار ذي الصلة على 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
    }
}

قواعد فلترة الملفات التجارية

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

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

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

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

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.**")
    }
}

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.**'
    }
}

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

// 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.**")
            }
        }
    }
}

// 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 Gradle أنواع إنشاء إضافية لإنشاءملفّات الأداء وإجراء اختبارات الأداء. يتمّ وضع البادئة benchmark وnonMinified على أنواع الإصدارات هذه. على سبيل المثال، بالنسبة إلى نوع الإصدار release، ينشئ التكامل نوعَي الإصدار benchmarkRelease وnonMinifiedRelease. يتم ضبط أنواع الإصدارات هذه تلقائيًا لحالة الاستخدام المحدّدة، ولا تحتاج عمومًا إلى أي تخصيص. ولكن قد يظلّ مفيداً في بعض الحالات تطبيق بعض الخيارات المخصّصة، مثلاً لتطبيق إعدادات توقيع مختلفة.

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

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
        }
    }
}

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       
        }
    }
}

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

عند إنشاء الملفات الشخصية الأساسية، إليك بعض النقاط الإضافية التي يجب أخذها في الاعتبار:

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

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

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