מעבר מ-Xcode ל-Bazel

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

הבדלים בין Xcode לבין Bazel

• Bazel דורש ממך לציין במפורש כל יעד build ותלות שלו, וכן את הגדרות ה-build התואמות באמצעות כללי build.

• Bazel מחייב שכל הקבצים שבהם הפרויקט יהיה קיים בספרייה של סביבת העבודה או שהוא יצוין כייבוא בקובץ WORKSPACE.

• כשבונים פרויקטים של Xcode באמצעות Bazel, קובצי BUILD הופכים למקור האמת. אם אתם עובדים על הפרויקט ב-Xcode, עליכם ליצור גרסה חדשה של פרויקט ה-Xcode שתואם לקובצי BUILD באמצעות טולסי בכל פעם שתעדכנו את BUILD. אם אינך משתמש ב-Xcode, הפקודות של bazel build ו-bazel test מספקות יכולות בדיקה ובדיקה עם מגבלות מסוימות המתוארות בהמשך מדריך זה.

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

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

  • ניתוחים סטטיים, חומרי חיטוי לכתובות וחומרי חיטוי לשרשורים עשויים שלא לפעול, מפני ש-Bazel לא מפיקה את הפלטים ש-Xcode מצפה להם עבור התכונות האלה.

  • אם אתה יוצר פרויקט Xcode עם Tulsi ומשתמש בפרויקט זה כדי להריץ בדיקות מתוך Xcode, Xcode תריץ את הבדיקות במקום ב-Bazel. כדי להריץ בדיקות עם Bazel, יש להריץ את הפקודה bazel test באופן ידני.

לפני שמתחילים

לפני שמתחילים, צריך לבצע את הפעולות הבאות:

1. מתקינים את Bazel אם עדיין לא עשיתם זאת.

2. אם אתם לא מכירים את Bazel ואת הרעיונות שלה, תוכלו להשלים את המדריך לאפליקציה ל-iOS. עליכם להבין את סביבת העבודה של Bazel, כולל הקבצים WORKSPACE ו-BUILD, וכן את המושגים של יעדים, כללי build וחבילות Bazel.

3. ניתוח והבנת יחסי התלות של הפרויקט.

ניתוח יחסי תלות של פרויקטים

בניגוד ל-Xcode, Bazel דורשת להצהיר במפורש על כל יחסי התלות בכל יעד בקובץ BUILD.

למידע נוסף על יחסי תלות חיצוניים, ראו עבודה עם יחסי תלות חיצוניים.

בנייה או בדיקה של פרויקט Xcode באמצעות Bazel

כדי לבנות או לבדוק פרויקט Xcode באמצעות Bazel, בצע את הפעולות הבאות:

1. יצירת הקובץ WORKSPACE

2. (ניסיוני) שילוב יחסי תלות של CocoaPods

3. יצירת קובץ BUILD:

   א. הוספת יעד האפליקציה

   ב. (אופציונלי) מוסיפים את יעדי הבדיקה

   ג. הוספת יעדי הספרייה

4. (אופציונלי) בודקים את ה-build בפירוט

5. הפעלה של ה-build

6. יצירת פרויקט Xcode באמצעות Tulsi

שלב 1: יצירת הקובץ WORKSPACE

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

שלב 2: (משולב) שילוב יחסי תלות של CocoaPods

כדי לשלב יחסי תלות של CocoaPods בסביבת העבודה של Bazel, צריך להמיר אותם לחבילות Bazel כפי שמתואר בהמרת יחסי תלות של CocoaPods.

שלב 3: יצירת קובץ BUILD

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

• שלב 3א: הוספת יעד האפליקציה
• שלב 3ב: (אופציונלי) מוסיפים את יעדי הבדיקה
• שלב 3ג: מוסיפים את יעדי הספרייה

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

שלב 3א: מוסיפים את יעד האפליקציה

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

• bundle_id - מזהה החבילה (הנתיב ה-DNS ההפוך ואחריו שם האפליקציה) של הקובץ הבינארי.

• provisioning_profile - ניהול תצורה של פרופיל מחשבון המפתח שלך ב-Apple (אם מוגדר עבור מכשיר iOS).

• families (iOS בלבד) - בין אם לבנות את היישום עבור iPhone, iPad, או שניהם.

• infoplists - רשימה של קובצי .plist שיש למזג אל קובץ ה-Info.plist הסופי.

• minimum_os_version - הגרסה המינימלית של macOS או iOS שנתמכת על ידי האפליקציה. פעולה זו מבטיחה ש-Bazel תבנה את האפליקציה ברמות ה-API הנכונות.

שלב 3ב: (אופציונלי) מוסיפים את יעדי הבדיקה

כללי ה-build של Apple של Bazel תומכים בהרצת בדיקות יחידות מבוססות-ספרייה ב-iOS ו-macOS, וכן בבדיקות מבוססות-אפליקציות ב-macOS. לבדיקות מבוססות-אפליקציה ב-iOS או בבדיקות ממשק משתמש בכל אחת מהפלטפורמות, Bazel תבנה את תוצאות הבדיקות, אך הבדיקות חייבות לרוץ בתוך Xcode דרך פרויקט שנוצר באמצעות Tulsi. הוסיפו יעדי בדיקה באופן הבא:

• macos_unit_test כדי להריץ בדיקות על בסיס ספרייה על בסיס אפליקציה או מבוססות ספרייה, ב-macOS.

• ios_unit_test כדי להפעיל בדיקות יחידה מבוססות-ספרייה ב-iOS. עבור בדיקות שמחייבות את הסימולטור של iOS, Bazel תבנה את תוצאות הבדיקה אך לא תפעיל את הבדיקות. עליך ליצור פרויקט Xcode באמצעות Tulsi ולהפעיל את הבדיקות מתוך Xcode.

• ios_ui_test כדי לפתח פלטים הנדרשים להפעלת בדיקות של ממשק משתמש בסימולטור ל-iOS באמצעות Xcode. עליך ליצור פרויקט Xcode עם Tulsi ולהפעיל את הבדיקות מתוך Xcode. Bazel לא יכול להריץ בדיקות ממשק משתמש באופן מקורי.

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

שלב 3ג: מוסיפים את יעדי הספרייה

יש להוסיף יעד של objc_library לכל ספריית יעד C, ויעד swift_library לכל ספריית Swift שבה האפליקציה ו/או האפליקציה הבדיקות תלויות.

מוסיפים את יעדי הספרייה באופן הבא:

• הוסיפו את היעדים של ספריית האפליקציה כתלות ביעדים של האפליקציה.

• הוסיפו את היעדים של ספריית הבדיקה כתלות ביעדים.

• יש לציין את מקורות ההטמעה במאפיין srcs

• יש לציין את הכותרות במאפיין hdrs.

למידע נוסף על כללי build, ראו כללי Apple עבור Bazel.

בשלב זה, כדאי לבדוק את גרסת ה-build:

bazel build //:<application_target>

שלב 4: (אופציונלי) פירוט ה-build

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

• הגברה מצטברת של ה-build,

• העלאה במקביל של משימות build,

• שיפור התחזוקה למשתמשים עתידיים,

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

טיפים לחידוד הפרויקט:

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

• כשמוסיפים BUILD קבצים ומציינים יעדים, מוסיפים את היעדים החדשים למאפייני deps של יעדים שתלויים בהם.

• הפונקציה glob() לא חוצה גבולות של חבילות, ולכן ככל שמספר החבילות גדל, כך שגודל הקבצים התואמים ל-glob() יתכווץ.

• כשמוסיפים קובץ BUILD לספרייה של main, צריך להוסיף גם קובץ BUILD לספרייה test המתאימה.

• אכיפה של תקינות חשיפה תקינה בין חבילות

• בנו את הפרויקט אחרי כל שינוי חשוב בקובצי BUILD ותקנו שגיאות build כשתמצאו אותן.

שלב 5: מריצים את ה-build

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

למשל:

bazel build //:my-target

שלב 6: יצירת פרויקט Xcode באמצעות Tulsi

כשבונים עם Bazel, הקבצים WORKSPACE ו-BUILD הופכים למקור האמת לגבי ה-build. כדי ליידע את זה באמצעות Xcode, עליך ליצור פרויקט Xcode תואם ל-Bazel באמצעות Tulsi.

פתרון בעיות

שגיאות Bazel עלולות להתעורר כאשר הוא לא מסונכרן עם גרסת Xcode שנבחרה, למשל לאחר החלת עדכון. יש כמה דברים שכדאי לנסות אם נתקלים בשגיאות ב-Xcode, למשל "יש לציין גרסת Xcode כדי להשתמש ב-Apple CROSSROOM".

• הפעל Xcode באופן ידני וקבל את כל התנאים וההגבלות.

• השתמשו ב-Xcode select כדי לציין את הגרסה הנכונה, לאשר את הרישיון ולנקה את המצב של Bazel.

  sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
  sudo xcodebuild -license
  bazel sync --configure

• אם זה לא עוזר, אפשר גם לנסות להפעיל את bazel clean --expunge.