שימוש ב'עוזר הדיגיטלי לשדרוג הפלאגין של Android Gradle'

‫Android Gradle plugin (AGP) Upgrade Assistant הוא כלי ב-Android Studio שעוזר לשדרג את גרסת ה-AGP שבה משתמשים בפרויקט.

android skills add agp-9-upgrade

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

מידע נוסף על מבנה הפרויקט המומלץ ל-Upgrade Assistant זמין בקטע הגדרה בדף הזה.

תרחישים לדוגמה של עוזר השדרוג של AGP

כלי השדרוג של AGP מדריך אתכם בשינויים שצריך לבצע כדי לשדרג את גרסאות AGP. אלה התרחישים הנפוצים ביותר לשימוש ב-Upgrade Assistant:

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

• דרישות תאימות בין AGP ל-Gradle: כלי השדרוג מזהה את דרישות התאימות בין AGP ל-Gradle ועוזר לוודא שאתם משתמשים בגרסת Gradle שנדרשת לגרסת AGP שלכם.

• דרישות תאימות בין AGP לבין פלאגינים של Gradle של צד שלישי: כלי השדרוג מודע לדרישות התאימות בין AGP לבין פלאגינים מסוימים של Gradle של צד שלישי, ועוזר לוודא שאתם משתמשים בגרסאות של פלאגינים של Gradle של צד שלישי שנדרשות לגרסת ה-AGP שלכם.

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

איך משתמשים ב-AGP Upgrade Assistant

כדי להשתמש בכלי Upgrade Assistant, צריך לוודא שמבנה הפרויקט מתאים לכלי, ואז להפעיל אותו מ-Android Studio, כמו שמתואר בקטע הפעלת Upgrade Assistant.

הגדרת הפרויקט

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

מבנה הפרויקט באמצעות קובצי ה-build של Gradle ושפה ספציפית לדומיין

כדי להפיק את המרב מכלי השדרוג של AGP, צריך לבצע את הפעולות הבאות:

• הגדרת ה-build באמצעות קובצי ה-build של Gradle: כלי השדרוג מסתמך על ניתוח סטטי של קובצי ה-build של Gradle. כדי להפיק את המקסימום מכלי השדרוג, כדאי להגדיר את ה-build באמצעות קובצי ה-build האלה. משתמשים בקטלוגים של גרסאות Gradle כדי להפנות לתלויות ולפלאגינים שמוגדרים בקובץ libs.versions.toml בספריית המשנה gradle של הפרויקט.

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

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

גיבוי הפרויקט

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

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

הפעלת Upgrade Assistant

כדי להפעיל את Upgrade Assistant, פועלים לפי השלבים הבאים:

1. כדי להפעיל את Upgrade Assistant, עוברים אל Tools > AGP Upgrade Assistant או לוחצים על ההודעה, כמו שמוצג באיור 1.

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

   

2. בודקים את השלבים הנדרשים והמומלצים.

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

3. כדי להריץ את השדרוג, בוחרים את השלבים הנדרשים והרצויים ולוחצים על Run selected steps.

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

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

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

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

פתרון בעיות במקרה של שגיאות

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

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

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

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

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

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

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