כללי מאגר

כאן מוסבר איך יוצרים כללי מאגר ומפורטות דוגמאות לפרטים נוספים.

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

יצירת כלל מאגר

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

ניתן להשתמש בכלל של מאגר מותאם אישית בדיוק כמו כלל של מאגר מקורי. יש לו מאפיין name חובה וכל יעד שנמצא בקובצי ה-build שלו יכול להיספר כ-@<name>//package:target, כאשר <name> הוא הערך של המאפיין name.

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

מאפיינים

מאפיין הוא ארגומנט של כלל, כגון url או sha256. כשמגדירים את הכלל של מאגר, צריך לפרט את המאפיינים ואת הסוגים שלהם.

local_repository = repository_rule(
    implementation=_impl,
    local=True,
    attrs={"path": attr.string(mandatory=True)})

יש להשתמש ב-repository_ctx.attr.<attribute_name> כדי לגשת למאפיין מסוים.

לכל repository_rule יש מאפיינים שמוגדרים באופן לא מפורש (בדיוק כמו בכללי build). שני המאפיינים המשתמעים הם name (בדיוק כמו בכללי build) ו-repo_mapping. אפשר לגשת לשם של כלל מאגר עם repository_ctx.name. המשמעות של repo_mapping זהה לזו של כללי המאגר המקוריים local_repository ושל new_local_repository.

אם שם מאפיין מתחיל ב-_ הוא פרטי והמשתמשים לא יכולים להגדיר אותו.

פונקציית הטמעה

לכל כלל מאגר נדרש פונקציה implementation. הוא כולל את הלוגיקה בפועל של הכלל, והוא מופעל אך ורק בשלב הטעינה.

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

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

def _impl(repository_ctx):
  repository_ctx.symlink(repository_ctx.attr.path, "")

local_repository = repository_rule(
    implementation=_impl,
    ...)

מתי פונקציית ההטמעה מופעלת?

אם המאגר מוגדר כ-local, שינוי תלות בתרשים התלויות (כולל קובץ ה-WORKSPACE עצמו) יגרום להפעלת פונקציית ההטמעה.

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

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

• נדרשים .bzl קבצים כדי להגדיר את כלל המאגר.
• הצהרה על כלל המאגר בקובץ WORKSPACE.
• הערך של כל משתנה סביבה שהוצהר באמצעות המאפיין environ של הפונקציה repository_rule. אפשר לאכוף את הערך של משתנה הסביבה הזה בשורת הפקודה באמצעות הדגל --action_env (אבל הדגל הזה יגרום לביטול כל פעולה ב-build).
• תוכן של כל קובץ שנעשה בו שימוש בתווית ומוזכרים בו (לדוגמה, //mypkg:label.txt לא mypkg/label.txt).

אילוץ אחזור מחדש של מאגרים חיצוניים

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

בנוסף, חלק מהכללים בודקים את המכונה המקומית ועשויים להיות מיושנים אם המכונה המקומית שודרגה. כאן אפשר לבקש מה-Bazal לשלוף מחדש את המאגרים החיצוניים האלה, שבהם ההגדרה repository_rule מוגדרת עם המאפיין configure, באמצעות bazel sync --configure.

דוגמאות

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

• מאגרי Go משתמשים במספר repository_rule כדי להגדיר את רשימת יחסי התלות הנדרשים כדי להשתמש בכללי Go.

• rules_jvm_external יוצרת מאגר חיצוני בשם @maven כברירת מחדל, שיוצר יעדי build לכל פריט מידע שנוצר בתהליך פיתוח (Attribution) בעץ העץ של Maven.