כתיבת קובצי תצורה של bazelrc

Bazel מקבלת אפשרויות רבות. חלק מהאפשרויות מגוונות בתדירות גבוהה (לדוגמה, --subcommands) ואחרות נשארות ללא שינוי בכמה גרסאות (כמו --package_path). כדי לא לציין את האפשרויות האלה ללא שינוי בכל build (ופקודות אחרות), ניתן לציין אפשרויות בקובץ תצורה בשם .bazelrc.

היכן נמצאים קובצי .bazelrc?

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

1. קובץ RC של המערכת, אלא אם --nosystem_rc קיים.

   נתיב:

   • ב-Linux/macOS/Unixes: /etc/bazel.bazelrc
   • ב-Windows: %ProgramData%\bazel.bazelrc

   אם הקובץ לא קיים, זו לא שגיאה.

   אם נדרש מיקום אחר שצוין על ידי המערכת, יש לבנות קובץ בינארי של התאמה אישית ב-Bazel, וכך לבטל את הערך BAZEL_SYSTEM_BAZELRC_PATH ב-//src/main/cpp:option_processor. המיקום שצוין על ידי המערכת עשוי לכלול הפניות למשתנים מהסביבה, כמו ${VAR_NAME} ב-Unix או %VAR_NAME% ב-Windows.

2. קובץ סביבת עבודה RC, אלא אם --noworkspace_rc נמצא.

   נתיב: .bazelrc בספרייה של סביבת העבודה (לצד הקובץ הראשי WORKSPACE).

   אם הקובץ לא קיים, זו לא שגיאה.

3. קובץ RC בבית, אלא אם --nohome_rc נמצא.

   נתיב:

   • ב-Linux/macOS/Unixes: $HOME/.bazelrc
   • ב-Windows: %USERPROFILE%\.bazelrc אם קיים, או %HOME%/.bazelrc

   אם הקובץ לא קיים, זו לא שגיאה.

4. קובץ RC שצוין על ידי המשתמש, אם צוין --bazelrc=file

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

   /dev/null מציין שהמערכת תתעלם מכל --bazelrc הערכים הנוספים, וכתוצאה מכך משביתים את החיפוש של קובץ rc של משתמש, כמו גרסאות build של גרסה.

   למשל:

   --bazelrc=x.rc --bazelrc=y.rc --bazelrc=/dev/null --bazelrc=z.rc
   

   • קראת את x.rc ואת y.rc.
   • יש התעלמות מ-z.rc בגלל ה/dev/null הקודם.

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

תחביר וסמנטיקה ב.bazelrc

כמו כל קובצי ה-"rc" של UNIX, הקובץ .bazelrc הוא קובץ טקסט עם דקדוק מבוסס קו. המערכת מתעלמת משורות ומקווים ריקים החל מ-# (תגובות). כל שורה מכילה רצף של מילים, אשר מסומנות בהתאם לאותם כללים כמו המעטפת של בורן.

יבוא

שורות המתחילות ב-import או ב-try-import הן מיוחדות: השתמש בהן כדי לטעון קובצי "rc" אחרים. כדי לציין נתיב יחסי לבסיס של סביבת העבודה, כתוב import %workspace%/path/to/bazelrc.

ההבדל בין import לבין try-import הוא ש-Bazel נכשלת אם הקובץ import'd חסר (או שלא ניתן לקרוא אותו), אך לא כך לגבי try-import.

ייבוא ייבוא:

• האפשרויות בקובץ המיובא מקבלות עדיפות על פני אפשרויות שצוינו לפני הצהרת הייבוא.
• האפשרויות שצוינו לאחר הצהרת הייבוא מקבלות עדיפות על האפשרויות בקובץ המיובא.
• אפשרויות בקבצים שיובאו מאוחר יותר מקבלות עדיפות על פני קבצים שיובאו מוקדם יותר.

ברירות מחדל של אפשרויות

רוב השורות ב-bazelrc מגדירות ערכי ברירת מחדל של אפשרויות. המילה הראשונה בכל שורה מציינת מתי ערכי ברירת המחדל האלה יחולו:

• startup: אפשרויות הפעלה, שמופיעות לפני הפקודה ומתוארות בbazel help startup_options.
• common: אפשרויות החלות על כל פקודות Bazel.
• command: פקודת Bazel, כגון build או query שהאפשרויות חלות עליהן. אפשרויות אלו חלות גם על כל הפקודות היורשות מהפקודה שצוינה. (לדוגמה, test יורש מ-build).

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

build --test_tmpdir=/tmp/foo --verbose_failures
build --test_tmpdir=/tmp/bar

משולבים כ:

build --test_tmpdir=/tmp/foo --verbose_failures --test_tmpdir=/tmp/bar

כך שהסימונים היעילים הם --verbose_failures ו---test_tmpdir=/tmp/bar.

קדימות של אפשרויות:

• האפשרויות בשורת הפקודה מקבלות תמיד עדיפות על פני האפשרויות שבקובצי rc. לדוגמה, אם בקובץ rc מופיע build -c opt אבל הסימון בשורת הפקודה הוא -c dbg, הסימון בשורת הפקודה מקבל עדיפות.

• בקובץ ה-rc, העדיפות נקבעת לפי ספציפיות: שורות עבור פקודה ספציפית יותר מקבלות עדיפות על פני שורות עבור פקודה ספציפית פחות.

  ספציפיות מוגדרת באמצעות ירושה. פקודות מסוימות יורשות אפשרויות מפקודות אחרות, והופכות את פקודת הירושה לספציפית יותר מפקודת הבסיס. לדוגמה, test יורשת מהפקודה build, כך שכל bazel build הסימונים חוקיים עבור bazel test, וכל build השורות חלים גם על bazel test אלא אם יש שורה אחת (test) עבור אותה אפשרות. אם קובץ ה-rc מציין:

  test -c dbg --test_env=PATH
  build -c opt --verbose_failures
  

  לאחר מכן, bazel build //foo תשתמש ב-c opt --verbose_failures, וbazel test //foo ישתמש ב--verbose_failures -c dbg --test_env=PATH.

  תרשים הירושה (ספציפיות) הוא:

  • כל פקודה עוברת בירושה מהפונקציה common
  • הפקודות הבאות עוברות בירושה מ (והן ספציפיות יותר מ) build: test, run, clean, mobile-install, info, print_action, config, cquery, ו-aquery
  • coverage עוברת בירושה מ-test

• שתי שורות המציינות אפשרויות עבור אותה פקודה בפרט ספציפי מנתחות לפי הסדר שבו הן מופיעות בתוך הקובץ.

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

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

--config

בנוסף להגדרות ברירת המחדל של האפשרויות, ניתן להשתמש בקובץ ה-rc כדי לקבץ אפשרויות ולספק קיצור עבור קבוצות נפוצות. צריך לעשות זאת על ידי הוספת :name סיומת לפקודה. המערכת מתעלמת מאפשרויות אלה כברירת מחדל, אך היא תיכלל אם קיימת האפשרות --config=name, בשורת הפקודה או בקובץ .bazelrc, באופן חוזר, גם בתוך קובץ אחר הגדרות אישיות. האפשרויות שצוינו על ידי command:name יורחבו רק לפקודות רלוונטיות, בסדר העדיפות שתואר למעלה.

הערה: ניתן להגדיר תצורות בכל קובץ .bazelrc, ושכל השורות בצורה של command:name (לפקודות הרלוונטיות) יורחבו, בקובצי ה-rc השונים. כדי למנוע התנגשויות בין שמות, מומלץ להגדיר תצורות שמוגדרות בקובצי rc אישיים בקו תחתון (_) כדי להימנע משיתוף שם לא מכוון.

--config=foo מתרחב לאפשרויות שמוגדרות בקובצי ה-rc "במקום" כך שלאפשרויות שצוינו עבור התצורה יש עדיפות זהה לאפשרות --config=foo יש לו.

התחביר הזה לא כולל את השימוש ב-startup להגדרת אפשרויות הפעלה. המערכת תתעלם מהגדרה של startup:config-name --some_startup_option ב- .bazelrc.

דוגמה

הנה קובץ ~/.bazelrc לדוגמה:

# Bob's Bazel option defaults

startup --host_jvm_args=-XX:-UseParallelGC
import /home/bobs_project/bazelrc
build --show_timestamps --keep_going --jobs 600
build --color=yes
query --keep_going

# Definition of --config=memcheck
build:memcheck --strip=never --test_timeout=3600

קבצים אחרים העוסקים בהתנהגות של בזל

.bazelignore

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

קובץ ה-Bazelrc הגלובלי

Bazel קוראת קובצי Bazelrc אופציונליים בסדר הזה: - קובץ rc מערכת הממוקם בetc/bazel.bazelrc. - קובץ rc Workspace זמין בכתובת $workspace/tools/bazel.rc. - קובץ rc-home מותאם ל-$HOME/.bazelrc

לכל קובץ bazelrc שרשום כאן יש סימון תואם שיכול לשמש כדי להשבית אותם (למשל --nosystem_rc, --noworkspace_rc, --nohome_rc). ניתן גם לגרום ל-Bazel להתעלם מכל מכשירי bazelrcs על ידי העברת אפשרות ההפעלה של --ignore_all_rc_files.