תוויות

כל היעדים שייכים לחבילה אחת בלבד. שם של יעד נקרא תווית. כל תווית מזהה יעד באופן ייחודי. תווית אופיינית בפורמט קנוני נראית כך:

@myrepo//my/app/main:app_binary

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

//my/app/main:app_binary

החלק השני של התווית הוא שם החבילה הלא כשיר my/app/main, הנתיב לחבילה ביחס לשורש המאגר. ביחד, שם המאגר ושם החבילה הלא תואמים יוצרים את שם החבילה המלא.@myrepo//my/app/main כאשר התווית מתייחסת לאותה חבילה שבה משתמשים בה, ייתכן שלא יופיע שם החבילה (ואופציונלי גם בנקודתיים). לכן, בתוך @myrepo//my/app/main, התווית הזו יכולה להיות נכתבת באחת מהדרכים הבאות:

app_binary
:app_binary

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

החלק של התווית אחרי נקודתיים, app_binary הוא שם היעד לא כשיר. כאשר היא תואמת לרכיב האחרון של נתיב החבילה, ייתכן שהיא תושמט. כלומר, שתי התוויות האלה מקבילות:

//my/app/lib
//my/app/lib:lib

השם של יעד קובץ בספריית משנה של החבילה הוא הנתיב לקובץ ביחס לשורש החבילה (הספרייה שמכילה את הקובץ BUILD). לכן, הקובץ הזה נמצא בספריית המשנה של המאגר my/app/main/testdata:

//my/app/main:testdata/input.txt

למחרוזות כמו //my/app ו-@some_repo//my/app יש שתי משמעות בהתאם להקשר שבו הן משמשות: כאשר Bazel מצפה לתווית, פירוש הדבר //my/app:app ו-@some_repo//my/app:app, בהתאמה. אבל בבזל מכילה חבילה שמצוינת בחבילה (למשל, במפרט של package_group), היא מתייחסת לחבילה שמכילה את התווית.

טעות נפוצה בקובצי BUILD היא שימוש ב-//my/app להתייחסות לחבילה, או לכל היעדים בחבילה – לא. חשוב לזכור, שזה שווה ערך ל-//my/app:app, כך שהשם שלו הוא היעד app בחבילה של my/app של המאגר הנוכחי.

עם זאת, מומלץ להשתמש ב-//my/app כהתייחסות לחבילה במפרט של package_group או ב-.bzl קבצים, כי חשוב מאוד ששם החבילה יהיה מוחלט ושורשיו בספרייה ברמה העליונה של סביבת העבודה.

לא ניתן להשתמש בתוויות יחסיות כדי לטרגט ליעדים בחבילות אחרות. במקרה כזה, תמיד צריך לציין את מזהה המאגר ואת שם החבילה. לדוגמה, אם בעץ המקור יש גם את החבילה my/app וגם את החבילה my/app/testdata (לכל אחת משתי הספריות האלה יש קובץ BUILD), החבילה השנייה מכילה קובץ בשם testdepot.zip. הנה שתי דרכים (אחת שגויה, אחת נכונה) להתייחס לקובץ הזה בתוך //my/app:BUILD:

שגוי — testdata היא חבילה אחרת, לכן לא ניתן להשתמש בנתיב יחסי.

testdata/testdepot.zip

נכון — יש לעבור לכתובת testdata עם הנתיב המלא שלה

//my/app/testdata:testdepot.zip

תוויות שמתחילות ב-@// הן הפניות למאגר הראשי, שעדיין יפעלו גם ממאגרים חיצוניים. לכן, שונה מ-@//a/b/c ל-//a/b/c כשמתבצעת הפניה ממאגר חיצוני. הפריט הראשון מתייחס למאגר הראשי, והשני מחפש את //a/b/c במאגר החיצוני. זה רלוונטי במיוחד כשכותבים כללים במאגר הראשי שקשורים ליעדים במאגר הראשי, וייעשה בהם שימוש ממאגרים חיצוניים.

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

מפרט מילוני של תווית

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

בהמשך מוצגים הפרטים המדויקים של שמות היעדים המורשים.

שמות יעדים — package-name:target-name

target-name הוא שם היעד בחבילה. השם של הכלל הוא הערך של המאפיין name בהצהרת כלל של קובץ BUILD. שם הקובץ הוא שם הנתיב שלו ביחס לספרייה שמכילה את הקובץ BUILD.

שמות של מיקוד חייבים להיות מורכבים מתווים שנקבעו על ידי a-z, A-Z, 0-9 וסימני הפיסוק !%-@^_"#$&'()*-+,;<=>?[]{|}~/..

שמות הקבצים חייבים להיות שמות יחסיים באופן רגיל, כלומר הם לא יכולים להתחיל או להסתיים בקו נטוי (לדוגמה, /foo ו-foo/ אסורים) ואינם יכולים לכלול מספר קווים נטויים עוקבים כמפרידי נתיבים (לדוגמה, foo//bar). באופן דומה, אין להשתמש בהפניות ברמה עליונה (..) ובהפניות בספרייה הנוכחית (./).

שגוי – אין להשתמש ב-'..' כדי להפנות לקבצים בחבילות אחרות.

נכון — צריך להשתמש ב-'//package-name:filename'

אמנם נהוג להשתמש ב-/ בשם של יעד קובץ, אבל מומלץ לא להשתמש ב-/ בשמות של כללים. במיוחד כשמשתמשים בתווית הקצרה של התווית, זה עלול לבלבל את הקורא. התווית //foo/bar/wiz היא תמיד קיצור הדרך ל-//foo/bar/wiz:wiz, גם אם אין חבילה כזו foo/bar/wiz; היא אף פעם לא מתייחסת ל-//foo:bar/wiz, גם אם היעד הזה קיים.

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

שמות חבילות — //package-name:target-name

שם החבילה הוא שם הספרייה שמכילה את קובץ BUILD שלה, ביחס לספרייה ברמה העליונה של המאגר המכיל. לדוגמה: my/app.

שמות החבילה חייבים להיות מורכבים מתווים שנלקחו מהקבוצה A-Z, a–z, 0–9, '/', '-', '.', '@' ו-'_' וכן לא יכולים להתחיל.

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

על אף ש-Bazel תומך ביעדים בחבילה הבסיסית של סביבת העבודה (לדוגמה: //:foo), מומלץ להשאיר את החבילה הזו ריקה כך שלכל החבילות החשובות יש שמות תיאוריים.

שמות של חבילות לא יכולים להכיל את מחרוזת המשנה // ולא להסתיים בקו נטוי.

כללים

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

BUILD קבצים מצהירים על יעדים באמצעות הפעלת כללים.

בדוגמה שבהמשך מוצגת ההצהרה על היעד my_app באמצעות הכלל cc_binary.

cc_binary(
    name = "my_app",
    srcs = ["my_app.cc"],
    deps = [
        "//absl/base",
        "//absl/strings",
    ],
)

לכל הפעלה של כלל יש מאפיין name (שחייב להיות שם יעד חוקי), שמצהיר על יעד בחבילה של הקובץ BUILD.

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

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

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

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

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

יעדים

קובצי BUILD