הכלי Android Gradle plugin (AGP) Upgrade Assistant הוא כלי ב-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. כדי להפיק את המרב מ-Upgrade Assistant, צריך להגדיר את ה-build באמצעות קובצי ה-build האלה. אפשר להשתמש בקטלוגים של גרסאות Gradle כדי להתייחס לתלויות ולפלאגינים שמוגדרים בקובץ
libs.versions.tomlבספריית המשנהgradleשל הפרויקט.
- שימוש בשפה הצהרתית ספציפית לתחום ה-build: קובצי ה-build של Gradle מבוטאים ב-Groovy או ב-Kotlin. עם זאת, ככל שההצהרה של הגדרות הפרויקט מפורטת יותר, כך גדל הסיכוי שכלי העזרה לשדרוג ימצא את כל המקומות שצריך לבצע בהם שינויים כדי לשדרג.
גם אם פרויקט עומד במגבלות האלה, יכול להיות שעוזר השדרוג לא יצליח לבצע שדרוג חלק. במאמר פתרון שגיאות מוסבר איך לפתור באגים או לדווח עליהם.
גיבוי הפרויקט
לפני שמשתמשים בכלי העזרה לשדרוג, מומלץ לוודא שאין בפרויקט שינויים שלא נשמרו, כפי שמוצג במערכת בקרת הגרסאות. אם אתם לא משתמשים בבקרת גרסאות, בשלב הזה כדאי להשתמש בגיבוי של גרסה טובה אחרונה.
אחרי שמריצים את כלי העזרה לשדרוג, והפרויקט נבנה ונבדק בהצלחה, אפשר לבצע קומיט של הגרסה החדשה של הפרויקט במערכת בקרת הגרסאות.
הפעלת הכלי לשדרוג
כדי להפעיל את כלי השדרוג, מבצעים את השלבים הבאים:
כדי להפעיל את כלי העזרה לשדרוג, עוברים אל Tools > AGP Upgrade Assistant או לוחצים על ההודעה שמופיעה, כמו שמוצג באיור 1.
בחלון הכלים שמופיע מוצגים הפרטים של השדרוג שמוגדר כברירת מחדל, כולל הגרסה הנוכחית של AGP בפרויקט והגרסה העדכנית שנתמכת על ידי הגרסה הזו של Android Studio.
איור 1. חלון הכלי AGP Upgrade Assistant כשמפעילים אותו באמצעות ההודעה. בודקים את השלבים הנדרשים והמומלצים.
בחלונית הימנית, בעץ עם תיבות הסימון מפורטות הפעולות השונות בשדרוג, והן מסווגות לפי חובה או המלצה לעדכון ולפי דרישות מוקדמות לפעולות אחרות. בוחרים פריטים בודדים בתצוגת העץ כדי להציג פרטים נוספים על כל שלב בחלונית הראשית.
כדי להריץ את השדרוג, בוחרים את השלבים הנדרשים והרצויים ולוחצים על הפעלת השלבים שנבחרו.
הכלי Upgrade Assistant משנה את קובצי ה-build של הפרויקט ומנסה לסנכרן את ה-build החדש של הפרויקט עם Android Studio. אם יש לכם מודולים רבים, התהליך עשוי להימשך זמן מה, כי יכול להיות שיהיה צורך להוריד גרסאות חדשות של תוספים וספריות.
בודקים את הדוח שאחרי השדרוג. בדוח הזה מתוארים השלבים שהושלמו, ומופיע בו מידע על הצלחת השדרוג. הוא כולל גם פעולה להחזרת שינויים שבוצעו על ידי כלי העזרה לשדרוג, אם יש בעיות בבנייה או בבדיקה של הפרויקט אחרי השדרוג.
אחרי שהפרויקט מסתנכרן עם Android Studio, צריך לבצע build של הפרויקט ולהריץ חבילות בדיקה כדי לוודא שפעולת השדרוג לא שינתה שום פונקציונליות.
אחרי שמוודאים שהפרויקט במצב תקין, מבצעים קומיט של הגרסה החדשה של הפרויקט למערכת בקרת הגרסאות.
פתרון בעיות במקרה של שגיאות
אם כלי העזרה לשדרוג מציע שדרוג אבל השדרוג נכשל, בדרך כלל זה קורה בגלל שינויים שבוצעו בקובצי ה-build, שגורמים לכשל בסנכרון. כדי לבודד את השגיאה ולתקן אותה, צריך לפעול לפי השלבים הבאים:
קודם כל, בודקים את השגיאה שגרמה לכשל בסנכרון. לפעמים השגיאה נובעת מסיבה ברורה, שאפשר לטפל בה בקובצי הבנייה של הפרויקט.
אם הודעת השגיאה לא ברורה, או שלא ברור מה גורם לבעיה, צריך להחזיר את הפרויקט למצב המקורי כדי לחלק את השדרוג לשלבים קטנים יותר. משחזרים את המצב המקורי מניהול הגרסאות או מגיבויים, ומוודאים שהפרויקט במצב המקורי ושהוא מסונכרן עם Android Studio.
כדי לחקור את השגיאה, אפשר לעיין בשני סוגים של פירוט השדרוג:
שדרוג לגרסה אחרת של AGP שאינה הגרסה האחרונה. אם השדרוג שנכשל היה שדרוג של מספר גדול של גרסאות, הדרך הכי טובה לבודד את הבעיה היא לבצע סדרה של שדרוגים קטנים יותר, מגרסה לגרסה, כדי למצוא את השדרוג הראשון שגורם לבעיה.
במהלך השדרוג, מבצעים כל שלב בנפרד. אחרי שמזהים את העדכון שגורם לבעיה, יכול להיות שאפשר להשבית שלבים ספציפיים בעדכון. אם זה אפשרי, כדאי לנסות לבצע כל שלב בנפרד כדי לזהות איזה מהשלבים גורם לשגיאה. אם לא הצלחתם למצוא את השלב הבעייתי, כדאי לבדוק את הערות הגרסה של כל פלאגין אחר של Gradle שבו אתם משתמשים, כדי לראות אם יש בעיות תאימות עם Gradle או AGP. לפעמים, גרסה חדשה מטפלת בשימוש בממשקי API שהוצאו משימוש או בממשקי API פנימיים.
דיווח על באג לפעמים כל שלבי ההכנה והסנכרון מצליחים, אבל שלב השדרוג הסופי עדיין נכשל. במקרה כזה, צריך לדווח על באג. גם אם הצלחתם לתקן את השגיאה בעצמכם, כדאי לדווח על הכשל המקורי לכלי למעקב אחרי באגים, כדי שצוות הפיתוח יוכל לטפל בבעיה.