פרוטוקול Build (BEP) מאפשר לתוכניות של צדדים שלישיים לקבל תובנות לגבי הפעלה של Bazel. לדוגמה, תוכלו להשתמש ב-BEP כדי לאסוף מידע עבור פלאגין של IDE או מרכז בקרה שמציג תוצאות build.
הפרוטוקול הוא קבוצה של הודעות מאגר פרוטוקול שמכיל כמה סמנטיים מעליו. היא כוללת מידע על תוצאות build ובדיקה, התקדמות גרסת build, הגדרת ה-build ועוד הרבה יותר. מטרת ה-BEP היא לצרוך את התוכן באופן פרוגרמטי, כך שניתוח שורת הפקודות של Bazel משפיע בעבר.
פרוטוקול Build Build מייצג מידע על build בתור אירועים. אירוע build הוא הודעה במאגר נתונים זמני של פרוטוקול, שכוללת מזהה אירוע build, קבוצה של מזהים של צאצא ומטען ייעודי (payload).
בניית מזהה אירוע: בהתאם לסוג של אירוע ה-build, הוא יכול להיות מחרוזת אטומה או מידע מובנה שחושף יותר על אירוע ה-build. מזהה אירוע Build הוא ייחודי ב-build.
ילדים: אירוע build עשוי להודיע על אירועי build אחרים, על ידי הכללת מזהי האירועים שלהם ב-ילד/ה. לדוגמה, אירוע ה-build של
PatternExpandedמכריז על היעדים שהוא מתרחב אליהם כילדים. הפרוטוקול מבטיח שכל האירועים, חוץ מהאירוע הראשון, יוכרזו על ידי אירוע קודם.payload: המטען הייעודי מכיל מידע מובנה על אירוע build, שמקודד כהודעת מאגר נתונים זמני על פרוטוקול ספציפי לאותו אירוע. חשוב לדעת: המטען הייעודי (payload) לא יכול להיות הסוג הנדרש, אבל הוא יכול להיות הודעת
Abortedאם גרסת ה-build בוטלה מוקדם מדי.
יצירת תרשים של אירוע
כל אירועי ה-build יוצרים תרשים מחזורי מכוון דרך הקשר בין ההורה לילד. לכל אירוע build יש אירוע אחד או יותר, מלבד אירוע ה-build הראשוני. שימו לב: לא כל האירועים ההורה של אירוע צאצא חייבים להיות מתפרסמים לפניו. לאחר השלמת build (הצלחה או כישלון), כל האירועים שפורסמו יפורסמו. במקרה של קריסה ב-Bazel או העברה של רשתות נכשלים, יכול להיות שאירועי build מסוימים לא יפורסמו.
מבנה התרשים של האירוע משקף את מחזור החיים של פקודה. לכל תרשים BEP יש צורה אופיינית:
- האירוע הבסיסי הוא תמיד אירוע
BuildStarted. כל האירועים האחרים הם צאצאים שלה. - ילדים מיידית באירוע BuildStarted מכילים מטא נתונים על הפקודה.
- אירועים שמכילים נתונים שהופקו על ידי הפקודה, כמו קבצים שנבנו ובדיקת תוצאות, מופיעים לפני האירוע
BuildFinished. BuildFinishedהאירוע עשוי לעקוב אחר אירועים שמכילים מידע סיכום על ה-build (לדוגמה, מדד או נתוני יצירת פרופיל).
שימוש בפרוטוקול build של אירוע
צריכה בפורמט בינארי
כדי לצרוך את BEP בפורמט בינארי:
תכתבו ב-Bazel את סדרות האחסון הזמני של הקובץ בקובץ על ידי ציון האפשרות
--build_event_binary_file=/path/to/file. הקובץ יכלול הודעות מופרדות בפרוטוקול פרוטוקולים נפרדים, כאשר כל הודעה מופרדת לאורך. כל הודעה כוללת קידומת כשהאורך שלה מקודד כמספר שלם של משתנה. אפשר לקרוא את הפורמט הזה בשיטה של ספריית מאגר הנתונים הזמניparseDelimitedFrom(InputStream).לאחר מכן, כותבים תוכנה שמוציאה את המידע הרלוונטי מהודעת מאגר הנתונים הזמני של הפרוטוקול.
צריכה בפורמט טקסט או JSON
הסימונים הבאים בשורת הפקודה של Bazel יפלטו את ה-BEP בפורמטים שקריאים לאדם, כמו טקסט ו-JSON:
--build_event_text_file
--build_event_json_file
שירות יצירת אירועים
שירות build של אירועים
פרוטוקול הוא שירות gRPC כללי לפרסום אירועי build. פרוטוקול Build Event Service אינו תלוי ב-BEP ומתייחס לאירועי BEP כאטום.
Bazel מספקת שירות הטמעת לקוח gRPC של פרוטוקול Build Event Service שמפרסם אירועי Build Event Protocol. אפשר לציין את נקודת הקצה שאליה יישלחו האירועים באמצעות הדגל --bes_backend=HOST:PORT. אם הקצה העורפי משתמש ב-gRPC, צריך להוסיף את הכתובת בסכימה המתאימה: grpc:// עבור plaintext
gRPC ו-grpcs:// עבור gRPC כאשר TLS מופעל.
התרעות לגבי בניית שירותי אירועים
ל-Bazel יש כמה דגלים הקשורים לפרוטוקול של Service Event, כולל:
--bes_backend--[no]bes_best_effort--[no]bes_lifecycle_events--bes_results_url--bes_timeout--project_id
תיאור של כל אחד מהסימונים האלה זמין בחומר העזר בנושא שורת הפקודה.
אימות ואבטחה
ההטמעה של 'שירות יצירת אירועים' של Bazel תומכת גם באימות וב-TLS (אבטחת שכבת התעבורה). אפשר לשלוט בהגדרות האלה באמצעות התכונות המפורטות בהמשך. שימו לב שהסימונים האלה משמשים גם לביצוע מרחוק של בזל. המשמעות היא שנקודות השירות (endpoint) של שירותי build ונקודות הביצוע מרחוק צריכות לשתף את אותה תשתית אימות וTLS (אבטחת שכבת התעבורה).
--[no]google_default_credentials--google_credentials--google_auth_scopes--tls_certificate--[no]tls_enabled
תיאור של כל אחד מהסימונים האלה זמין בחומר העזר בנושא שורת הפקודה.
יצירת שירות אירועים ושמירה במטמון
BEP מכיל בדרך כלל הפניות רבות לקובצי יומן (test.log, test.xml וכו') המאוחסנים במחשב שבו פועל Bazel. שרת BES מרוחק בדרך כלל אינו יכול לגשת לקבצים אלה כפי שהם נמצאים במחשבים שונים. אפשר לפתור את הבעיה הזו על ידי שימוש ב-Bazel יחד עם שמירה במטמון מרחוק. Bazel תעלה את כל קובצי הפלט למטמון המרוחק (כולל קבצים שצוינו ב-BEP), ושרת BES יוכל לאחזר את הקבצים המוזכרים מהמטמון.
לפרטים נוספים, ניתן לעיין בבעיה של GitHub 3689.