כתיבת יישומי פלאגין של Gradle

פלאגין של Android Gradle‏ (AGP) הוא מערכת ה-build הרשמית לאפליקציות ל-Android. הוא כולל תמיכה בהידור של סוגים רבים ושונים של מקורות וקישור שלהם לאפליקציה שאפשר להריץ במכשיר Android פיזי או באמולטור.

‫AGP מכיל נקודות הרחבה לתוספים כדי לשלוט בקלט של הבנייה ולהרחיב את הפונקציונליות שלו באמצעות שלבים חדשים שאפשר לשלב עם משימות בנייה רגילות. בגרסאות קודמות של AGP לא היו ממשקי API רשמיים שהופרדו בצורה ברורה מהטמעות פנימיות. החל מגרסה 7.0, ל-AGP יש קבוצה של ממשקי API רשמיים ויציבים שאפשר להסתמך עליהם.

מחזור החיים של AGP API

‫AGP פועל לפי מחזור החיים של התכונות ב-Gradle כדי לציין את המצב של ממשקי ה-API שלו:

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

מדיניות הוצאה משימוש

‫AGP מתפתח עם הוצאה משימוש של ממשקי API ישנים והחלפה שלהם בממשקי API חדשים ויציבים ובשפה חדשה ספציפית לדומיין (DSL). השינוי הזה יתבצע בכמה גרסאות של AGP, ומידע נוסף זמין בציר הזמן של המעבר ל-AGP API/DSL.

כשמוציאים משימוש ממשקי AGP API, לצורך ההעברה הזו או מסיבות אחרות, הם ממשיכים להיות זמינים בגרסה הראשית הנוכחית, אבל מוצגות אזהרות לגביהם. ממשקי API שהוצאו משימוש יוסרו לחלוטין מ-AGP בגרסה הראשית הבאה. לדוגמה, אם הוצא משימוש ממשק API ב-AGP 7.0, הוא יהיה זמין בגרסה הזו ויציג אזהרות. ממשק ה-API הזה לא יהיה זמין יותר ב-AGP 8.0.

כדי לראות דוגמאות לשימוש בממשקי API חדשים בהתאמות אישיות נפוצות של build, אפשר לעיין במתכונים לפלאגין של Android Gradle. הם מספקים דוגמאות להתאמות אישיות נפוצות של בנייה. בנוסף, במאמרי העזרה מפורט מידע נוסף על ממשקי ה-API החדשים.

הבסיס של בניית Gradle

המדריך הזה לא כולל את כל מערכת ה-build של Gradle. עם זאת, הוא כולל את קבוצת המושגים המינימלית שצריך להכיר כדי לשלב את ה-APIs שלנו, וכולל קישורים למסמכי Gradle הראשיים לקריאה נוספת.

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

מילון מונחים של סוגים עצלים ב-Gradle

ל-Gradle יש כמה סוגים שמתנהגים בצורה 'עצלנית' או עוזרים לדחות חישובים כבדים או Task יצירה לשלבים מאוחרים יותר של הבנייה. הסוגים האלה הם הבסיס להרבה ממשקי API של Gradle ו-AGP. הרשימה הבאה כוללת את הסוגים העיקריים של Gradle שמשתתפים בהפעלה עצלה, ואת השיטות העיקריות שלהם.

Provider<T>

הפונקציה מחזירה ערך מסוג T (כאשר T מייצג כל סוג), שאפשר לקרוא אותו במהלך שלב ההרצה באמצעות get() או להמיר אותו לערך חדש מסוג Provider<S> (כאשר S מייצג סוג אחר) באמצעות השיטות map(),‏ flatMap() ו-zip(). שימו לב שאסור לקרוא ל-get() במהלך שלב ההגדרה.

‫map(): מקבל lambda ומפיק Provider מסוג S,‏ Provider<S>. הארגומנט lambda של map() מקבל את הערך T ומחזיר את הערך S. פונקציית ה-lambda לא מופעלת באופן מיידי, אלא ההפעלה שלה נדחית לרגע שבו קוראים ל-get() ב-Provider<S> שמתקבל, וכך כל השרשרת מתבצעת באופן עצלני.
‫flatMap(): מקבלת גם פונקציית LAMBDA ומחזירה את הערך Provider<S>, אבל פונקציית ה-LAMBDA מקבלת ערך T ומחזירה את הערך Provider<S> (במקום להחזיר את הערך S ישירות). משתמשים ב-flatMap() כשאי אפשר לקבוע את S בזמן ההגדרה ואפשר לקבל רק Provider<S>. מבחינה מעשית, אם השתמשתם ב-map() וקיבלתם תוצאה מסוג Provider<Provider<S>>, כנראה שהיה עליכם להשתמש ב-flatMap() במקום זאת.
‫zip(): מאפשרת לשלב שני מופעים של Provider כדי ליצור Provider חדש, עם ערך שמחושב באמצעות פונקציה שמשלבת את הערכים משני מופעי הקלט של Providers.

Property<T>

Implements Provider<T>, so it also provides a value of type T. בשונה מ-Provider<T>, שהוא לקריאה בלבד, אפשר גם להגדיר ערך ל-Property<T>. יש שתי דרכים לעשות זאת:

אם הערך מסוג T זמין, צריך להגדיר אותו ישירות בלי לבצע חישובים מושהים.
מגדירים עוד Provider<T> כמקור הערך של Property<T>. במקרה הזה, הערך T ממומש רק כשמתבצעת קריאה ל-Property.get().

TaskProvider

מטמיע את Provider<Task>. כדי ליצור TaskProvider, משתמשים ב-tasks.register() ולא ב-tasks.create(), כדי להבטיח שהמשימות יופעלו רק כשצריך. אפשר להשתמש ב-flatMap() כדי לגשת לפלט של Task לפני ש-Task נוצר. זה יכול להיות שימושי אם רוצים להשתמש בפלט כקלט למופעים אחרים של Task.

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

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

הנה דוגמה לרישום של שתי משימות, GitVersionTask ו-ManifestProducerTask, תוך דחיית היצירה של מופעי Task עד שהם נדרשים בפועל. ערך הקלט ManifestProducerTask מוגדר ל-Provider שמתקבל מהפלט של GitVersionTask, ולכן ManifestProducerTask תלוי ב-GitVersionTask באופן מרומז.

// Register a task lazily to get its TaskProvider.
val gitVersionProvider: TaskProvider =
    project.tasks.register("gitVersionProvider", GitVersionTask::class.java) {
        it.gitVersionOutputFile.set(
            File(project.buildDir, "intermediates/gitVersionProvider/output")
        )
    }

...

/**
 * Register another task in the configuration block (also executed lazily,
 * only if the task is required).
 */
val manifestProducer =
    project.tasks.register(variant.name + "ManifestProducer", ManifestProducerTask::class.java) {
        /**
         * Connect this task's input (gitInfoFile) to the output of
         * gitVersionProvider.
         */
        it.gitInfoFile.set(gitVersionProvider.flatMap(GitVersionTask::gitVersionOutputFile))
    }

שתי המשימות האלה יתבצעו רק אם תהיה בקשה מפורשת לכך. זה יכול לקרות כחלק מהפעלת Gradle, למשל אם מריצים את הפקודה ./gradlew debugManifestProducer, או אם הפלט של ManifestProducerTask מחובר למשימה אחרת והערך שלו נדרש.

אתם יכולים לכתוב משימות מותאמות אישית שצורכות קלט או מייצרות פלט, אבל אין לכם גישה ישירה למשימות של AGP. הם פרטי הטמעה שנתונים לשינוי מגרסה לגרסה. במקום זאת, AGP מציע את Variant API וגישה לפלט של המשימות שלו, או build artifacts, שאפשר לקרוא ולשנות. מידע נוסף זמין במאמר Variant API, Artifacts, and Tasks.

שלבי build של Gradle

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

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

שלב ההגדרה

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

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

שלב הביצוע

בשלב הביצוע, המשימות המבוקשות והמשימות שתלויות בהן מבוצעות. באופן ספציפי, מופעלות שיטות המחלקה Task שמסומנות ב-@TaskAction. במהלך ביצוע המשימה, מותר לקרוא נתונים מקלט (כמו קבצים) ולפתור ספקי lazy על ידי קריאה ל-Provider<T>.get(). פתרון של lazy providers בדרך הזו מפעיל רצף של קריאות map() או flatMap() שפועלות לפי מידע על תלות במשימות שכלול ב-provider. המשימות מופעלות באופן עצלני כדי ליצור את הערכים הנדרשים.

‫Variant API,‏ Artifacts ו-Tasks

‫Variant API הוא מנגנון הרחבה בפלאגין של Android Gradle שמאפשר לכם לשנות את האפשרויות השונות, שבדרך כלל מוגדרות באמצעות DSL בקובצי הגדרות ה-build, שמשפיעות על ה-build של Android. ‫Variant API גם מאפשר לכם לגשת לארטיפקטים ביניים וסופיים שנוצרים על ידי ה-build, כמו קובצי מחלקה, המניפסט שעבר מיזוג או קובצי APK/AAB.

תהליך ה-build של Android ונקודות ההרחבה

כשמבצעים אינטראקציה עם AGP, צריך להשתמש בנקודות הרחבה שנוצרו במיוחד במקום לרשום את הקריאות החוזרות הרגילות של מחזור החיים של Gradle (כמו afterEvaluate()) או להגדיר תלות מפורשת ב-Task. משימות שנוצרו על ידי AGP נחשבות לפרטי הטמעה ולא מוצגות כ-API ציבורי. אסור לנסות לקבל מופעים של אובייקטים מסוג Task או לנחש את השמות של Task ולהוסיף קריאות חוזרות או תלות לאובייקטים האלה ישירות.Task

‫AGP מבצע את השלבים הבאים כדי ליצור ולהפעיל את המופעים של Task, שבתורם יוצרים את תוצרי הבנייה. אחרי השלבים העיקריים שקשורים ליצירת אובייקט Variant, מתבצעות קריאות חוזרות שמאפשרות לכם לבצע שינויים באובייקטים מסוימים שנוצרו כחלק מהבנייה. חשוב לציין שכל הקריאות החוזרות מתרחשות במהלך שלב ההגדרה (שמתואר בדף הזה) והן חייבות לפעול במהירות. במקום זאת, כל פעולה מורכבת צריכה להתבצע במהלך שלב ההרצה על ידי מופעים מתאימים של Task.

ניתוח DSL: זה קורה כשסביבת ה-DSL של Android מעריכה את סקריפטים הבנייה, ויוצרת ומגדירה את המאפיינים השונים של אובייקטים של Android DSL מתוך הבלוק android. במהלך השלב הזה נרשמים גם הקבלאקים של Variant API שמתוארים בקטעים הבאים.
‫finalizeDsl(): קריאה חוזרת שמאפשרת לשנות אובייקטים של DSL לפני שהם ננעלים ליצירת רכיב (וריאציה). אובייקטים מסוג VariantBuilder נוצרים על סמך נתונים שנכללים באובייקטים של DSL.
נעילת DSL: ה-DSL נעול עכשיו ואי אפשר לבצע יותר שינויים.
‫beforeVariants(): הקריאה החוזרת הזו יכולה להשפיע על הרכיבים שנוצרים ועל חלק מהמאפיינים שלהם, באמצעות VariantBuilder. היא עדיין מאפשרת לבצע שינויים בתהליך הבנייה ובפריטי המידע שנוצרים.
יצירת וריאנטים: רשימת הרכיבים והארטיפקטים שייווצרו סופית ואי אפשר לשנות אותה.
‫onVariants(): בפונקציית הקריאה החוזרת הזו, מקבלים גישה לאובייקטים שנוצרו Variant ואפשר להגדיר ערכים או ספקים לערכים Property שהם מכילים, כדי שהחישוב יתבצע רק כשצריך.
נעילת וריאנטים: אובייקטים של וריאנטים נעולים עכשיו ואי אפשר לבצע בהם שינויים.
משימות שנוצרו: נעשה שימוש באובייקטים של Variant ובערכים של Property כדי ליצור את המופעים של Task שנדרשים לביצוע הבנייה.

‫AGP מציג את AndroidComponentsExtension שמאפשר לרשום קריאות חוזרות (callback) עבור finalizeDsl(), ‏ beforeVariants() ו-onVariants(). התוסף זמין בסקריפטים של build דרך הבלוק androidComponents:

// This is used only for configuring the Android build through DSL.
android { ... }

// The androidComponents block is separate from the DSL.
androidComponents {
   finalizeDsl { extension ->
      ...
   }
}

עם זאת, אנחנו ממליצים להשתמש בסקריפטים של build רק להגדרה הצהרתית באמצעות ה-DSL של הבלוק android, ולהעביר כל לוגיקה אימפרטיבית בהתאמה אישית אל buildSrc או אל תוספים חיצוניים. אפשר גם לעיין בbuildSrc דוגמאות במאגר המתכונים של Gradle ב-GitHub כדי ללמוד איך ליצור תוסף בפרויקט. דוגמה לרישום של פונקציות הקריאה החוזרת מקוד הפלאגין:

abstract class ExamplePlugin: Plugin<Project> {

    override fun apply(project: Project) {
        val androidComponents = project.extensions.getByType(AndroidComponentsExtension::class.java)
        androidComponents.finalizeDsl { extension ->
            ...
        }
    }
}

בואו נבחן מקרוב את הפונקציות הזמינות של Callback ואת סוגי תרחישי השימוש שהתוסף יכול לתמוך בהם בכל אחת מהן:

`finalizeDsl(callback: (DslExtensionT) -> Unit)`

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

abstract class ExamplePlugin: Plugin<Project> {

    override fun apply(project: Project) {
        val androidComponents = project.extensions.getByType(AndroidComponentsExtension::class.java)
        androidComponents.finalizeDsl { extension ->
            extension.buildTypes.create("extra").let {
                it.isJniDebuggable = true
            }
        }
    }
}

`beforeVariants()`

בשלב הזה של הבנייה, מקבלים גישה לאובייקטים של VariantBuilder, שקובעים את הווריאציות שייווצרו ואת המאפיינים שלהן. לדוגמה, אפשר להשבית באופן פרוגרמטי גרסאות מסוימות, את הבדיקות שלהן או לשנות את הערך של מאפיין (למשל minSdk) רק עבור גרסה נבחרת. בדומה ל-finalizeDsl(), כל הערכים שאתם מספקים צריכים להיות מוגדרים בזמן ההגדרה ולא להיות תלויים בקלט חיצוני. אסור לשנות את האובייקטים VariantBuilder אחרי שהפונקציה beforeVariants() callback מסיימת את ההרצה.

androidComponents {
    beforeVariants { variantBuilder ->
        variantBuilder.minSdk = 23
    }
}

הקריאה החוזרת beforeVariants() יכולה לקבל אופציונלית את VariantSelector, שאפשר לקבל באמצעות המתודה selector() ב-androidComponentsExtension. אפשר להשתמש בו כדי לסנן רכיבים שמשתתפים בהפעלת הקריאה החוזרת על סמך השם, סוג ה-build או גרסת המוצר שלהם.

androidComponents {
    beforeVariants(selector().withName("adfree")) { variantBuilder ->
        variantBuilder.minSdk = 23
    }
}

`onVariants()`

בזמן הקריאה ל-onVariants(), כל הארטיפקטים שייווצרו על ידי AGP כבר נקבעו, ולכן אי אפשר יותר להשבית אותם. עם זאת, אפשר לשנות חלק מהערכים שמשמשים למשימות על ידי הגדרתם במאפייני Property באובייקטים Variant. מכיוון שהערכים של Property יתקבלו רק כשמשימות AGP יבוצעו, אפשר לחבר אותם בבטחה לספקי מידע ממשימות מותאמות אישית משלכם שיבצעו את כל החישובים הנדרשים, כולל קריאה מקלטים חיצוניים כמו קבצים או הרשת.

// onVariants also supports VariantSelectors:
onVariants(selector().withBuildType("release")) { variant ->
    // Gather the output when we are in single mode (no multi-apk).
    val mainOutput = variant.outputs.single { it.outputType == OutputType.SINGLE }

    // Create version code generating task
    val versionCodeTask = project.tasks.register("computeVersionCodeFor${variant.name}", VersionCodeTask::class.java) {
        it.outputFile.set(project.layout.buildDirectory.file("${variant.name}/versionCode.txt"))
    }
    /**
     * Wire version code from the task output.
     * map() will create a lazy provider that:
     * 1. Runs just before the consumer(s), ensuring that the producer
     * (VersionCodeTask) has run and therefore the file is created.
     * 2. Contains task dependency information so that the consumer(s) run after
     * the producer.
     */
    mainOutput.versionCode.set(versionCodeTask.map { it.outputFile.get().asFile.readText().toInt() })
}

הוספת מקורות שנוצרו ל-build

תוסף יכול ליצור כמה סוגים של מקורות שנוצרו על ידי AI, כמו:

קוד האפליקציה בספרייה java
משאבי Android בספרייה res
Java resources בספרייה resources
נכסי Android בספרייה assets

רשימה מלאה של המקורות שאפשר להוסיף זמינה במאמר בנושא Sources API.

בקטע הקוד הזה אפשר לראות איך מוסיפים ל-Java source set תיקיית מקור בהתאמה אישית בשם ${variant.name} באמצעות הפונקציה addStaticSourceDirectory(). לאחר מכן, ערכת הכלים של Android מעבדת את התיקייה הזו.

onVariants { variant ->
    variant.sources.java?.let { java ->
        java.addStaticSourceDirectory("custom/src/kotlin/${variant.name}")
    }
}

פרטים נוספים זמינים במאמר בנושא addJavaSource recipe.

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

onVariants(selector().withBuildType("release")) { variant ->
    // Step 1. Register the task.
    val resCreationTask =
       project.tasks.register<ResCreatorTask>("create${variant.name}Res")

    // Step 2. Register the task output to the variant-generated source directory.
    variant.sources.res?.addGeneratedSourceDirectory(
       resCreationTask,
       ResCreatorTask::outputDirectory)
    }

...

// Step 3. Define the task.
abstract class ResCreatorTask: DefaultTask() {
   @get:OutputFiles
   abstract val outputDirectory: DirectoryProperty

   @TaskAction
   fun taskAction() {
      // Step 4. Generate your resources.
      ...
   }
}

פרטים נוספים זמינים במאמר בנושא addCustomAsset recipe.

גישה לפריטי מידע שנוצרים בתהליך פיתוח (Artifact) ושינוי שלהם

בנוסף לאפשרות לשנות מאפיינים פשוטים באובייקטים Variant, ‏ AGP כולל גם מנגנון הרחבה שמאפשר לקרוא או לשנות ארטיפקטים ביניים וארטיפקטים סופיים שנוצרו במהלך ה-build. לדוגמה, אתם יכולים לקרוא את התוכן של קובץ AndroidManifest.xml סופי וממוזג בTask בהתאמה אישית כדי לנתח אותו, או להחליף את התוכן שלו לגמרי בתוכן של קובץ מניפסט שנוצר על ידי Task בהתאמה אישית.

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

עוצמה (cardinality)

העוצמה (cardinality) של Artifact מייצגת את מספר המקרים של FileSystemLocation, או את מספר הקבצים או הספריות של סוג הארטיפקט. כדי לקבל מידע על הקרדינליות של פריט מידע שנוצר בתהליך פיתוח (Artifact), צריך לבדוק את מחלקת האב שלו: פריטי מידע שנוצרו בתהליך פיתוח עם FileSystemLocation יחיד יהיו מחלקת משנה של Artifact.Single, ופריטי מידע שנוצרו בתהליך פיתוח עם כמה מופעים של FileSystemLocation יהיו מחלקת משנה של Artifact.Multiple.

סוג `FileSystemLocation`

כדי לבדוק אם Artifact מייצג קבצים או ספריות, אפשר להסתכל על סוג הפרמטרים שלו FileSystemLocation, שיכול להיות RegularFile או Directory.

פעולות נתמכות

כל מחלקה של Artifact יכולה להטמיע כל אחד מהממשקים הבאים כדי לציין אילו פעולות היא תומכת בהן:

‫Transformable: מאפשר להשתמש ב-Artifact כקלט ל-Task שמבצע עליו טרנספורמציות שרירותיות ומפיק גרסה חדשה של Artifact.
‫Appendable: חל רק על ארטיפקטים שהם מחלקות משנה של Artifact.Multiple. המשמעות היא שאפשר להוסיף ל-Artifact, כלומר Artifact בהתאמה אישית יכול ליצור מופעים חדשים של סוג ה-Artifact הזה שיתווספו לרשימה הקיימת.Task
‫Replaceable: חל רק על ארטיפקטים שהם מחלקות משנה של Artifact.Single. אפשר להחליף Artifact במופע חדש לגמרי, שנוצר כפלט של Task.

בנוסף לשלוש הפעולות שמשנות את הארטיפקט, כל ארטיפקט תומך בפעולה get() (או getAll()), שמחזירה Provider עם הגרסה הסופית של הארטיפקט (אחרי שכל הפעולות בו הסתיימו).

תוספים מרובים יכולים להוסיף כל מספר של פעולות על ארטיפקטים לפייפליין מהקריאה החוזרת onVariants(), ו-AGP יוודא שהן משורשרות בצורה נכונה, כך שכל המשימות יפעלו בזמן הנכון והארטיפקטים ייווצרו ויתעדכנו בצורה נכונה. כלומר, כשפעולה משנה פלט כלשהו על ידי הוספה, החלפה או שינוי שלו, הפעולה הבאה תראה את הגרסה המעודכנת של הארטיפקטים האלה כקלט, וכן הלאה.

נקודת הכניסה לרישום פעולות היא המחלקה Artifacts. בקטע הקוד הבא אפשר לראות איך מקבלים גישה למופע של Artifacts ממאפיין באובייקט Variant בקריאה החוזרת onVariants().

לאחר מכן אפשר להעביר את TaskProvider המותאם אישית כדי לקבל אובייקט TaskBasedOperation (1), ולהשתמש בו כדי לחבר את הקלט והפלט שלו באמצעות אחת מהשיטות של wiredWith* (2).

השיטה המדויקת שצריך לבחור תלויה בקרדינליות ובFileSystemLocationסוג שהוטמעו על ידי Artifact שרוצים לשנות.

לבסוף, מעבירים את הטיפוס Artifact לשיטה שמייצגת את הפעולה שנבחרה באובייקט *OperationRequest שמתקבל בתמורה, לדוגמה, toAppendTo(),‏ toTransform() או toCreate() (3).

androidComponents.onVariants { variant ->
    val manifestUpdater = // Custom task that will be used for the transform.
            project.tasks.register(variant.name + "ManifestUpdater", ManifestTransformerTask::class.java) {
                it.gitInfoFile.set(gitVersionProvider.flatMap(GitVersionTask::gitVersionOutputFile))
            }
    // (1) Register the TaskProvider w.
    val variant.artifacts.use(manifestUpdater)
         // (2) Connect the input and output files.
        .wiredWithFiles(
            ManifestTransformerTask::mergedManifest,
            ManifestTransformerTask::updatedManifest)
        // (3) Indicate the artifact and operation type.
        .toTransform(SingleArtifact.MERGED_MANIFEST)
}

בדוגמה הזו, MERGED_MANIFEST הוא SingleArtifact, והוא RegularFile. לכן, אנחנו צריכים להשתמש בשיטה wiredWithFiles, שמקבלת הפניה אחת ל-RegularFileProperty כקלט, ו-RegularFileProperty אחד כפלט. יש עוד wiredWith* שיטות במחלקה TaskBasedOperation שיעבדו לשילובים אחרים של Artifact קרדינליות וסוגים של FileSystemLocation.

כדי לקבל מידע נוסף על הרחבת AGP, מומלץ לקרוא את הקטעים הבאים במדריך למערכת ה-build של Gradle: