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

כללים כלליים

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

כללים

כינוי

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

הכלל alias יוצר שם אחר שאפשר להתייחס אליו ככלל.

הכינוי פועל ביעדים של "regular" בלבד. ספציפית, לא ניתן לתת כינוי לpackage_group ולtest_suite.

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

  • הבדיקות לא פועלות אם הכינוי שלהם מוזכר בשורת הפקודה. כדי להגדיר כתובת אימייל חלופית שמפעילה את הבדיקה, יש להשתמש בכלל test_suite עם יעד יחיד במאפיין tests.
  • כשמגדירים קבוצות סביבה, הכינויים לכללים של environment לא נתמכים. הן גם לא נתמכות באפשרות שורת הפקודה --target_environment.

דוגמאות

filegroup(
    name = "data",
    srcs = ["data.txt"],
)

alias(
    name = "other",
    actual = ":data",
)

ארגומנטים

מאפיינים
name

Name; required

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

actual

Label; required

היעד שאליו כינוי זה מפנה. הוא לא חייב להיות כלל, אלא גם קובץ קלט.

config_setting

config_setting(name, constraint_values, define_values, deprecation, distribs, features, flag_values, licenses, tags, testonly, values, visibility)

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

דוגמאות

הרכיבים הבאים תואמים לכל מבנה המגדיר --compilation_mode=opt או -c opt (באופן מפורש בשורת הפקודה או באופן לא מפורש מקובצי .bazelrc):

  config_setting(
      name = "simple",
      values = {"compilation_mode": "opt"}
  )
  

הפונקציה הבאה תואמת לכל מבנה שמתמקד ב-RMA ומחיל את ההגדרה המותאמת אישית FOO=bar (למשל, bazel build --cpu=arm --define FOO=bar ...):

  config_setting(
      name = "two_conditions",
      values = {
          "cpu": "arm",
          "define": "FOO=bar"
      }
  )
  

הרכיבים הבאים תואמים לכל מבנה שמגדיר סימון בהגדרת משתמש --//custom_flags:foo=1 (באופן מפורש בשורת הפקודה או באופן לא מפורש מקובצי .bazelrc):

  config_setting(
      name = "my_custom_flag_is_set",
      flag_values = { "//custom_flags:foo": "1" },
  )
  

הפונקציה הבאה תואמת לכל מבנה שמטרגט לפלטפורמה עם ארכיטקטורה x86_64 ולגליבק 2.25, בהנחה שיש constraint_value עם תווית //example:glibc_2_25. חשוב לזכור שפלטפורמה עדיין תואמת אם היא מגדירה ערכי אילוץ נוספים מעבר לשני הסוגים האלה.

  config_setting(
      name = "64bit_glibc_2_25",
      constraint_values = [
          "@platforms//cpu:x86_64",
          "//example:glibc_2_25",
      ]
  )
  
בכל המקרים האלה, ייתכן שהתצורה תשתנה בתוך ה-build. לדוגמה, אם יש לבנות יעד בפלטפורמה שונה מזו של הפלטפורמה. גם אם config_setting לא תואם לסימונים של שורת הפקודה ברמה העליונה, ייתכן שעדיין תהיה התאמה לחלק מהיעדים.

הערות

  • יש לעיין בקטע select כדי לציין מה קורה כאשר config_setting תואמים למספר ההגדרות הנוכחיות.
  • עבור סימונים שתומכים בטפסים מקוצרים (למשל, --compilation_mode לעומת -c), ההגדרות של values חייבות להשתמש בטופס המלא. ההתאמות האלה פועלות באופן אוטומטי באמצעות כל אחד מהטפסים.
  • אם לסימון יש כמה ערכים (כמו --copt=-Da --copt=-Db או סימון בכוכב של רשימה), values = { "flag": "a" } מתאים אם "a" נמצא במקום כלשהו ברשימה בפועל.

    values = { "myflag": "a,b" } פועל באותו אופן: תואם: --myflag=a --myflag=b, --myflag=a --myflag=b --myflag=c, --myflag=a,b וגם --myflag=c,b,a. הסמנטיקה המדויקת משתנה בין הסימונים. לדוגמה, הפונקציה --copt לא תומכת בערכים מרובים באותה מכונה: הפונקציה --copt=a,b יוצרת את הפרמטר ["a,b"] בעוד שהפרמטר --copt=a --copt=b יוצר את ["a", "b"] (כך שהפרמטר values = { "copt": "a,b" } תואם לערך הקודם, אך לא הערך השני). אבל --ios_multi_cpus (לכללים של Apple) כן: -ios_multi_cpus=a,b ו-ios_multi_cpus=a --ios_multi_cpus=b מייצרים ["a", "b"]. יש לבדוק את הגדרות הסימונים ולבדוק את התנאים בקפידה כדי לאמת את הציפיות המדויקות.

  • אם צריך להגדיר תנאים שלא יהיו מבוססים על דגלי build מובנים, אפשר להשתמש ב דגלים המוגדרים ב-Starlark. אפשר גם להשתמש ב---define, אבל התמיכה הזו חלשה יותר ולא מומלץ להשתמש בה. אפשר למצוא דיון נוסף כאן.
  • לא מומלץ לחזור על אותן הגדרות של config_setting בחבילות שונות. במקום זאת, אפשר להפנות ל-config_setting נפוץ שמוגדרים בחבילה קנונית.
  • אפשר להשתמש בפורמטים values, define_values וגם constraint_values בכל שילוב באותו שילוב, אבל צריך להגדיר לפחות אחד לכל פלייליסט נתון.

ארגומנטים

מאפיינים
name

Name; required

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

constraint_values

List of labels; optional; nonconfigurable

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

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

define_values

Dictionary: String -> String; optional; nonconfigurable

זהה ל-values, אבל ספציפית לסימון --define.

--define הוא מיוחד כי התחביר שלו (--define KEY=VAL) פירושו ש-KEY=VAL הוא ערך מנקודת המבט של הדגל של Bazel.

כלומר:

            config_setting(
                name = "a_and_b",
                values = {
                    "define": "a=1",
                    "define": "b=2",
                })
          

לא פועל מפני שאותו מפתח (define) מופיע פעמיים במילון. מאפיין זה פותר את הבעיה:

            config_setting(
                name = "a_and_b",
                define_values = {
                    "a": "1",
                    "b": "2",
                })
          

יש התאמה מדויקת ל-bazel build //foo --define a=1 --define b=2.

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

flag_values

Dictionary: label -> String; optional; nonconfigurable

זהה ל-values אבל ל תכונות build שהוגדרו על ידי המשתמש.

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

values

Dictionary: String -> String; optional; nonconfigurable

קבוצת ערכי התצורה שתואמים לכלל הזה (מבוטאת כסימונים של build)

הכלל הזה יורש את ההגדרה של היעד המוגדר המפנה אליו בהצהרה של select. המערכת נחשבת כ-"match" הפעלה של Bazel אם לכל רשומה במילון, ההגדרה שלה תואמת לערך הצפוי של הרשומה. לדוגמה, values = {"compilation_mode": "opt"} מפעיל את bazel build --compilation_mode=opt ... ואת bazel build -c opt ... בכללים שהוגדרו לפי יעד.

מטעמי נוחות, ערכי התצורה מצוינים כדגלים של build (ללא "--" הקודמים). עם זאת, חשוב לזכור ששניהם אינם זהים. הסיבה לכך היא שניתן ליצור יעדים במספר תצורות באותו מבנה. לדוגמה, תצורת מארח&&33;s "cpu" תואמת לערך של --host_cpu, ולא ל---cpu. לכן, מופעים שונים של אותו config_setting עשויים להתאים לאותה הפעלה בהתאם לתצורה של הכלל שמשתמשים בהם.

אם סימון לא מוגדר במפורש בשורת הפקודה, נעשה שימוש בערך ברירת המחדל שלו. אם מפתח מופיע מספר פעמים במילון, נעשה שימוש רק במופע האחרון. אם מפתח מפנה לסימון שניתן להגדיר כמה פעמים בשורת הפקודה (למשל, bazel build --copt=foo --copt=bar --copt=baz ...), תתבצע התאמה אם אחת מההגדרות האלה תואמת.

קבוצת קבצים

filegroup(name, srcs, data, compatible_with, deprecation, distribs, features, licenses, output_group, restricted_to, tags, target_compatible_with, testonly, visibility)

יש להשתמש במאפיין filegroup כדי לתת שם נוח לאוסף של יעדים. לאחר מכן אפשר להפנות את הכללים האלה מכללים אחרים.

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

דוגמאות

כדי ליצור filegroup שמורכב משני קובצי מקור, יש לבצע:

filegroup(
    name = "mygroup",
    srcs = [
        "a_file.txt",
        "some/subdirectory/another_file.txt",
    ],
)

לחלופין, אפשר להשתמש ב-glob כדי לחפש בספריית נתוני הבדיקה:

filegroup(
    name = "exported_testdata",
    srcs = glob([
        "testdata/*.dat",
        "testdata/logs/**/*.log",
    ]),
)

כדי להשתמש בהגדרות האלה, צריך להפנות לfilegroup עם תווית מכל כלל:

cc_library(
    name = "my_library",
    srcs = ["foo.cc"],
    data = [
        "//my_package:exported_testdata",
        "//my_package:mygroup",
    ],
)

ארגומנטים

מאפיינים
name

Name; required

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

srcs

List of labels; optional

רשימת היעדים החברים בקבוצת הקבצים.

פעמים רבות משתמשים בתוצאה של ביטוי ב-glob בתור הערך של המאפיין srcs.

data

List of labels; optional

רשימת הקבצים הדרושים על ידי הכלל הזה בזמן הריצה.

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

output_group

String; optional

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

"Output group" היא קטגוריה של פריטי פלט של יעד, שצוינה בהטמעה של כלל זה.

שאילתה

genquery(name, deps, data, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, expression, features, licenses, opts, restricted_to, scope, strict, tags, target_compatible_with, testonly, visibility)

genquery() מריץ שאילתה שצוינה בשפת השאילתות המקוצרות ומוסיף את התוצאה לקובץ.

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

ההבדל היחיד בין השאילתות שמותרות כאן לבין שורת הפקודה הוא ששאילתות שמכילות מפרטי יעדים בתווים כלליים (למשל //pkg:* או //pkg:all) אינן מותרות כאן. הסיבות לכך הן שתי כפילויות: ראשית, מפני ש-genquery צריך לציין היקף כדי למנוע יעדים מחוץ לסגירה העקיפה של השאילתה, על מנת להשפיע על הפלט שלו. שנית, מכיוון ש-BUILD קבצים לא תומכים בתווי תו כללי לחיפוש (למשל, deps=["//a/..."]).

הפלט של genquery' נקבע על ידי שימוש ב---order_output=full כדי לאכוף פלט דקורטיבי.

שם קובץ הפלט הוא שם הכלל.

דוגמאות

בדוגמה הזו נכתבת רשימה של התוויות בסגירה העקיפה של היעד שצוין בקובץ.

genquery(
    name = "kiwi-deps",
    expression = "deps(//kiwi:kiwi_lib)",
    scope = ["//kiwi:kiwi_lib"],
)

ארגומנטים

מאפיינים
name

Name; required

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

expression

String; required

השאילתה להרצה. בניגוד לשורת הפקודה ולמקומות אחרים בקובצי BUILD, התוויות כאן פותרות את הבעיה ביחס לספריית הבסיס של סביבת העבודה. לדוגמה, התווית :b במאפיין הזה בקובץ a/BUILD תפנה אל היעד //:b.
opts

List of strings; optional

האפשרויות המועברות למנוע השאילתות. הן תואמות לאפשרויות בשורת הפקודה שאפשר להעביר אל bazel query. חלק מאפשרויות השאילתה לא מותרות כאן: --keep_going, --query_file, --universe_scope, --order_results ו---order_output. לאפשרויות שלא צוינו כאן יהיו ערכי ברירת המחדל, בדיוק כמו בשורת הפקודה של bazel query.
scope

List of labels; required

היקף השאילתה. השאילתה אינה מורשית לגעת ביעדים מחוץ לסגירה העקיפה של היעדים האלה.
strict

Boolean; optional; default is True

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

Genrule

genrule(name, srcs, outs, cmd, cmd_bash, cmd_bat, cmd_ps, compatible_with, deprecation, distribs, exec_compatible_with, exec_properties, exec_tools, executable, features, licenses, local, message, output_licenses, output_to_bindir, restricted_to, tags, target_compatible_with, testonly, toolchains, tools, visibility)

genrule יוצר קובץ אחד או יותר באמצעות פקודת Bash בהגדרת המשתמש.

כללי גנריים הם כללי בנייה כלליים שבהם אפשר להשתמש אם אין כלל ספציפי למשימה. לדוגמה, אפשר להפעיל מרווח פנימי של קו מוצרים (Bash). עם זאת, אם צריך להרכיב קובצי C++, יש לפעול בהתאם לכללים הקיימים של cc_*, כי כל העלייה הכבדה כבר בוצעה עבורך.

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

שיקולים הקשורים ליצירת אוסף צולב

במדריך למשתמש אפשר למצוא מידע נוסף על איסוף בין מקורות.

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

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

כשיוצרים כללים, מערכת ה-build מבטיחה שהתלויות יתבססו כראוי: srcs נקבעים (במידת הצורך) בהגדרה של target, הערך tools מוגדר עבור ההגדרה host, והפלט נחשב להגדרה של target. הוא גם מספק "Make" משתנים שפקודות הסימון יכולות להעביר לכלים המתאימים.

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

מקרים מיוחדים

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

JDK & C++ Tooling: כדי להשתמש בכלי של JDK או של המהדר C+K, מערכת ה-build מספקת קבוצת משתנים לשימוש. פרטים נוספים זמינים בקטע "Make" variable.

סביבת הז'אנר

פקודת ה מסוים מבוצע על ידי מעטפת אש, שכשלו, כשפקודה או צינור עיבוד נתונים נכשל, באמצעות set -e -o pipefail.

כלי ה-build מבצע את הפקודה 'Bash' בסביבת תהליכים מבוטאת, שמגדירה רק משתני ליבה כמו PATH, PWD, TMPDIR ומספר פרמטרים נוספים. כדי לוודא שיצירת ה-build מתחדשת, רוב המשתנים שמוגדרים בסביבה של המשתמשים במעטפת לא מועברים לפקודת הז'אנר. עם זאת, Bazel (אבל לא Blaze) מעביר את הערך של משתנה הסביבה PATH של המשתמש. כל שינוי בערך של PATH יגרום ל-Bazel לבצע מחדש את הפקודה ב-build הבא.

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

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

ייעוץ כללי

  • מוודאים שהכלים המופעלים על ידי ג'אנר הם לא צריכים לכתוב חותמות זמן בפלט, והם צריכים להשתמש בסדר קבוע עבור קבוצות ומפות, וכן כדי לכתוב רק נתיבי קבצים יחסיים לפלט, ולא בנתיבים מוחלטים. אי-ביצוע כלל זה יגרום להתנהגות לא צפויה של Build (Bazel לא בונה מחדש כלל שחשבת עליו) ותפגע בביצועים של המטמון.
  • את השימוש ב-$(location) יש לבצע במגוון רחב של פלט, כלים ומקורות. עקב ההפרדה של קובצי הפלט של הגדרות שונות, כללי כלל לא יכולים להסתמך על מסלולים שמקודדים ו/או מוחלטים.
  • כדאי לכתוב מאקרו נפוץ ב-Starlark למקרה שמשתמשים באותם כללים או דומים מאוד בכמה מקומות. אם הכלל הוא מורכב, כדאי ליישם אותו בסקריפט או בכלל של Starlark. כך ניתן לשפר את הקריאוּת ואת יכולת הבדיקה.
  • יש לוודא שקוד היציאה מציין באופן תקין את מידת ההצלחה או הכשל של הדור.
  • אל תכתבו הודעות אינפורמטיביות ל-Stdout או ל-Stderr. אמנם זה שימושי לניפוי באגים, אבל הוא עשוי להפוך לרעש בקלות. עדין מוצלח. מצד שני, לוח זמנים כושל אמור לדמות הודעות שגיאה טובות.
  • $$ evaluates to a $, a literal dollar-sign, so in order to invoke a shell command containing dollar-signs such as ls $(dirname $x), one must escape it thus: ls $$(dirname $$x)
  • יש להימנע מיצירת קישורי ספריות וספריות. מאחר ש-Bazel אינה מעתיקה את המבנה של הספרייה/ה-symlink, שנוצר על ידי כללים גנריים והבדיקה של תלות הספריות שלו לא נשמעת.
  • כשמאזכרים את כלל הכלל, אפשר להשתמש בתווית 'כללי' או בתוויות של קובצי פלט ספציפיים. לפעמים הגישה אחת קלה יותר לקריאה, ולפעמים הגישה האחרת: התייחסות לפלט לפי שם בכלל srcs תימנע באופן לא מכוון מפלט אחר של הז'אנר, אבל ייתכן שהיא תהיה מעייפה אם היא תניב תוצאות רבות.

דוגמאות

דוגמה זו יוצרת את foo.h. אין מקורות כי הפקודה לא מקבלת קלט. ה-"הבינארי והמירכאות; הרצה על ידי פקודה היא סקריפט מסוג Perl באותה חבילה כמו הג'אנר.

genrule(
    name = "foo",
    srcs = [],
    outs = ["foo.h"],
    cmd = "./$(location create_foo.pl) > \"$@\"",
    tools = ["create_foo.pl"],
)

בדוגמה הבאה אפשר לראות איך להשתמש ב-filegroup ובפלט של genrule אחר. לתשומת ליבך, אפשר להשתמש ב$(SRCS) גם במקום בהוראות $(location) מפורשות. בדוגמה הזאת אנחנו משתמשים בהוראה השנייה כדי להשלים הדגמה.

genrule(
    name = "concat_all_files",
    srcs = [
        "//some:files",  # a filegroup with multiple files in it ==> $(locations)
        "//other:gen",   # a genrule with a single output ==> $(location)
    ],
    outs = ["concatenated.txt"],
    cmd = "cat $(locations //some:files) $(location //other:gen) > $@",
)

ארגומנטים

מאפיינים
name

Name; required

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


אפשר לעיין בכלל הזה לפי שם בקטע srcs או deps בכללים אחרים של BUILD. אם הכלל יוצר קובצי מקור, יש להשתמש במאפיין srcs.
srcs

List of labels; optional

רשימת קלט של הכלל הזה, כגון קובצי מקור לעיבוד.

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

מערכת ה-build מבטיחה שהדרישות המוקדמות האלו נבנו לפני הרצת פקודת genrule; הן נבנו באמצעות אותה הגדרה של בקשת ה-build המקורית. השמות של הקבצים בדרישות המוקדמות האלה זמינים לפקודה כרשימה המופרדת ברווחים ב-$(SRCS). לחלופין, אפשר להגיע אל הנתיב של יעד אחד (srcs) //x:y באמצעות $(location //x:y), או להשתמש ב-$<, בתנאי שהרשומה הזו תהיה הרשומה היחידה ב-//srcs.

outs

List of filenames; required; nonconfigurable

רשימת קבצים שנוצרו על ידי הכלל הזה.

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

אם הדגל executable הוגדר, outs חייב להכיל תווית אחת בדיוק.

cmd

String; optional

הפקודה להרצה. כפופים ל-$(location) ולתחליף ל-"Make" .
  1. החלפת $(location) הראשונה, שמחליפה את כל המופעים של $(location label) ושל $(locations label).
  2. לתשומת ליבך, outs לא נכללים בתחליף הזה. קובצי הפלט תמיד נוצרים במיקום ניתן לחיזוי (זמין דרך $(@D), $@, $(OUTS) או $(RULEDIR). $(location output_name) בהמשך).

  3. לאחר מכן מרחיבים את המשתנים "Make" . חשוב לזכור שהמשתנים המוגדרים מראש $(JAVA), $(JAVAC) ו-$(JAVABASE) מרחיבים את ההגדרה מארח, כך שהפעלות Java שפועלות כחלק משלב של build יכולות לטעון בצורה נכונה ספריות משותפות ותלויות אחרות.
  4. לבסוף, הפקודה שמתקבלת מתבצעת באמצעות מעטפת באש. אם קוד היציאה אינו אפס, הפקודה נחשבת כ'נכשלה'.

הפקודה עשויה להפנות ל-*_binary יעדים. לשם כך היא צריכה להשתמש בתווית. המשתנים הבאים זמינים בשפת המשנה cmd:

  • "Make" משתנים
  • "Make" משתנים שהוגדרו מראש על ידי הכלים של Build. עליך להשתמש במשתנים האלה במקום בערכים הכתובים בתוך הקוד. כדי לראות רשימה של ערכים נתמכים, ניתן לעיין בקטע מוגדר מראש &משתנים;משתנים& במסמך הזה.

מדובר בחלופה של cmd_bash, cmd_ps ו-cmd_bat, אם אף אחת מהן לא רלוונטית.

אם אורך שורת הפקודה חורג מהגבלת הפלטפורמה (64K ב-Linux/macOS, 8K ב-Windows), הקוד יכתב את הפקודה על ידי סקריפט ויפעיל את הסקריפט כדי לעקוף אותו. הפעולה הזו חלה על כל מאפייני ה-CMd (cmd, cmd_bash, cmd_ps, cmd_bat).

cmd_bash

String; optional

פקודת Bash להפעלה.

למאפיין הזה יש עדיפות גבוהה יותר מ-cmd. הפקודה מורחבת ופועלת בדיוק כמו המאפיין cmd.

cmd_bat

String; optional

פקודת האצווה שתופעל ב-Windows.

למאפיין הזה יש עדיפות גבוהה יותר מאשר ל-cmd ול-cmd_bash. הפקודה פועלת באופן דומה למאפיין cmd, עם ההבדלים הבאים:

  • מאפיין זה חל רק על Windows.
  • הפקודה פועלת באמצעות cmd.exe /c עם הארגומנטים הבאים המוגדרים כברירת מחדל:
    • /S - להסיר את המירכאות הראשונות והאחרונות ולבצע את כל הפעולות כפי שהן.
    • /E:ON - הפעלה של קבוצת פקודה מורחבת.
    • /V:ON – הפעלת הרחבה של משתנה מעוכבת
    • /D - התעלמות מרשומות הרישום של AutoRun.
  • אחרי החלפת התווים $(location) ו-"Make"
cmd_ps

String; optional

פקודת Powershell יכולה לפעול ב-Windows.

למאפיין הזה יש עדיפות גבוהה יותר מאשר המאפיינים cmd, cmd_bash ו-cmd_bat. הפקודה פועלת באופן דומה למאפיין cmd, עם ההבדלים הבאים:

  • מאפיין זה חל רק על Windows.
  • הפקודה פועלת באמצעות powershell.exe /c.

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

  • Set-ExecutionPolicy -Scope CurrentUser RemoteSigned - מותר להריץ סקריפטים לא חתומים.
  • $errorActionPreference='Stop' – אם יש כמה פקודות שמופרדות באמצעות ;, הפעולה נסגרת באופן מיידי אם Powershell CmdLet נכשל, אבל היא לא פועלת בפקודה חיצונית.
  • $PSDefaultParameterValues['*:Encoding'] = 'utf8' - שינוי קידוד ברירת המחדל מ-utf-16 ל-utf-8.
exec_tools

List of labels; optional

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

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

executable

Boolean; optional; nonconfigurable; default is False

הצהרה על פלט לקובץ הפעלה.

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

אין תמיכה בהצהרת תלות נתונים לקובץ ההפעלה שנוצר.

local

Boolean; optional; default is False

אם המדיניות הזו מוגדרת כ-1, האפשרות הזו מאלצת את ההפעלה של genrule באמצעות השיטה "local" שמשמעותה היא ביצוע מרחוק, ללא ארגז חול (sandbox), ללא עובדים קבועים.

זה שווה ערך ל-'local' כתג (tags=["local"]).

message

String; optional

הודעת התקדמות.

הודעת התקדמות שתודפס במהלך ביצוע שלב ה-build הזה. כברירת מחדל, ההודעה היא "יוצרת פלט" (או משהו אחר בעיוור) אבל אפשר לספק הודעה ספציפית יותר. אפשר להשתמש במאפיין הזה במקום ב-echo או בהצהרות הדפסה אחרות בפקודה cmd, כי כך הכלי יכול לקבוע אם ההודעות שיישלחו יודפסו או לא.

output_licenses

Licence type; optional

הצגת common attributes
output_to_bindir

Boolean; optional; nonconfigurable; default is False

אם המדיניות מוגדרת כ-1, המערכת כותבת קובצי פלט לספרייה bin במקום לספרייה genfiles.

tools

List of labels; optional

רשימה של תלויות כלי לכלל הזה. מידע נוסף זמין בהגדרה של תלויות.

מערכת ה-build מוודאת שהדרישות המוקדמות האלו נוצרות לפני הפעלת פקודת 'הכלה'. הן מבוססות על מארח , כי הכלים האלה מופעלים במסגרת גרסת ה-build. אפשר להשיג את הנתיב של יעד אחד (tools) //x:y באמצעות $(location //x:y).

כל *_binary או כלי ש-cmd צריך לבצע יופיעו ברשימה הזו, ולא ב-srcs, כדי לוודא שהם מוגדרים נכון.

Test_Suite

test_suite(name, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, tests, visibility)

test_suite מגדיר קבוצת בדיקות שנחשבות לבני אדם כך פרויקטים יכולים להגדיר קבוצות של בדיקות, כמו "בדיקות שצריך להפעיל לפני ביצוע צ'ק-אין;“"ה פרויקט'של בדיקות לחץ הפקודה blaze test מכבדת את הארגון הזה: לצורך הפעלה, כמו blaze test //some/test:suite, מערכת Blaze סופרת קודם את כל יעדי הבדיקה שנכללים ביעד של //some/test:suite (אנחנו קוראים להם "test_Suite extension" ), ולאחר מכן Blaze בונה ובודק את היעדים האלה.

דוגמאות

חבילת בדיקה להפעלת כל הבדיקות הקטנות בחבילה הנוכחית.

test_suite(
    name = "small_tests",
    tags = ["small"],
)

חבילת בדיקה שמפעילה קבוצת בדיקות מסוימת:

test_suite(
    name = "smoke_tests",
    tests = [
        "system_unittest",
        "public_api_unittest",
    ],
)

חבילה ניסיונית להפעלת כל הבדיקות בחבילה הנוכחית שאינה מצומצמת.

test_suite(
    name = "non_flaky_test",
    tags = ["-flaky"],
)

ארגומנטים

מאפיינים
name

Name; required

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

tags

List of strings; optional; nonconfigurable

רשימה של תגי טקסט כגון "small" או "database" או "-flky". תגים יכולים להיות כל מחרוזת חוקית.

תגים שמתחילים בתו &"-" נחשבים לתגים שליליים. התו לפני &"-" לא נחשב לחלק מהתג, ולכן תג חבילה של"-small" תואם לגודל "small" . כל שאר התגים נחשבים לתגים חיוביים.

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

רק כללי בדיקה שתואמים לכל התגים החיוביים ואף אחד מהתגים השליליים ייכללו בחבילת הבדיקה. חשוב לדעת: אין פירוש הדבר שבדיקת שגיאות התלויה בבדיקות שמסוננות אינה חוקית. התלויות בבדיקות שדילגו עליהן עדיין צריכות להיות חוקיות (למשל: לא חסומות על ידי מגבלות חשיפה).

מילת המפתח manual של התג מתייחסת באופן שונה מזה שצוין למעלה, באמצעות "test_Suite ההרחבה" מבוצעת על ידי הפקודה blaze test בנושא הפעלות הכוללות תווים כלליים לחיפוש דפוסי יעד. כאן, test_suite יעדים שתויגו "ידני" מסוננים (ולכן לא מורחבים). התנהגות זו תואמת לאופן שבו blaze build ו-blaze test מטפלים בדפוסי יעד של תו כללי לחיפוש באופן כללי. חשוב לשים לב שהערך הזה שונה מההתנהגות של blaze query 'tests(E)', כי סוויטות תמיד מורחבות באמצעות פונקציית השאילתה tests, בלי קשר לתג manual.

לתשומת ליבך, בדיקה של size נחשבת כתג למטרות סינון.

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

tests

List of labels; optional; nonconfigurable

רשימה של חבילות בדיקה ויעדים לבדיקה בכל שפה.

ניתן להשתמש בכל *_test כאן, ללא קשר לשפה. עם זאת, לא ניתן להשתמש ביעדים של *_binary, גם אם הם מריצים בדיקה. סינון לפי tags שצוין מתבצע רק לבדיקות שמופיעות ישירות במאפיין הזה. אם המאפיין כולל test_suite, הבדיקות בתוך אלה לא יסוננו על ידי test_suite (הן כבר נחשבות כמסוננות).

אם המאפיין tests לא צוין או ריק, הכלל יוגדר כברירת מחדל כך שיכלול את כל כללי הבדיקה בקובץ ה-BUILD הנוכחי שלא תויגו כ-manual. הכללים האלה עדיין כפופים לסינון של tag.