כללי פריסה

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

כללים לאירוח ובחירת שמות

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

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

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

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

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

תוכן המאגר

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

לדוגמה, כשכותבים כללים חדשים בשפה (make-feed) 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 שלך ובקריאת מאקרו שמאפשרת הורדה/הגדרה של כל הכלים שהכלל שלך צריך. לדוגמה, הכללים:

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_settings ו/או constraint_values מותאם אישית. יש להעביר אותן לחבילה של //<LANG>/constraints. מבנה הספרייה שלכם ייראה כך:

/
  mockascript/
    constraints/
      BUILD
    BUILD
    defs.bzl

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

ספריית Runfiles

אם הכלל שלך מספק ספרייה רגילה לצורך גישה לקובצי ריצה, הוא צריך להיות בצורת יעד מסוג ספרייה שנמצא ב-//<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). עדיין יש לנו כמה כללים, אבל אנחנו עובדים על העברת הכללים הנותרים.