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

כללי פלטפורמה

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

כללים

הגדרה של אילוץ

constraint_setting(name, default_constraint_value, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, tags, testonly, visibility)

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

לכל constraint_setting יש קבוצה ניתנת להרחבה של constraint_value שנ'. בדרך כלל אלו מוגדרים באותה חבילה, אבל לפעמים חבילה אחרת כוללת ערכים חדשים להגדרה קיימת. לדוגמה, ניתן להרחיב את ההגדרה המוגדרת מראש @platforms//cpu:cpu באמצעות ערך מותאם אישית כדי להגדיר פלטפורמה שמטרגטת ארכיטקטורת GPU לא מוסתרת.

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד הזה.

default_constraint_value

Name; optional

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

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

ערך_אילוץ

constraint_value(name, constraint_setting, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, tags, testonly, visibility)
הכלל הזה מציג ערך חדש עבור סוג אילוץ נתון. פרטים נוספים זמינים בדף פלטפורמות.

דוגמה

הפורמט הבא יוצר ערך אפשרי חדש עבור ה-constraint_value בדרישות של ארכיטקטורת PG.

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)
פלטפורמות יכולות להצהיר שיש להם את ארכיטקטורת mips כחלופה ל-x86_64, ל-arm וכו'.

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד הזה.

constraint_setting

Label; required

המאפיין constraint_setting שעבורו אפשר לבחור את constraint_value.

platform

platform(name, constraint_values, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, parents, remote_execution_properties, tags, testonly, visibility)

הכלל הזה מגדיר פלטפורמה חדשה – אוסף עם שם של אפשרויות לבחירה (כמו ארכיטקטורת מעבד (CPU) או גרסת מהדר) שמתאר את הסביבה שבה חלק מה-build עשוי לפעול. פרטים נוספים זמינים בדף פלטפורמות.

דוגמה

היא מגדירה פלטפורמה שמתארת כל סביבה הפועלת ב-Linux ב-ARM.

platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

ירושה בפלטפורמה

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

כשבודקים את הערך של הגדרת אילוץ בפלטפורמה, קודם כול בודקים את הערכים ישירות (באמצעות המאפיין constraint_values) ואז בודקים את ערכי האילוץ בהורה. כך, כל ערכים שמוגדרים בפלטפורמה באופן ישיר יבטלו את הערכים שהוגדרו בפלטפורמה של ההורה.

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

פלטפורמות יכולות גם לרשת את המאפיין remote_execution_properties (הוצא משימוש) מפלטפורמת ההורה. הערה: במקום זאת יש להשתמש בקוד חדש exec_properties. הלוגיקה המתוארת בהמשך מיועדת להתאים להתנהגות הקודמת, אבל תוסר בעתיד. הלוגיקה להגדרת remote_execution_platform היא: כאשר יש פלטפורמת הורה:

  1. אם השדה remote_execution_property לא מוגדר בפלטפורמת הצאצא, ייעשה שימוש ב-remote_execution_properties של ההורה.
  2. אם המדיניות remote_execution_property מוגדרת בפלטפורמת הצאצא ומכילה את המחרוזת הליטרלית {PARENT_REMOTE_EXECUTION_PROPERTIES}, המאקרו הזה יוחלף בתוכן המאפיין remote_execution_property של ההורה.
  3. אם המדיניות remote_execution_property מוגדרת בפלטפורמת הצאצא ולא מכילה את המאקרו, ייעשה שימוש ב-remote_execution_property של הילד או הילדה ללא שינוי.

מכיוון ש-remote_execution_properties הוצא משימוש ויופסק בהדרגה, אסור לשלב את remote_execution_properties עם exec_properties באותה שרשרת ירושה. אני רוצה להשתמש ב-exec_properties במקום ב-remote_execution_properties שהוצא משימוש.

דוגמה: ערכי מגבלה

platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)

בדוגמה הזו, לפלטפורמות צאצא יש את המאפיינים הבאים:

  • ל-child_a יש את ערכי האילוץ @platforms//os:linux (עוברת בירושה מההורה) ואת @platforms//cpu:x86_64 (שמוגדרים ישירות בפלטפורמה).
  • ההגדרה child_b יורשת את כל ערכי האילוצים מהורה, ואינה מגדירה אף אחד מהם.

דוגמה: מאפייני ביצוע

platform(
    name = "parent",
    exec_properties = {
      "k1": "v1",
      "k2": "v2",
    },
)
platform(
    name = "child_a",
    parents = [":parent"],
)
platform(
    name = "child_b",
    parents = [":parent"],
    exec_properties = {
      "k1": "child"
    }
)
platform(
    name = "child_c",
    parents = [":parent"],
    exec_properties = {
      "k1": ""
    }
)
platform(
    name = "child_d",
    parents = [":parent"],
    exec_properties = {
      "k3": "v3"
    }
)

בדוגמה הזו, לפלטפורמות צאצא יש את המאפיינים הבאים:

  • child_a יורשת את הפרמטר "exec_properties" של ההורה ולא מגדירה אותו בעצמו.
  • ההגדרה child_b יורשת את exec_properties של ההורה ותבטל את הערך של k1. הexec_properties יהיה: { "k1": "child", "k2": "v2" }.
  • ההגדרה child_c יורשת את exec_properties של ההורה ותבטל את ההגדרה של k1. הexec_properties יהיה: { "k2": "v2" }.
  • child_d יורש את חשבון exec_properties של ההורה ומוסיף נכס חדש. הexec_properties יהיה: { "k1": "v1", "k2": "v2", "k3": "v3" }.

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד הזה.

constraint_values

List of labels; optional

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

כל constraint_value ברשימה זו חייב להיות עבור constraint_setting אחר. לדוגמה, לא ניתן להגדיר פלטפורמה שמחייבת את הארכיטקטורה של ה-CPU על בסיס @platforms//cpu:x86_64 וגם @platforms//cpu:arm.

exec_properties

Dictionary: String -> String; optional

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

List of labels; optional

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

String; optional

הוצא משימוש. במקום זאת, יש להשתמש במאפיין exec_properties. מחרוזת המשמשת להגדרת פלטפורמת ביצוע מרחוק. גרסאות build בפועל אינן מנסות לפרש את זה, ומתייחסות לנתונים אטומים שיוכלו להשתמש ב-SpwnRunner ספציפי. נתונים אלה יכולים לכלול את הנתונים מפלטפורמת ההורה של &quot33;s "remote_execution_properties" באמצעות המאקרו "{PARENT_REMOTE_EXECUTION_PROPERTIES}" לקבלת פרטים, יש לעיין בקטע ירושה בפלטפורמה.

toolchain

toolchain(name, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

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

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד הזה.

exec_compatible_with

List of labels; optional; nonconfigurable

רשימה של constraint_value שפלטפורמת ההפעלה צריכה לעמוד בהם כדי שכלי הבחירה הזה ייבחר עבור מבנה יעד בפלטפורמה הזו.
target_compatible_with

List of labels; optional; nonconfigurable

רשימה של constraint_value שנדרשים מפלטפורמת היעד כדי שניתן יהיה לבחור בארגז הכלים הזה עבור מבנה יעד של הפלטפורמה.
target_settings

List of labels; optional

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

Name; required

היעד שמייצג את הכלי או את חבילת הכלים הזמינים בפועל כשבוחרים בשרשרת הכלים הזו.
toolchain_type

Label; required; nonconfigurable

התווית של יעד toolchain_type שמייצג את התפקיד שכלי הכלי הזה משרת.

Toolchain_type

toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

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

פרטים נוספים זמינים בדף Toolchains.

דוגמה

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

toolchain_type(
    name = "bar_toolchain_type",
)

אפשר להשתמש בקובץ Bzl.

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)

ארגומנטים

מאפיינים
name

Name; required

שם ייחודי ליעד הזה.