הגדרת וריאציות של אתר חדשות

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

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

לפני שממשיכים, צריך לוודא להכין את הספרייה שלכם להפצה.

שימוש במטא-נתונים של מודול Gradle

כדי לפרסם וריאנטים של הספרייה, צריך להשתמש ב- מטא-נתונים של Gradle Module (GMM). GMM מתאר את אתר החדשות ומתחזק ניהול תלות מבוססת-וריאנט. GMM מפורסם יחד עם הספרייה שלכם כברירת מחדל.

יתרונות השימוש ב-GMM כוללים:

• אם משתמשים ב-GMM עם Gradle מגרסה 6.0 ואילך, אפשר לפרסם כמה אתרי חדשות וריאציות או ארטיפקטים מרובים – לכל אחד מהם יש מאפיינים ויחסי תלות משלו. אם משתמשים בקובץ POM של Maven במקום GMM, אפשר לפרסם רק פריט מידע אחד שנוצר בתהליך הפיתוח (Artifact). אם משתמשים בקובץ POM, יכולים לפרסם פריטי מידע נוספים שנוצרים באמצעות מסווגים, אבל פריטי המידע הנוספים לא יכולים להיות יחסי תלות משלהם.
• Gradle יוצרת באופן אוטומטי וריאנט אחד להידור וגרסה אחת לזמן ריצה, שלכל אחד מהן יחסי תלות משלו. אפשר לפרסם וריאנט אחד לצורך הידור והשני הוא סביבת זמן הריצה, כך שהצרכן יכול לבחור בהתאם לזמן שבו הוא משתמש בספרייה שלך. GMM מאפשר לצרכנים לראות יחסי תלות שונים על סמך השימוש שהספרייה פורסמה api, implementation או compileOnly מתוך runtimeOnly. צפייה הגדרות תלות לרשימה מלאה של יחסי התלות. האפשרות הזו זמינה גם אם פרסמת הווריאנט של אתר החדשות.
• כשמשתמשים באביזרי בדיקה, אפשר לפרסם וריאציה נוספת עם מטא-נתונים או יכולות שמאפשרים לצרכנים לבחור בה. האפשרות הזו זמינה גם אם מפרסמים וריאנט אחד של אתר חדשות.

הסבר על הווריאציות של אתר החדשות

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

• יצירת וריאנט: התצורה ש-Gradle משתמש בה כדי לבנות את הספרייה שלכם, הוא השילוב בין סוג ה-build לטעם של המוצר. מידע נוסף זמין במאמר הבא: מילון מונחים בנושא build של Android.
• Artifact: קובץ או ספרייה שנוצרים על ידי build. בהקשר של פרסום בספרייה, ארטיפקט הוא בדרך כלל קובץ JAR או AAR.
• וריאנט של אתר החדשות: פריט מידע שנוצר בתהליך הפיתוח (Artifact) עם המאפיינים, התכונות ויחסי התלות שמשויכים אליו. הערה ש-Gradle מכנה את הווריאנטים של אתר החדשות לוריאציות. אבל הם נקראים וריאציות פרסום במסמכים האלה כדי להבדיל בינן לבין ליצור וריאציות.
• מאפיין: ב-Gradle נעשה שימוש במאפיינים כדי לזהות ולבחור וריאנטים של אתר חדשות, יש כמה אפשרויות. לדוגמה, org.gradle.usage=java-api וגם org.gradle.jvm.version=11 הם מאפייני וריאציה.
• רכיב תוכנה: אובייקט Gradle שיכול להכיל וריאנט אחד או יותר של אתר חדשות, והוא מתפרסם לקבוצה אחת של קואורדינטות Maven (groupdId:artifactId:version). זה כן נחשפו ב-DSL של Gradle Project.getComponents().
• אתר חדשות: מה מפורסם למאגר והצרכנים משתמשים בו. אתרי החדשות כוללים של רכיב תוכנה אחד והמטא-נתונים שלו, למשל, הזהות שלו (groupId:artifactId:version).

הפלאגין של Android Gradle (AGP) 7.1 כולל שפה ספציפית לדומיין (DSL) כדי לקבוע באילו וריאנטים של build ייעשה שימוש פרסום מסוים והמערכת מתעלמת מהם. ה-DSL מאפשר ליצור מופעים של SoftwareComponent שמכילים אחד מהערכים הבאים:

• וריאנט אחד של אתר חדשות מווריאנט אחד של build
• כמה וריאנטים של אתרי חדשות מכמה וריאציות של גרסת build

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

יצירת רכיב תוכנה עם וריאנט אחד של אתר חדשות

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

android {
  publishing {
    singleVariant("release") {
        withSourcesJar()
    }
  }
}

android {
  publishing {
    singleVariant('release') {
        withSourcesJar()
    }
  }
}

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

יצירת רכיב תוכנה עם כמה וריאציות של אתר החדשות

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

כדי לפרסם את כל וריאציות ה-build ברכיב אחד, צריך לציין allVariants() בבלוק multipleVariants{} בקובץ build.gradle ברמת המודול:

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

android {
  publishing {
    multipleVariants {
      allVariants()
      withJavadocJar()
    }
  }
}

הפעולה הזו יוצרת רכיב יחיד בשם default. כדי לתת שם לרכיב משהו אחר, צריך להשתמש ב-multipleVariants({name}). במקרה הזה, כל המימדים של סוג ה-build ומאפייני המוצר משמשים בתור .

אפשר גם לבחור אילו וריאציות פורסמו באמצעות includeBuildTypeValues() וגם includeFlavorDimensionAndValues():

android {
  publishing {
    multipleVariants("custom") {
      includeBuildTypeValues("debug", "release")
      includeFlavorDimensionAndValues(
        dimension = "color",
        values = arrayOf("blue", "pink")
      )
        includeFlavorDimensionAndValues(
          dimension = "shape",
          values = arrayOf("square")
      )
    }
  }
}

android {
  publishing {
    multipleVariants('custom') {
      includeBuildTypeValues('debug', 'release')
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'color',
        /*values =*/ 'blue', 'pink'
      )
      includeFlavorDimensionAndValues(
        /*dimension =*/ 'shape',
        /*values =*/ 'square'
      )
    }
  }
}

בדוגמה הזו, הרכיב המותאם אישית מכיל את כל השילובים של (debug, release) לסוג ה-build, (blue, pink) במאפיין color, ו-(square) של המאפיין shape .

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

בטבלה הבאה מפורטים הווריאנטים של אתר החדשות וה במאפיינים שמשויכים אליו.

בפועל, מתפרסמות יותר וריאנטים. לדוגמה, כל אחת מהווריאציות שלמעלה מתפרסם פעמיים, פעם אחת עבור הידור ופעם אחת עבור עם יחסי תלות שונים (בהתאם ליחסי התלות המוצהרים) משתמשים ב-implementation או ב-api) ועם ערך שונה במאפיין org.gradle.Usage. עם זאת, פריטי המידע שנוצרו בתהליך הפיתוח (Artifact) (קובץ AAR) של שתי הווריאציות האלה כמעט זהים.

מידע נוסף זמין במאמר publishing מאמרי העזרה של ה-API.

בעיית תאימות לפרסום ספריות של כמה טעמים

פרויקטים שמשתמשים ב-AGP 7.0 ומטה לא יכולים לצרוך ספריות רב-טעם שפורסמו עם AGP 7.1 ומעלה. זוהי בעיה ידועה, שנגרמה כתוצאה משינוי במאפיין שם המאפיין 'טעם מוצר' מ-dimensionName עד com.android.build.api.attributes.ProductFlavor:dimensionName ב-AGP 7.1. בהתאם להגדרות הפרויקט, אפשר להשתמש ב-missingDimensionStrategy ב- הגרסה הישנה של API כדי לפעול בקשר לבעיה.

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

android {
    applicationVariants.forEach { variant ->
        val flavor = variant.productFlavors[0].name
        val attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        val dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}

android {
    applicationVariants.forEach { variant ->
        def flavor = variant.getProductFlavors()[0].name
        def attributePrefix = "com.android.build.api.attributes.ProductFlavor"
        def dimensionName = "version"
        variant.missingDimensionStrategy("$attributePrefix:$dimensionName", flavor)
    }
}