BazelCon 2022 מגיע בין 16 ל-17 בנובמבר לניו יורק באינטרנט.
הירשמו עוד היום!

כללי פריסה

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

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

כללי אירוח ושם

כללים חדשים צריכים לעבור למאגר GitHub משלהם בארגון. אם לדעתך הכללים שלך שייכים לארגון bazelbuild, צור קשר עם רשימת הדיוור של bazel-dev.

שמות מאגרים לכללי בזל סטנדרטיים בפורמט הבא: $ORGANIZATION/rules_$NAME. ניתן לעיין בדוגמאות ב-GitHub. כדי לשמור על עקביות, יש לפרסם את אותו פורמט כשמפרסמים את הכללים של Bazel.

חשוב להשתמש בתיאור תיאורי במאגר GitHub ובכותרת README.md, לדוגמה:

  • שם המאגר: bazelbuild/rules_go
  • תיאור המאגר: כללי הכללים של Bazel
  • תגי מאגר: golang, bazel
  • כותרת אחת של README.md: כללי כללים ל-Bazel (יש לשים לב לקישור אל https://bazel.build כדי לכוון את המשתמשים שלא מכירים בזל למקום הנכון)

אפשר לקבץ כללים לפי שפה (כמו Scala) או לפי פלטפורמה (כמו Android).

תוכן המאגר

כל מאגר כללים צריך להיות בעל פריסה מסוימת כדי שמשתמשים יוכלו להבין במהירות כללים חדשים.

לדוגמה, כשכותבים כללים חדשים לשפה (אמינה) mockascript, מאגר הכללים יהיה במבנה הבא:

/
  LICENSE
  README
  WORKSPACE
  mockascript/
    constraints/
      BUILD
    runfiles/
      BUILD
      runfiles.mocs
    BUILD
    defs.bzl
  tests/
    BUILD
    some_test.sh
    another_test.py
  examples/
    BUILD
    bin.mocs
    lib.mocs
    test.mocs

סביבת עבודה

הפרויקטWORKSPACE, עליך להגדיר את השם שבו משתמשים כדי להתייחס לכללים שלך. אם הכללים שלכם שייכיםBazelbuild לארגון שלך, עליך להשתמשrules_<lang> (כמוrules_mockascript ). אחרת, יש לתת שם למאגר<org>_rules_<lang> (כמוbuild_stack_rules_proto ). יש לפנות רשימת דיוור של bazel-dev אם לדעתך הכללים צריכים לפעול בהתאם למוסכמות של הכלליםBazelbuild הארגון.

בקטעים הבאים, נניח שהמאגר שייך לארגון bazelbuild.

workspace(name = "rules_mockascript")

קובץ README

ברמה העליונה, צריך להיות README מכיל (לפחות) מה שמשתמשים יצטרכו להעתיק ולהדביק לקובץ ה-WORKSPACE שלהם כדי להשתמש בכלל. באופן כללי, זו תהיה http_archive שמצביעה על מהדורת GitHub שלך, ושיחת מאקרו על הורדה/הגדרה של כלים הדרושים לכלל. לדוגמה, עבור כללי Go, זה נראה כך:

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_go",
    urls = ["https://github.com/bazelbuild/rules_go/releases/download/0.18.5/rules_go-0.18.5.tar.gz"],
    sha256 = "a82a352bffae6bee4e95f68a8d80a70e87f42c4741e6a448bec11998fcc82329",
)
load("@rules_go//go:deps.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()

אם הכללים שלך תלויים בכללים של מאגר אחר, יש לציין זאת בתיעוד הכללים (לדוגמה, יש לעיין בכללי Skydoc, התלויים בכללי Sass), ולספק מאקרו WORKSPACE שיוריד את כל התלות (ראה rules_go למעלה).

כללים

לעתים קרובות יש מספר כללים המסופקים על ידי המאגר שלך. יוצרים ספרייה בשם השפה ומציינים נקודת כניסה – קובץ defs.bzl מייצא את כל הכללים (כוללים גם קובץ BUILD, כך שהספרייה היא חבילה). בrules_mockascript, יהיו ספרייה בשם mockascript, וקובץ BUILD וקובץ defs.bzl בפנים:

/
  mockascript/
    BUILD
    defs.bzl

מגבלות

אם הכלל שלכם מגדיר ארגז כלים כללים, ייתכן שיהיה עליכם להגדירconstraint_setting s ו/או constraint_value. יש להכניס אותם לחבילה של //<LANG>/constraints. מבנה הספרייה שלכם ייראה כך:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

מומלץ לקרוא את המאמר github.com/bazelbuild/platforms כדי לעיין בשיטות המומלצות וכדי לראות אילו אילו אילו מגבלות כבר קיימות, ולשקול להוסיף את האילוצים שלך שם אם הם לא תלויים בשפה זו. כדאי להקפיד על אילוצים מותאמים אישית. כל המשתמשים בכללים ישתמשו בהם כדי להפעיל לוגיקה ספציפית לפלטפורמה בקובצי BUILD (לדוגמה, באמצעות בחירה). עם אילוצים מותאמים אישית, אתה מגדיר שפה שבה תדבר כל הסביבה העסקית של בזל.

ספריית RunFiles

אם הכלל שלכם מספק ספרייה רגילה לגישה אל קובצי cookie, היא צריכה להיות בפורמט של יעד ספרייה הממוקם בכתובת //<LANG>/runfiles (קיצור של //<LANG>/runfiles:runfiles). משתמשי היעד שרוצים לגשת ליחסי התלות של הנתונים שלהם בדרך כלל מוסיפים את היעד הזה למאפיין deps.

כללי המאגר

תלויות

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

יוצרים קובץ בשם <LANG>/repositories.bzl ומספקים מאקרו של נקודת כניסה אחת בשם rules_<LANG>_dependencies. הספרייה שלנו תיראה כך:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl
    repositories.bzl

רישום שרשראות כלים

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

לכן, צריך להוסיף מאקרו WORKSPACE בשם rules_<LANG>_toolchains לקובץ <LANG>/repositories.bzl.

הערה: כדי לפתור 'כלים' בשלב הניתוח, Bazel צריכה לנתח את כל toolchain היעדים הרשומים. Bazel לא צריך לנתח את כל היעדים עם מאפיין toolchain.toolchain. אם כדי לרשום כלים, צריך לבצע חישוב מורכב במאגר, מומלץ לפצל את המאגר ל-toolchain יעדים מהמאגר עם <LANG>_toolchain יעדים. המערכת תאחזר תמיד את הפריט הקודם, והמשתמש יאחזר רק כאשר המשתמש יצטרך לבנות את קוד <LANG>.

קטע טקסט של גרסה

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

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
http_archive(
    name = "rules_<LANG>",
    urls = ["<url_to_the_release.zip"],
    sha256 = "4242424242",
)
load("@rules_<LANG>//<LANG>:repositories.bzl", "rules_<LANG>_dependencies", "rules_<LANG>_toolchains")
rules_<LANG>_dependencies()
rules_<LANG>_toolchains()

בדיקות

יש לבצע בדיקות כדי לוודא שהכללים פועלים כצפוי. המיקום יכול להיות מיקום רגיל לשפה של הכללים או ספרייה tests/ ברמה העליונה.

דוגמאות (אופציונלי)

מומלץ להשתמש בספרייה של examples/ שמראה למשתמשים כמה דרכים בסיסיות שבהן אפשר להשתמש בכללים.

בדיקה

מגדירים את טראוויס כמתואר במסמכים לתחילת העבודה. לאחר מכן, יש להוסיף קובץ .travis.yml למאגר שלך עם התוכן הבא:

dist: xenial  # Ubuntu 16.04

# On trusty (or later) images, the Bazel apt repository can be used.
addons:
  apt:
    sources:
    - sourceline: 'deb [arch=amd64] http://storage.googleapis.com/bazel-apt stable jdk1.8'
      key_url: 'https://bazel.build/bazel-release.pub.gpg'
    packages:
    - bazel

script:
  - bazel build //...
  - bazel test //...

אם המאגר שלכם נכלל בארגון bazelbuild, תוכלו לבקש להוסיף אותו ל-ci.bazel.build.

מסמכי תיעוד

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

שאלות נפוצות

למה אנחנו לא יכולים להוסיף את הכלל שלנו למאגר הראשי של Bazel GitHub?

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

החיסרון הוא תהליך התקנה חד-פעמי מורכב יותר למשתמשים: עליהם להעתיק ולהדביק כלל לקובץ ה-WORKSPACE שלהם, כפי שמתואר בקטע README.md שלמעלה.

בעבר נהגנו כל הכללים במאגר Bazel (בקטע //tools/build_rules או //tools/build_defs). עדיין יש לנו כמה כללים, אבל אנחנו פועלים כדי להעביר את הכללים הנותרים.