שיטות מומלצות

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

היעדים הכוללים הם:

• כדי להשתמש בתלות עדינות כדי לאפשר מקבילות ומצטברות.
• כדי לשמור על תלות גבוהה בגופות.
• ליצור קוד מובנה וכדאי לבדיקה.
• כדי ליצור תצורת build שקל להבין ולתחזק.

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

הדף הזה משתמש ברמות הדרישות המתוארות ב-RFC הזה.

הפעלת גרסאות build ובדיקות

פרויקט צריך להיות מסוגל להפעיל את bazel build //... ואת bazel test //... בהצלחה בסניף היציב שלו. יש להוסיף יעדים נדרשים, אך הם אינם יוצרים בנסיבות מסוימות (למשל, דרישה לסימונים ספציפיים של ה-build, אי-בנייה בפלטפורמה מסוימת או דרישה להסכמי רישיון), יש לתייג אותם בצורה ספציפית ככל האפשר לדוגמה, "requires-osx"). התיוג הזה מאפשר לסנן יעדים ברמת פירוט גבוהה יותר מאשר התג "ידני", ומאפשר למישהו שבודק את הקובץ BUILD להבין מהן ההגבלות של היעד.

יחסי תלות של צד שלישי

אפשר להצהיר על יחסי תלות של צד שלישי:

• צריך להצהיר עליהם כמאגרים מרוחקים בקובץ WORKSPACE.
• לחלופין, אפשר להעביר אותם לספרייה בשם third_party/ בספרייה של סביבת העבודה.

בהתאם לבינאריים

במידת האפשר, יש לבנות את כל המידע מהמקור. באופן כללי, המשמעות היא שבמקום ליצור ספרייה בשם some-library.so, יש ליצור קובץ BUILD ולבנות את some-library.so מהמקורות שלו, ולאחר מכן תלוי ביעד הזה הנתונים.

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

ניהול גרסאות

עדיף לבנות את כל הקוד מראש, אם אפשר. כשחובה להשתמש בגרסאות, יש להימנע מהוספת הגרסה בשם היעד (לדוגמה, //guava, לא //guava-20.0). השם הזה מאפשר לעדכן את הספרייה בקלות (צריך לעדכן רק יעד אחד). היא גם עמידה יותר בבעיות של תלות יהלום: אם ספרייה אחת תלויה ב-guava-19.0 וספרייה אחת תלויה ב-guava-20.0, ייתכן שבסופו של דבר תהיה לכם ספרייה שתנסה להיות תלויה בשתי גרסאות שונות. אם יצרת כינוי מטעה כך שיפנה את שני היעדים לספרייה אחת של guava, אז קובצי BUILD יהיו מטעים.

שימוש בקובץ .bazelrc

אם מדובר באפשרויות ספציפיות לפרויקט, יש להשתמש בקובץ התצורה workspace/.bazelrc (ניתן לעיין בפורמט bezelrc).

אם אתם רוצים לתמוך בפרויקט באפשרויות לכל משתמש שלא רוצים לבדוק במסגרת בקרת המקור, אפשר לכלול את השורה:

try-import %workspace%/user.bazelrc

(או כל שם קובץ אחר) בworkspace/.bazelrc ומוסיפים את user.bazelrc למכשיר .gitignore.

חבילות

כל ספרייה שמכילה קבצים הניתנים לבנייה צריכה להיות חבילה. אם קובץ BUILD מתייחס לקבצים בספריות משנה (כגון srcs = ["a/b/C.java"]), זה סימן לכך שיש להוסיף קובץ BUILD לספריית המשנה. ככל שהמבנה הזה קיים לאורך זמן רב יותר, כך תיתכן סבירות גבוהה יותר על סמך תלות מעגלית, היקף ההשתמטות של היעד יתגבר, ומספר הולך וגדל של יחסי תלות לאחור יצטרך להתעדכן.