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

يسهِّل المكوّن الإضافي لنظام Gradle المتوافق مع خط الأساس إنشاء المحتوى وصيانته الملفات الشخصية المرجعية: إنه يساعدك قم بتنفيذ المهام التالية:

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

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

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

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

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

لاستخدام جهاز مُدار من Gradle من أجل إنشاء ملفك الشخصي الأساسي، وإضافة ملف شخصي في إعدادات 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: يتم تخزين الملف الشخصي الأساسي في الملفات المتوسطة في الإصدار. الدليل. بهذه الطريقة، لن تحفظ أحدث الرمز البرمجي إنشاء ملف شخصي.

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

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

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

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

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

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

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

• اسم الحزمة الذي ينتهي بحروف بدل مزدوجة لمطابقة الحزمة المحدّدة وجميع الحِزم الفرعية على سبيل المثال، تتطابق 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 المكوّن الإضافي لتصفية البيانات لأنها توفر طريقة أبسط لتصفية الحزم الفرعية مكان واحد لتهيئة الوحدة بالكامل.

تخصيص أنواع إنشاء ملفّات الأداء المرجعي وملفّات "الملفّ الشخصي للمرجع"

ينشئ المكوّن الإضافي لنظام 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 الثنائي الملف الشخصي من خلال تحديد موقعه في أداة الإخراج ضمن assets/dexopt/baseline.prof لملف APK أو BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof لتنسيق AAB.

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

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