BazelCon 2022 מגיע בין 16 ל-17 בנובמבר לניו יורק באינטרנט. הירשמו עוד היום!
חדש: אנחנו מזמינים אותך להצטרף אלינו ליום הקהילה ב-15 בנובמבר! פרטים ורישום.

פעולות

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

חברי מועדון

Args

Args actions.args()

מחזירה אובייקט Args שניתן להשתמש בו כדי לבנות שורות פקודה יעילות בזיכרון.

הצהרת_ספרייה

File actions.declare_directory(filename, *, sibling=None)

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

פרמטרים

פרמטר תיאור
filename חובה
אם לא צוין #&39;sibling' נתיב של הספרייה החדשה, ביחס לחבילה הנוכחית. אחרת, שם הבסיס של הקובץ ('sibling' מגדיר ספרייה).
sibling File; or None; ברירת מחדל = ללא
קובץ ששוכן באותה ספרייה שבה נמצאת הספרייה החדשה. הקובץ חייב להיות בחבילה הנוכחית.

הצהרת_קובץ

File actions.declare_file(filename, *, sibling=None)

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

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

הערה: אין צורך להצהיר על קובצי פלט מוצהרים (ולא ניתן להצהיר עליהם באמצעות הפונקציה הזו). במקום זאת, אפשר לקבל את האובייקטים שלהם מ-File מ-ctx.outputs. דוגמה לשימוש.

פרמטרים

פרמטר תיאור
filename חובה
אם לא צוין #&39;sibling' הנתיב של הקובץ החדש, ביחס לחבילה הנוכחית. אחרת, שם בסיסי של קובץ ('sibling' קובע ספרייה).
sibling File; or None; ברירת מחדל = ללא
קובץ ששוכן באותה ספרייה כמו הקובץ החדש שנוצר. הקובץ חייב להיות בחבילה הנוכחית.

File actions.declare_symlink(filename, *, sibling=None)

ניסיוני. הפרמטר הזה ניסיוני ועשוי להשתנות בכל שלב. אין צורך להסתמך עליה. ניתן להפעיל את התכונה על ידי הגדרה של --experimental_allow_unresolved_symlinks

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

פרמטרים

פרמטר תיאור
filename חובה
אם לא צוין 'sibling' שצוין, הנתיב של הקישור הסמלי החדש, ביחס לחבילה הנוכחית. אחרת, שם הבסיס של הקובץ ('sibling' מגדיר ספרייה).
sibling File; or None; ברירת מחדל = ללא
קובץ ששוכן באותה ספרייה כמו הקישור הסמלי המוצהר.

כלום

None actions.do_nothing(mnemonic, inputs=[])

יוצר פעולה ריקה שלא מבצעת פקודה ולא מייצרת פלט, אבל היא שימושית להוספה של 'extra actions'

פרמטרים

פרמטר תיאור
mnemonic חובה
תיאור של הפעולה, כמו CPPCompile או GoLink.
inputs sequence of Files; or depset; ברירת מחדל = []
רשימה של קובצי הקלט של הפעולה.

תבנית_הרחבה

None actions.expand_template(template, output, substitutions={}, is_executable=False, computed_substitutions=unbound)

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

פרמטרים

פרמטר תיאור
template חובה
קובץ התבנית, שהוא קובץ טקסט בקידוד UTF-8.
output חובה
קובץ הפלט, שהוא קובץ טקסט בקידוד UTF-8.
substitutions ברירת מחדל = {}
חלופות לביצוע בעת הרחבת התבנית.
is_executable ברירת מחדל = False
האם קובץ הפלט צריך להיות קובץ הפעלה.
computed_substitutions TemplateDict; ברירת מחדל = לא מוגדרת
ניסיוני. הפרמטר הזה ניסיוני ועשוי להשתנות בכל שלב. אין צורך להסתמך עליה. אפשר להפעיל את התכונה באופן ניסיוני על ידי הגדרת המאפיין --+experimental_lazy_template_expansion
ניסיוני: החלפת רכיבים שניתן לבצע כשמרחיבים את התבנית.

הפעל

None actions.run(outputs, inputs=[], unused_inputs_list=None, executable, tools=unbound, arguments=[], mnemonic=None, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None)

יוצר פעולה שמפעילה קובץ הפעלה. דוגמה לשימוש.

פרמטרים

פרמטר תיאור
outputs sequence of Files; חובה
רשימה של קובצי הפלט של הפעולה.
inputs sequence of Files; or depset; ברירת מחדל = []
רשימה או מחיקה של קובצי הקלט של הפעולה.
unused_inputs_list File; or None; ברירת מחדל = ללא
קובץ המכיל רשימה של ערכי קלט שאינם בשימוש בפעולה זו.

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

executable File; or string; or FilesToRunProvider; נדרש
קובץ ההפעלה שהפעולה תפעיל.
tools sequence; or depset; ברירת מחדל = לא מוגדרת
עליך לפרט או לבטל את הכלים הנחוצים לפעולה. כלים הם ערכי קלט עם קובצי Runrun נוספים שזמינים באופן אוטומטי לפעולה. כשמספקים רשימה, היא יכולה להיות אוסף משוכלל של קבצים, מכונות FilesToRunProvider או גינות של קבצים. קבצים שכלולים ישירות ברשימה ומקורם ב-ctx.executable יתווספו לקבצים שלהם באופן אוטומטי. כשמסופקת מנהלים, היא חייבת לכלול רק קבצים. בשני המקרים, הקבצים בתוך השרתים לא מיוחסים ל-ctx.executable עבור קובצי runfile.
arguments sequence; ברירת מחדל = []
ארגומנטים לשורת פקודה של הפעולה. חייב להיות רשימת מחרוזות או אובייקטים מסוג actions.args().
mnemonic string; or None; ברירת מחדל = ללא
תיאור של הפעולה במילה אחת, לדוגמה: CppCompile או GoLink.
progress_message string; or None; ברירת מחדל = ללא
הודעת התקדמות שתוצג למשתמש במהלך יצירת ה-build. לדוגמה, "התאמת foo.cc ליצירת foo.o". ההודעה עשויה להכיל תבניות %{label}, %{input} או %{output}, שיוחלפו במחרוזת תווית, בנתיב הראשון או בנתיב פלט, בהתאמה. עדיף להשתמש בדפוסים במקום במחרוזות סטטיות, מפני שהדרך הראשונה יעילה יותר.
use_default_shell_env ברירת מחדל = False
האם הפעולה צריכה להשתמש בסביבה מובנית של מעטפת או לא.
env dict; or None; default = None
מגדיר את המילון של משתני הסביבה.
execution_requirements dict; or None; ברירת מחדל = ללא
מידע לגבי תזמון הפעולה. בקטע תגים אפשר לראות מפתחות שימושיים.
input_manifests sequence; or None; ברירת מחדל = ללא
(ניסיוני) מגדירה את המטא-נתונים של קובצי הרצה לקליטת נתונים. בדרך כלל הם נוצרים על ידי שירות לפענח_command.
exec_group string; or None; ברירת מחדל = ללא
מריץ את הפעולה בפלטפורמת ההפעלה הרלוונטית. אם לא, נעשה שימוש בפלטפורמת הביצוע של יעד ברירת המחדל.
shadowed_action Action; ברירת מחדל = ללא
מריצה את הפעולה באמצעות הקלט והסביבה שהוגדרו בצל של פעולות ונוספה לרשימת הקלט והסביבה של הפעולה. סביבת הפעולה יכולה להחליף כל משתני סביבה של פעולה מוצלת. אם אין, המערכת משתמשת רק בקלט של הפעולה ובסביבה הנתונה.
resource_set callable; or None; ברירת מחדל = ללא
פונקציית קריאה חוזרת שמחזירה מילון של קבוצת משאבים, משמשת להערכה של שימוש במשאבים בזמן הביצוע, אם הפעולה הזו מתבצעת באופן מקומי.

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

  • "cpu": מספר המעבדים; ברירת מחדל 1
  • "memory": ב-MB; ברירת מחדל 250
  • "local_test": מספר הבדיקות המקומיות; ברירת מחדל 1

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

הקריאה החוזרת (callback) חייבת להיות ברמה העליונה (אסור להשתמש בפונקציות lambda ופונקציות מקוננות).

Run_shell

None actions.run_shell(outputs, inputs=[], tools=unbound, arguments=[], mnemonic=None, command, progress_message=None, use_default_shell_env=False, env=None, execution_requirements=None, input_manifests=None, exec_group=None, shadowed_action=None, resource_set=None)

יצירה של פעולה שפועלת פקודת מעטפת. דוגמה לשימוש.

פרמטרים

פרמטר תיאור
outputs sequence of Files; חובה
רשימה של קובצי הפלט של הפעולה.
inputs sequence of Files; or depset; ברירת מחדל = []
רשימה או מחיקה של קובצי הקלט של הפעולה.
tools sequence of Files; or depset; ברירת מחדל = לא מוגדרת
עליך לפרט או לבטל את הכלים הנחוצים לפעולה. כלים הם ערכי קלט עם קובצי Runrun נוספים שזמינים באופן אוטומטי לפעולה. הרשימה יכולה להכיל קבצים מסוג Files או FilesToRunProvider.
arguments sequence; ברירת מחדל = []
ארגומנטים לשורת פקודה של הפעולה. חייב להיות רשימת מחרוזות או אובייקטים מסוג actions.args().

Bazel מעביר את הרכיבים שבמאפיין הזה כארגומנטים בפקודה.הפקודה יכולה לגשת לארגומנטים באמצעות תחליפי מעטפת, כמו $1, $2 וכו'. לתשומת לבך, מכיוון שאובייקטים של Args שטוחים לפני ההוספה לאינדקס, אם יש אובייקט Args בגודל לא ידוע, כל המחרוזות הבאות יהיו באינדקסים בלתי צפויים. כדאי להשתמש ב-$@ (כדי לאחזר את כל הארגומנטים) יחד עם אובייקטים של Args בגודל לא קבוע.

אם command הוא רשימה של מחרוזות, לא ניתן להשתמש בפרמטר הזה.

mnemonic string; or None; ברירת מחדל = ללא
תיאור של הפעולה במילה אחת, לדוגמה: CppCompile או GoLink.
command string; or sequence of strings; נדרשת
פקודת Shell לביצוע. הערך יכול להיות מחרוזת (מועדפת) או רצף של מחרוזות (הוצא משימוש).

אם הפונקציה command היא מחרוזת, אז היא תופעל כאילו היא sh -c <command> "" <arguments> – כלומר הרכיבים ב-arguments יהיו זמינים לפקודה בתור $1, $2 (או %1, %2 אם נעשה שימוש ב-Windows מקובצות) וכו'. אם arguments מכיל אובייקטים actions.args(), התוכן שלהם יצורף אחד לשורת הפקודה, כך ש-$i יכול להפנות למחרוזות בודדות בתוך אובייקט Args. חשוב לשים לב שאם אובייקט Args בגודל לא ידוע מועבר כחלק מ-arguments, המחרוזות יהיו באינדקסים לא ידועים. במקרה כזה, החלפת המעטפת של $@ (אחזור כל הארגומנטים) יכולה להיות שימושית.

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

Bazel משתמשת באותו מעטפת כדי לבצע את הפקודה בעת יצירת כללי כלל.

progress_message string; or None; ברירת מחדל = ללא
הודעת התקדמות שתוצג למשתמש במהלך יצירת ה-build. לדוגמה, "התאמת foo.cc ליצירת foo.o". ההודעה עשויה להכיל תבניות %{label}, %{input} או %{output}, שיוחלפו במחרוזת תווית, בנתיב הראשון או בנתיב פלט, בהתאמה. עדיף להשתמש בדפוסים במקום במחרוזות סטטיות, מפני שהדרך הראשונה יעילה יותר.
use_default_shell_env ברירת מחדל = False
האם הפעולה צריכה להשתמש בסביבה מובנית של מעטפת או לא.
env dict; or None; default = None
מגדיר את המילון של משתני הסביבה.
execution_requirements dict; or None; ברירת מחדל = ללא
מידע לגבי תזמון הפעולה. בקטע תגים אפשר לראות מפתחות שימושיים.
input_manifests sequence; or None; ברירת מחדל = ללא
(ניסיוני) מגדירה את המטא-נתונים של קובצי הרצה לקליטת נתונים. בדרך כלל הם נוצרים על ידי שירות לפענח_command.
exec_group string; or None; ברירת מחדל = ללא
מריץ את הפעולה בפלטפורמת ההפעלה הרלוונטית. אם לא, נעשה שימוש בפלטפורמת הביצוע של יעד ברירת המחדל.
shadowed_action Action; ברירת מחדל = ללא
הפעולה מתבססת על פעולת הצללית שהוזנה ונוספה לרשימת הקלט של הפעולה. אם אין, נעשה שימוש רק בקלט של הפעולה.
resource_set callable; or None; ברירת מחדל = ללא
פונקציית קריאה חוזרת להערכת השימוש במשאבים אם היא פועלת באופן מקומי. עיינו בctx.actions.run().

None actions.symlink(output, target_file=None, target_path=None, is_executable=False, progress_message=None)

יוצר פעולה שכותבת קישור סימבולי במערכת הקבצים.

יש לקרוא לפונקציה הזו בדיוק עם target_file או target_path שצוינו.

אם נעשה שימוש ב-target_file, צריך להצהיר על output עד declare_file() או declare_directory() ולהתאים לסוג target_file. במקרה כזה, output יהיה קישור סימולטיבי שהתוכן שלו הוא הנתיב של target_file.

אחרת, אם ייעשה שימוש ב-target_path, יהיה צורך להצהיר על output באמצעות declare_symlink(). במקרה כזה, output יהיה קישור סימבולי שהתוכן שלו הוא target_path. ניתן להשתמש באפשרות הזו כדי ליצור קישור סימבולי.

פרמטרים

פרמטר תיאור
output חובה
הפלט של הפעולה הזו.
target_file File; or None; default = None
הקובץ שאליו מפנה סמל הקישור של הפלט.
target_path string; or None; ברירת מחדל = ללא
(ניסיוני) הנתיב המדויק שאליו מפנה סמל הקישור לפלט. לא הוחלו נורמליזציה או עיבוד אחר. כדי לקבל גישה לתכונה הזו צריך להגדיר את --experimental_allow_unresolved_symlinks.
is_executable ברירת מחדל = False
ניתן להשתמש רק ב-target_file, ולא ב-target_path. אם הערך הוא TRUE, כשהפעולה מתבצעת, הנתיב target_file' מסומן כדי לאשר שניתן להפעיל אותו. אם לא, מתבצע דיווח על שגיאה. אם מגדירים את המאפיין is_executable כ-False, אין אפשרות להפעיל את היעד, אלא רק על כך שלא מתבצע אימות.

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

progress_message string; or None; ברירת מחדל = ללא
הודעת התקדמות שתוצג למשתמש במהלך יצירת ה-build.

תבנית_הכתבה

TemplateDict actions.template_dict()

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

כתיבה

None actions.write(output, content, is_executable=False)

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

פרמטרים

פרמטר תיאור
output חובה
קובץ הפלט.
content string; or Args; נדרש
תוכן הקובץ. יכול להיות מחרוזת או אובייקט actions.args().
is_executable ברירת מחדל = False
האם קובץ הפלט צריך להיות קובץ הפעלה.