קובצי BUILD

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

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

הם מוצגים כרשימה רציפה של הצהרות.

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

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

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

כדי לאפשר הפרדה נקייה בין קוד לנתונים, קובצי BUILD לא יכולים להכיל הגדרות של פונקציות, for הצהרות או if הצהרות (אבל מותר להשתמש בהסברים ובניסוחים מהרשימה if). במקום זאת, אפשר להצהיר על פונקציות ב-.bzl קבצים. בנוסף, לא ניתן להשתמש בארגומנטים *args ו-**kwargs ב-BUILD קבצים, צריך לפרט את כל הארגומנטים במפורש.

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

יש לכתוב BUILD קבצים רק באמצעות תווי ASCII. עם זאת, מבחינה טכנית, הם מפורשים באמצעות קבוצת התווים Latin-1.

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

מתבצעת טעינה של תוסף

תוספי Bazel הם קבצים שמסתיימים ב-.bzl. השתמשו בהצהרה load כדי לייבא סמל מתוסף.

load("//foo/bar:file.bzl", "some_library")

הקוד הזה טוען את הקובץ foo/bar/file.bzl ומוסיף את הסמל some_library לסביבה. אפשר להשתמש בו כדי לטעון כללים, פונקציות או קבועים חדשים (לדוגמה, מחרוזת או רשימה). אפשר לייבא כמה סמלים באמצעות ארגומנטים נוספים לקריאה ל-load. הארגומנטים חייבים להיות ליטרים של מחרוזת (ללא משתנה) והצהרות load חייבות להופיע ברמה העליונה — הן לא יכולות להיות בגוף פונקציה.

הארגומנט הראשון של load הוא תווית שמזהה קובץ .bzl. אם מדובר בתווית יחסית, היא נפתרה ביחס לחבילה (לא לספרייה) שמכילה את קובץ bzl הנוכחי. תוויות יחסיות בהצהרות של load צריכות להשתמש ב-: מוביל.

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

load("//foo/bar:file.bzl", library_alias = "some_library")

ניתן להגדיר כמה כינויים בהצהרה אחת (load). בנוסף, רשימת הארגומנטים יכולה להכיל גם כינויים וגם שמות סמלים רגילים. הדוגמה הבאה חוקית לחלוטין (חשוב לשים לב מתי להשתמש במירכאות).

load(":my_rules.bzl", "some_rule", nice_alias = "some_other_rule")

בקובץ .bzl, לא ניתן לייצא סמלים שמתחילים ב-_ ולא ניתן לטעון אותם מקובץ אחר.

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

סוגים של כללי build

רוב כללי ה-build מקובצים יחד לפי משפחות, לפי שפה. לדוגמה, cc_binary, cc_library ו-cc_test הם כללי Build לבינאריים, ספריות ובדיקות C+, בהתאמה. לכל שפה יש שם שונה, עם קידומת שונה, כמו java_* ל-Java. חלק מהפונקציות האלה מתועדות ב-Enciclopedia, אבל כל אחד יכול ליצור כללים חדשים.

• *_binary כללים בונים תוכניות הפעלה בשפה נתונה. אחרי הבנייה, קובץ ההפעלה יופיע בכלי לבניית נתונים בינאריים של הכלי המתאים, בשם המתאים לתווית של כלל, כך ש-//my:program יופיע (למשל) $(BINDIR)/my/program.

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

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

  כמו קבצים בינאריים, גם בבדיקות יש עצי ריצה, והקבצים שמתחתיו הם הקבצים היחידים שהבדיקה עשויה להיפתח בצורה חוקית בזמן ריצה. לדוגמה, תוכנית cc_test(name='x', data=['//foo:bar']) עשויה לפתוח ולקרוא את $TEST_SRCDIR/workspace/foo/bar במהלך הביצוע. (לכל שפת תכנות יש פונקציית שירות משלה לגישה לערך של $TEST_SRCDIR, אבל כולם מקבילים לשימוש במשתנה הסביבה באופן ישיר). אי-ציות לכלל עלול לגרום לכשל בבדיקה כאשר הוא מופעל במארח בדיקה מרחוק.

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

תוויות

יחסי תלות