BazelCon 2022 מגיע בין 16 ל-17 בנובמבר לניו יורק באינטרנט.
הירשמו עוד היום!

קובצי BUILD

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

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

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

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

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

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

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

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

באופן מכריע, תוכניות ב-Starlark לא יכולות לבצע I/O שרירותי. היא הופכת את הפרשנות המשמעותית הזוBUILD קבצים הרמטיים - תלויים רק במערך ידוע של רכיבי קלט, החיוניים לשימור של גרסאות 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, סמלים שמתחילים ב-_ לא מיוצאים ולא ניתן לטעון אותם מקובץ אחר. הרשאות הגישה לא משפיעות על הטעינה (עדיין): אין צורך להשתמש ב-exports_files כדי להגדיר קובץ .bzl כגלוי.

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

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

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

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

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

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

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

תוויות תלויות?