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

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

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

בדף הזה מוסבר איך להשתמש בפלאגין 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 של הגרסה.

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

baselineProfile {
    automaticGenerationDuringBuild = true
}

baselineProfile {
    automaticGenerationDuringBuild true
}

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

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

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

baselineProfile {
    variants {
        freeRelease {
            automaticGenerationDuringBuild true
        }
    }
}

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

שמירת פרופילים Baseline במקורות

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

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

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

הפלאגין Baseline Profile Gradle יוצר סוגים נוספים של גרסאות build כדי ליצור את הפרופילים ולהריץ את מדדי הביצועים. סוגי ה-build האלה מתחילים ב-benchmark וב-nonMinified. לדוגמה, עבור סוג ה-build release, הפלאגין יוצר את סוגי ה-build 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