תוויות

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

@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 לבין שמות חבילה. תוויות תמיד מתחילות במזהה מאגר (בדרך כלל קיצור של //), אך שמות חבילות אף פעם לא מתבצעים. לכן, my/app היא החבילה שמכילה //my/app/lib (אפשר גם לכתוב אותה כ-//my/app/lib:lib).

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

לא ניתן להשתמש בתוויות יחסיות כדי להפנות ליעדים בחבילות אחרות. במקרה כזה, תמיד יש לציין את מזהה הנכס ושם החבילה. לדוגמה, אם עץ המקור מכיל גם את החבילה 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 במאגר החיצוני. הדבר רלוונטי במיוחד כשכותבים כללים במאגר הראשי המטרגטים ליעדים במאגר הראשי. הם ישמשו במאגרים חיצוניים.

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

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

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

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

שמות היעד – package-name:target-name

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

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

שמות קבצים חייבים להיות שמות נתיבים יחסיים בפורמט רגיל, כלומר הם לא יכולים להתחיל או להסתיים בקו נטוי (לדוגמה, /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, az, 09, '/', '-','.'@' ו-'_' ולא יכולים להתחיל בקו נטוי.

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

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

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

כללים

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

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

בדוגמה הבאה, אנחנו רואים את הצהרת היעד my_app באמצעות הכלל cc_binary.

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

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

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

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

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

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

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

יעדים קובצי BUILD