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

חשיפה

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

דף זה כולל מפרטי חשיפה, שיטות מומלצות ודוגמאות.

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

אם עליך להשבית את בדיקת החשיפה (לדוגמה בעת ניסוי), השתמש ב---check_visibility=false.

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

מפרטי הרשאות גישה

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

לכל תווית יש אחד מהטפסים הבאים:

  • "//visibility:public": כל אחד יכול להשתמש ביעד הזה. (לא ניתנים לשילוב עם כל מפרט אחר).

  • "//visibility:private": רק יעדים בחבילה הזו יכולים להשתמש ביעד הזה. (אין לשלב אותם עם אף מפרט אחר).

  • "//foo/bar:__pkg__": מעניק גישה ליעדים שהוגדרו ב-//foo/bar (אך לא לחבילות המשנה שלו). כאן, __pkg__ הוא קטע תחבירי מיוחד המייצג את כל היעדים בחבילה.

  • "//foo/bar:__subpackages__": מעניק גישה ליעדים שהוגדרו ב-//foo/bar או לכל חבילות המשנה הישירות או העקיפות שלו. גם כאן, תחביר מיוחד של __subpackages__.

  • "//foo/bar:my_package_group": מעניק גישה לכל החבילות שנקראות על ידי קבוצת החבילות הנתונה.

    • קבוצות חבילות לא תומכות בתחביר המיוחד של __pkg__ ושל __subpackages__. בתוך קבוצת חבילות, הפונקציה "//foo/bar" שווה ערך ל-"//foo/bar:__pkg__", והערך "//foo/bar/..." שווה ערך ל-"//foo/bar:__subpackages__".

לדוגמה, אם הערך visibility של //some/package:mytarget הוגדר כ-[":__subpackages__", "//tests:__pkg__"], ניתן להשתמש בכל יעד שהוא חלק מעץ המקור של //some/package/... וגם יעדים שהוגדרו ב//tests/BUILD, אבל לא לפי יעדים שהוגדרו ב//tests/integration/BUILD.

כמקרה מיוחד, למאפיינים package_group אין יעדים עם מאפיין visibility; הוא תמיד גלוי לכול.

לא ניתן להגדיר את החשיפה ליעדים ספציפיים שאינם של package_group. הפעולה מפעילה את השגיאה "תווית לא מתייחסת לקבוצת חבילות" או "עיגול בתרשים התלות".

החשיפה של יעד כלל

אם יעד כלל לא מגדיר את המאפיין visibility, החשיפה שלו ניתנת על ידי default_visibility שצוין בpackage הצהרה של קובץ ה-BUILD של היעד. אם אין הצהרת default_visibility כזו, הניראות היא //visibility:private.

בעבר config_setting לא נאכפה חשיפה. --incompatible_enforce_config_setting_visibility ו---incompatible_config_setting_private_default_visibility מספקים לוגיקת העברה לשילוב עם כללים אחרים.

אם --incompatible_enforce_config_setting_visibility=false, כל config_setting מוגדר באופן מותנה לכל היעדים, ללא תנאי.

אחרת, אם הערך --incompatible_config_setting_private_default_visibility=false הוא config_setting, אם לא הוגדר במפורש סטטוס חשיפה, הוא //visibility:public (להתעלמות מהחבילה default_visibility).

אחרת, אם --incompatible_config_setting_private_default_visibility=true, config_setting משתמשת באותה לוגיקת חשיפה כמו כל הכללים האחרים.

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

דוגמה

קובץ //frobber/bin/BUILD:

# This target is visible to everyone
cc_binary(
    name = "executable",
    visibility = ["//visibility:public"],
    deps = [":library"],
)

# This target is visible only to targets declared in the same package
cc_library(
    name = "library",
    # No visibility -- defaults to private since no
    # package(default_visibility = ...) was used.
)

# This target is visible to targets in package //object and //noun
cc_library(
    name = "subject",
    visibility = [
        "//noun:__pkg__",
        "//object:__pkg__",
    ],
)

# See package group "//frobber:friends" (below) for who can
# access this target.
cc_library(
    name = "thingy",
    visibility = ["//frobber:friends"],
)

קובץ //frobber/BUILD:

# This is the package group declaration to which target
# //frobber/bin:thingy refers.
#
# Our friends are packages //frobber, //fribber and any
# subpackage of //fribber.
package_group(
    name = "friends",
    packages = [
        "//fribber/...",
        "//frobber",
    ],
)

הרשאות הגישה ליעד הקובץ שנוצר

יעד קיים של קובץ זהה לחשיפה של יעד כלל שיוצר אותו.

הרשאות הגישה ליעד של קובץ מקור

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

אם הקריאה ל-exports_files מציינת את מאפיין החשיפה, מידת החשיפה תהיה רלוונטית. אחרת, הקובץ גלוי לכול (default_visibility לא נכלל).

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

דוגמה

קובץ //frobber/data/BUILD:

exports_files(["readme.txt"])

קובץ //frobber/bin/BUILD:

cc_binary(
  name = "my-program",
  data = ["//frobber/data:readme.txt"],
)

התנהגות מדור קודם

אם הדגל --incompatible_no_implicit_file_export לא מוגדר, תחול התנהגות מדור קודם.

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

מי יכול לראות את קובצי ה-bzl

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

עם זאת, משתמשים יכולים לבחור להפעיל את הלימוד לבנייה. בדיקת bzl-ability מספקת אזהרה אם המשתמשים load נמצאים מתחת לספריית משנה בשם internal או private.

חשיפה של יחסי תלות מרומזים

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

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

שיטות מומלצות

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

  • השתמשו ב-package_group כדי לשתף את מפרטי החשיפה במספר יעדים. אפשרות זו שימושית במיוחד כאשר יש לחשוף יעדים בקובצי BUILD רבים לאותה קבוצת חבילות.

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