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

يسهّل المكوّن الإضافي Baseline Profile Gradle إنشاء الملفات الشخصية المرجعية وصيانتها. يساعدك على القيام بالمهام التالية:

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

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

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

• 8.0 AGP أو أعلى
• الاعتماد على أحدث إصدار من مكوّن 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 للملف الشخصي الأساسي على النحو التالي:

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

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

baselineProfile {
    ...
    useConnectedDevices = false
}

baselineProfile {
    ...
    useConnectedDevices false
}

إنشاء ملفات شخصية أساسية لخيارات مختلفة

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

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:

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

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

يمكنك أيضًا تحديد هذا السلوك لكل صيغة:

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

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

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

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

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

• اسم الحزمة الذي ينتهي بحرفي بدل مزدوجين لمطابقة الحزمة المحددة وجميع الحزم الفرعية. على سبيل المثال، تتطابق السمة 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 {
            ...
        }
        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")
        }
        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 ميغابايت. ولا ينطبق ذلك على تنسيق النص في الملفات المصدر، والتي عادةً ما تكون أكبر بكثير قبل التجميع. يمكنك التحقق من حجم ملفك الشخصي الأساسي الثنائي من خلال تحديد مكانه في عنصر الإخراج ضمن assets/dexopt/baseline.prof لحِزمة APK أو BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof لتنسيق AAB.

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

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