הגדרת היצירה של פרופיל הבסיס

התוסף Baseline Profile Gradle מאפשר ליצור ולתחזק פרופילים בסיסיים בקלות רבה יותר. הוא עוזר לכם לבצע את המשימות הבאות:

• יצירת פרופילים חדשים של Baseline לאפליקציה
• יצירת פרופילי Baseline חדשים לספרייה.
• התאמה אישית של יצירת פרופיל הבסיס להשוואה.

בדף הזה מוסבר איך להשתמש בתוסף Baseline Profile 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 ליצירת פרופילי בסיס, מוסיפים אותו להגדרת הפלאגין Baseline Profile Gradle באופן הבא, בקובץ build.gradle.kts של מודול הבדיקה :baselineprofile:

baselineProfile {
    managedDevices += "pixel6Api31"
}

baselineProfile {
    managedDevices = ['pixel6Api31']
}

כשמשתמשים ב-GMD כדי ליצור פרופילים של בסיס, מגדירים את useConnectedDevices ל-false במודול הבדיקה :baselineprofile:

baselineProfile {
    ...
    useConnectedDevices = false
}

baselineProfile {
    ...
    useConnectedDevices false
}

יצירת פרופילים של Baseline לווריאנטים שונים

אתם יכולים ליצור פרופילים של תצורת הבסיס לכל וריאציה, לכל טעם או כקובץ יחיד לשימוש בכל הווריאציות. אפשר לשלוט בהתנהגות הזו באמצעות הגדרת המיזוג, כמו בדוגמה הבאה, בקובץ build.gradle.kts של האפליקציה או של מודול הספרייה.

baselineProfile {
    mergeIntoMain = true
}

baselineProfile {
    mergeIntoMain true
}

כדי למזג את הפרופילים שנוצרו לכל הווריאציות לפרופיל אחד, מגדירים את mergeIntoMain לערך true. אי אפשר ליצור פרופילים של ביצועים בסיסיים לכל וריאנט כשההגדרה הזו היא true, ולכן יש משימת Gradle אחת שנקראת generateBaselineProfile. הפרופיל מופיע במיקום src/main/generated/baselineProfiles.

כדי להשבית את המיזוג וליצור פרופיל אחד לכל וריאציה, צריך להגדיר את mergeIntoMain לערך false. במקרה הזה, יש כמה משימות Gradle ספציפיות לווריאנט. לדוגמה, אם יש שני טעמים – כמו חינמי ובתשלום – וסוג אחד של גרסת build, המשימות הן:

* `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 לאפליקציות.

יצירה אוטומטית של פרופילי בסיס כשמרכיבים גרסה חדשה

אתם יכולים להגדיר פרופילים של ביצועים בסיסיים כך שייווצרו באופן אוטומטי בכל גרסת build, במקום להשתמש במשימה generateBaselineProfile באופן ידני. במקרה של יצירה אוטומטית, הפרופיל העדכני ביותר נכלל בגרסת ההפצה.

כדי להפעיל יצירה אוטומטית של גרסאות build לפרסום, משתמשים בדגל automaticGenerationDuringBuild:

baselineProfile {
    automaticGenerationDuringBuild = true
}

baselineProfile {
    automaticGenerationDuringBuild true
}

הגדרת הדגל automaticGenerationDuringBuild לערך true מפעילה את יצירת פרופיל בסיסי חדש לכל גרסה. המשמעות היא שהרצת משימת build של גרסת release, כמו ./gradlew:app:assembleRelease, מפעילה גם את :app:generateReleaseBaselineProfile, מתחילה את בדיקות המכשירים של פרופיל הבסיס ויוצרת את ה-build של פרופיל הבסיס שעליו הן פועלות. היצירה האוטומטית עוזרת למשתמשים להשיג את הביצועים הכי טובים, אבל היא גם מאריכה את זמן הבנייה בגלל הבנייה הכפולה ובדיקות המכשור.

אפשר גם לציין את ההתנהגות הזו לכל וריאציה, כמו בדוגמה הבאה:

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

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

בדוגמה הקודמת, המשימה generateFreeReleaseBaselineProfile מופעלת כשמתחילים את assembleFreeRelease. זה שימושי כשרוצים, לדוגמה, ליצור release להפצה שתמיד יוצרת את הפרופיל בזמן ה-build, ו-build של releaseWithoutProfile לבדיקות פנימיות.

במקום להוסיף וריאציה חדשה ללא פרופיל בסיסי, אפשר גם להשבית את היצירה משורת הפקודה כך:

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

שמירת פרופילים של נתוני בסיס בחנות במקורות

אפשר לאחסן פרופילים של קו בסיס בספריית המקור באמצעות הדגל saveInSrc ב-build.gradle.kts של מודול האפליקציה או הספרייה:

• ‫true: פרופיל ה-Baseline מאוחסן ב- src/<variant>/generated/baselineProfiles. כך תוכלו לשמור את הפרופיל העדכני שנוצר עם המקורות שלכם.
• ‫false: פרופיל Baseline מאוחסן בקבצים הזמניים בספריית הבנייה. כך, כשמבצעים קומיט של הקוד, הפרופיל האחרון שנוצר לא נשמר.

baselineProfile {
    saveInSrc = true
}

baselineProfile {
    saveInSrc true
}

אפשר גם לציין את ההתנהגות הזו לכל גרסה:

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

baselineProfile {
    variants {
        freeRelease {
            saveInSrc true
        }
    }
}

השבתת האזהרות

כברירת מחדל, תוסף Baseline Profile 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 מאפשר לסנן את הכללים של פרופיל Baseline שנוצרו. האפשרות הזו שימושית במיוחד לספריות, אם רוצים להחריג כללי פרופיל למחלקות ולשיטות שמהוות חלק מהתלויות האחרות של אפליקציית הדוגמה או של הספרייה עצמה. המסננים יכולים לכלול או להחריג חבילות וכיתות ספציפיות. אם מציינים רק החרגות, רק כללים תואמים של פרופיל בסיסי מוחרגים וכל השאר נכללים.

הערך של מאפיין המסננים יכול להיות כל אחת מהאפשרויות הבאות:

• שם החבילה מסתיים בתווים כלליים כפולים לחיפוש כדי להתאים לחבילה שצוינה ולכל חבילות המשנה. לדוגמה, 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 לסינון, כי הוא מספק דרך פשוטה יותר לסנן חבילות משנה ומקום אחד להגדרת המודול כולו.

התאמה אישית של סוגי ה-build של פרופיל Baseline ושל השוואה לשוק

תוסף Gradle של פרופיל בסיסי יוצר סוגי build נוספים כדי ליצור את הפרופילים ולהריץ מדדים. סוגי הבנייה האלה מתחילים בקידומות benchmark ו-nonMinified. לדוגמה, עבור סוג הבנייה release, הפלאגין יוצר את סוגי הבנייה benchmarkRelease ו-nonMinifiedRelease. סוגי ה-build האלה מוגדרים אוטומטית לתרחיש השימוש הספציפי, ובדרך כלל לא צריך לבצע בהם התאמה אישית. אבל יש מקרים שבהם עדיין כדאי להחיל כמה אפשרויות מותאמות אישית, למשל כדי להחיל הגדרת חתימה שונה.

אפשר להתאים אישית את סוגי ה-build שנוצרו באופן אוטומטי באמצעות קבוצת משנה של מאפייני סוג ה-build. מאפיינים שלא ניתן להשתמש בהם מוחלפים. בדוגמה הבאה מוצגות דרכים להתאמה אישית של סוגי build נוספים ושל מאפיינים שמוחלפים:

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.5MB. ההגבלה הזו לא חלה על פורמט הטקסט בקובצי המקור, שבדרך כלל גדולים הרבה יותר לפני ההידור. כדי לאמת את הגודל של פרופיל הבסיס הבינארי, מאתרים אותו בארטיפקט של הפלט בקטע assets/dexopt/baseline.prof עבור APK או בקטע BUNDLE-METADATA/com.android.tools.build.profiles/baseline.prof עבור AAB.

• כללים רחבים שמקמפלים יותר מדי מהאפליקציה עלולים להאט את ההפעלה בגלל גישה מוגברת לדיסק. אם אתם רק מתחילים להשתמש בפרופילים של תצורת ברירת המחדל, אין צורך לדאוג לגבי זה. עם זאת, בהתאם לאפליקציה ולגודל ולמספר של מסלולי ההמרות, הוספה של הרבה מסלולי המרות עלולה להוביל לביצועים לא אופטימליים. כדי לבדוק את הביצועים של האפליקציה, כדאי לנסות פרופילים שונים ולוודא שהביצועים לא יורדים אחרי ההוספות.

Codelabs