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

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

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

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

תרחישים לדוגמה לשימוש בכלי AGP Upgrade Assistant

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

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

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

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

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

איך משתמשים בכלי AGP Upgrade Assistant

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

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

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

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

כדי להפיק את המרב מהכלי AGP Upgrade Assistant, כדאי:

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

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

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

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

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

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

הפעלת הכלי לשדרוג

כדי להפעיל את כלי העזרה לשדרוג:

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

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

   

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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