การเปิดเผย

หน้านี้ครอบคลุมระบบการแสดงผล 2 ระบบของ Bazel: การแสดงผลเป้าหมาย และ การแสดงผลการโหลด

การแสดงผลทั้ง 2 ประเภทช่วยให้นักพัฒนาซอฟต์แวร์คนอื่นๆ แยกแยะได้ระหว่าง API สาธารณะของไลบรารีกับรายละเอียดการใช้งาน และช่วยบังคับใช้โครงสร้างเมื่อพื้นที่ทำงานขยายใหญ่ขึ้น นอกจากนี้ คุณยังใช้การแสดงผลเมื่อเลิกใช้งาน API สาธารณะเพื่ออนุญาตผู้ใช้ปัจจุบันขณะที่ปฏิเสธผู้ใช้ใหม่ได้ด้วย

การมองเห็นเป้าหมาย

การแสดงผลเป้าหมาย จะควบคุมผู้ที่อาจขึ้นอยู่กับเป้าหมายของคุณ นั่นคือผู้ที่อาจใช้ป้ายกำกับของเป้าหมายภายในแอตทริบิวต์ เช่น deps เป้าหมายจะสร้างไม่สำเร็จ ในระยะการวิเคราะห์หาก ละเมิดการแสดงผลของทรัพยากร Dependency รายการใดรายการหนึ่ง

โดยทั่วไปแล้ว เป้าหมาย A จะแสดงต่อเป้าหมาย B หากเป้าหมายทั้ง 2 อยู่ในตำแหน่งเดียวกัน หรือหาก A ให้สิทธิ์การมองเห็นแก่ตำแหน่งของ B หากไม่มี มาโครสัญลักษณ์ คำว่า "ตำแหน่ง" สามารถย่อ ให้เหลือเพียง "แพ็กเกจ" ได้ โปรดดู ข้อมูลเพิ่มเติมเกี่ยวกับมาโครสัญลักษณ์ด้านล่าง

การแสดงผลจะระบุโดยการแสดงรายการแพ็กเกจที่ได้รับอนุญาต การอนุญาตแพ็กเกจไม่ได้หมายความว่าระบบจะอนุญาตแพ็กเกจย่อยด้วย ดูรายละเอียดเพิ่มเติมเกี่ยวกับ แพ็กเกจและแพ็กเกจย่อยได้ที่ แนวคิดและคำศัพท์

สำหรับการสร้างต้นแบบ คุณสามารถปิดใช้การบังคับใช้การแสดงผลเป้าหมายได้โดยตั้งค่าแฟล็ก --check_visibility=false ไม่ควรทำเช่นนี้กับการใช้งานจริงในโค้ดที่ส่ง

วิธีหลักในการควบคุมการแสดงผลคือการใช้แอตทริบิวต์ของกฎ visibility ส่วนย่อยต่อไปนี้จะอธิบายรูปแบบของแอตทริบิวต์ วิธีใช้แอตทริบิวต์กับเป้าหมายชนิดต่างๆ และการมีปฏิสัมพันธ์ระหว่างระบบการมองเห็นกับมาโครสัญลักษณ์

ข้อกำหนดการแสดงผล

เป้าหมายกฎทั้งหมดมีแอตทริบิวต์ visibility ที่ใช้รายการป้ายกำกับ ป้ายกำกับแต่ละรายการมีรูปแบบใดรูปแบบหนึ่งต่อไปนี้ ยกเว้นรูปแบบสุดท้าย รูปแบบเหล่านี้เป็นเพียงตัวยึดตำแหน่งทางไวยากรณ์ที่ไม่ได้สอดคล้องกับเป้าหมายจริง

• "//visibility:public": ให้สิทธิ์เข้าถึงแพ็กเกจทั้งหมด

• "//visibility:private": ไม่ให้สิทธิ์เข้าถึงเพิ่มเติม มีเพียงเป้าหมาย ในแพ็กเกจของตำแหน่งนี้เท่านั้นที่ใช้เป้าหมายนี้ได้

• "//foo/bar:__pkg__": ให้สิทธิ์เข้าถึง //foo/bar (แต่ไม่ใช่ แพ็กเกจย่อย)

• "//foo/bar:__subpackages__": ให้สิทธิ์เข้าถึง //foo/bar และแพ็กเกจย่อยทั้งหมดทั้งโดยตรงและโดยอ้อม

• "//some_pkg:my_package_group": ให้สิทธิ์เข้าถึงแพ็กเกจทั้งหมดที่ เป็นส่วนหนึ่งของ package_group ที่ระบุ

  • กลุ่มแพ็กเกจใช้ไวยากรณ์ที่ แตกต่างกันในการ ระบุแพ็กเกจ ภายในกลุ่มแพ็กเกจ รูปแบบ "//foo/bar:__pkg__" และ "//foo/bar:__subpackages__" จะถูกแทนที่ด้วย "//foo/bar" และ "//foo/bar/..." ตามลำดับ เช่นเดียวกัน "//visibility:public" และ "//visibility:private" จะเป็นเพียง "public" และ "private"

ตัวอย่างเช่น หาก //some/package:mytarget มี visibility ตั้งค่าเป็น [":__subpackages__", "//tests:__pkg__"] เป้าหมายนี้จะใช้ได้โดยเป้าหมายใดก็ตาม ที่เป็นส่วนหนึ่งของแผนผังแหล่งที่มา //some/package/... รวมถึงเป้าหมาย ที่ประกาศใน //tests/BUILD แต่เป้าหมายที่กำหนดไว้ใน //tests/integration/BUILD จะใช้ไม่ได้

แนวทางปฏิบัติแนะนำ: หากต้องการทำให้เป้าหมายหลายรายการแสดงต่อแพ็กเกจชุดเดียวกัน ให้ใช้ package_group แทนการทำซ้ำรายการในแอตทริบิวต์ visibility ของเป้าหมายแต่ละรายการ วิธีนี้จะช่วยเพิ่มความสามารถในการอ่านและป้องกันไม่ให้รายการไม่ซิงค์กัน

แนวทางปฏิบัติแนะนำ: เมื่อให้สิทธิ์การแสดงผลแก่โปรเจ็กต์ของทีมอื่น ให้ใช้ __subpackages__ แทน __pkg__ เพื่อหลีกเลี่ยงการเปลี่ยนแปลงการแสดงผลที่ไม่จำเป็นเมื่อโปรเจ็กต์นั้นพัฒนาและเพิ่มแพ็กเกจย่อยใหม่

การแสดงผลเป้าหมายกฎ

การแสดงผลเป้าหมายกฎจะกำหนดโดยใช้แอตทริบิวต์ visibility หรือค่าเริ่มต้นที่เหมาะสมหากไม่ได้ระบุไว้ และต่อท้ายตำแหน่งที่ ประกาศเป้าหมาย สำหรับเป้าหมายที่ไม่ได้ประกาศในมาโครสัญลักษณ์ หาก แพ็กเกจระบุ default_visibility, ระบบจะใช้ค่าเริ่มต้นนี้ แต่สำหรับแพ็กเกจอื่นๆ ทั้งหมดและสำหรับเป้าหมายที่ประกาศใน มาโครสัญลักษณ์ ค่าเริ่มต้นจะเป็น ["//visibility:private"]

# //mypkg/BUILD

package(default_visibility = ["//friend:__pkg__"])

cc_library(
    name = "t1",
    ...
    # No visibility explicitly specified.
    # Effective visibility is ["//friend:__pkg__", "//mypkg:__pkg__"].
    # If no default_visibility were given in package(...), the visibility would
    # instead default to ["//visibility:private"], and the effective visibility
    # would be ["//mypkg:__pkg__"].
)

cc_library(
    name = "t2",
    ...
    visibility = [":clients"],
    # Effective visibility is ["//mypkg:clients, "//mypkg:__pkg__"], which will
    # expand to ["//another_friend:__subpackages__", "//mypkg:__pkg__"].
)

cc_library(
    name = "t3",
    ...
    visibility = ["//visibility:private"],
    # Effective visibility is ["//mypkg:__pkg__"]
)

package_group(
    name = "clients",
    packages = ["//another_friend/..."],
)

แนวทางปฏิบัติแนะนำ: หลีกเลี่ยงการตั้งค่า default_visibility เป็นสาธารณะ แม้ว่าการตั้งค่านี้อาจสะดวกสำหรับการสร้างต้นแบบหรือในฐานของโค้ดขนาดเล็ก แต่ความเสี่ยงในการสร้างเป้าหมายสาธารณะโดยไม่ตั้งใจจะเพิ่มขึ้นเมื่อฐานของโค้ดขยายใหญ่ขึ้น จึงควรระบุอย่างชัดเจนว่าเป้าหมายใดเป็นส่วนหนึ่งของอินเทอร์เฟซสาธารณะของแพ็กเกจ

การแสดงผลเป้าหมายไฟล์ที่สร้างขึ้น

เป้าหมายไฟล์ที่สร้างขึ้นมีการแสดงผลเหมือนกับเป้าหมายกฎที่สร้างไฟล์นั้น

# //mypkg/BUILD

java_binary(
    name = "foo",
    ...
    visibility = ["//friend:__pkg__"],
)

# //friend/BUILD

some_rule(
    name = "bar",
    deps = [
        # Allowed directly by visibility of foo.
        "//mypkg:foo",
        # Also allowed. The java_binary's "_deploy.jar" implicit output file
        # target the same visibility as the rule target itself.
        "//mypkg:foo_deploy.jar",
    ]
    ...
)

การแสดงผลเป้าหมายไฟล์แหล่งที่มา

เป้าหมายไฟล์แหล่งที่มาสามารถประกาศได้อย่างชัดเจนโดยใช้ exports_files หรือสร้างขึ้นโดยนัย ด้วยการอ้างอิงชื่อไฟล์ในแอตทริบิวต์ป้ายกำกับของกฎ (นอก มาโครสัญลักษณ์) เช่นเดียวกับเป้าหมายกฎ ตำแหน่งของการเรียกใช้ exports_files หรือไฟล์ BUILD ที่อ้างอิงไฟล์อินพุตจะต่อท้ายการแสดงผลของไฟล์โดยอัตโนมัติเสมอ

ไฟล์ที่ประกาศโดย exports_files สามารถตั้งค่าการแสดงผลได้โดยพารามิเตอร์ visibility ของฟังก์ชันนั้น หากไม่ได้ระบุพารามิเตอร์นี้ การแสดงผลจะเป็นสาธารณะ

สำหรับไฟล์ที่ไม่ได้ปรากฏในการเรียกใช้ exports_files การแสดงผล จะขึ้นอยู่กับค่าของแฟล็ก --incompatible_no_implicit_file_export ดังนี้

• หากแฟล็กเป็นจริง การแสดงผลจะเป็นแบบส่วนตัว

• หากไม่เป็นจริง ระบบจะใช้ลักษณะการทำงานเดิม นั่นคือการแสดงผลจะเหมือนกับ default_visibility ของไฟล์ BUILD หรือเป็นแบบส่วนตัวหากไม่ได้ระบุการแสดงผลเริ่มต้น

หลีกเลี่ยงการใช้ลักษณะการทำงานเดิม เขียนการประกาศ exports_files ทุกครั้งที่เป้าหมายไฟล์แหล่งที่มาต้องมีการแสดงผลที่ไม่ใช่แบบส่วนตัว

แนวทางปฏิบัติแนะนำ: หากเป็นไปได้ ให้แสดงเป้าหมายกฎแทนไฟล์แหล่งที่มา ตัวอย่างเช่น แทนที่จะเรียกใช้ exports_files ในไฟล์ .java ให้ห่อไฟล์ในเป้าหมาย java_library ที่ไม่ใช่แบบส่วนตัว โดยทั่วไปแล้ว เป้าหมายกฎควรอ้างอิงไฟล์แหล่งที่มาที่อยู่ในแพ็กเกจเดียวกันโดยตรงเท่านั้น

ตัวอย่าง

ไฟล์ //frobber/data/BUILD

exports_files(["readme.txt"])

ไฟล์ //frobber/bin/BUILD

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

การแสดงผลการตั้งค่าการกำหนดค่า

ในอดีต Bazel ไม่ได้บังคับใช้การแสดงผลสำหรับ config_setting เป้าหมายที่ อ้างอิงในคีย์ของ select() โดยมีแฟล็ก 2 รายการเพื่อนำลักษณะการทำงานเดิมนี้ออก

• --incompatible_enforce_config_setting_visibility จะเปิดใช้การตรวจสอบการแสดงผลสำหรับเป้าหมายเหล่านี้ นอกจากนี้ ยังทำให้ config_setting ใดก็ตามที่ไม่ได้ระบุ visibility ถือเป็นสาธารณะ (ไม่ว่า default_visibility ระดับแพ็กเกจจะเป็นอย่างไร) เพื่อช่วยในการย้ายข้อมูล

• --incompatible_config_setting_private_default_visibility จะทำให้ config_setting ที่ไม่ได้ระบุ visibility เป็นไปตาม default_visibility ของแพ็กเกจและกลับไปใช้การแสดงผลแบบส่วนตัว เช่นเดียวกับ เป้าหมายกฎอื่นๆ แฟล็กนี้จะไม่มีผลหากไม่ได้ตั้งค่า --incompatible_enforce_config_setting_visibility

หลีกเลี่ยงการใช้ลักษณะการทำงานเดิม config_setting ใดก็ตามที่ต้องการใช้ภายนอกแพ็กเกจปัจจุบันควรมี visibility ที่ชัดเจน หากแพ็กเกจไม่ได้ระบุ default_visibility ที่เหมาะสมไว้แล้ว

การแสดงผลเป้าหมายกลุ่มแพ็กเกจ

เป้าหมาย package_group ไม่มีแอตทริบิวต์ visibility แต่จะแสดงต่อสาธารณะเสมอ

การแสดงผลทรัพยากร Dependency โดยนัย

กฎบางข้อมีทรัพยากร Dependency โดยนัย — ทรัพยากร Dependency ที่ไม่ได้ระบุไว้ในไฟล์ BUILD แต่เป็นส่วนสำคัญของ กฎแต่ละอินสแตนซ์ ตัวอย่างเช่น กฎ cc_library อาจสร้างทรัพยากร Dependency โดยนัยจากเป้าหมายกฎแต่ละรายการไปยังเป้าหมายที่ดำเนินการได้ซึ่งแสดงถึงคอมไพเลอร์ C++

ระบบจะตรวจสอบการแสดงผลของทรัพยากร Dependency โดยนัยดังกล่าวโดยอิงตามแพ็กเกจที่มีไฟล์ .bzl ซึ่งกำหนดกฎ (หรือ Aspect) ในตัวอย่างของเรา คอมไพเลอร์ C++ อาจเป็นแบบส่วนตัวได้ตราบใดที่อยู่ในแพ็กเกจเดียวกับคำจำกัดความของกฎ cc_library หากทรัพยากร Dependency โดยนัยไม่แสดงจากคำจำกัดความ ระบบจะตรวจสอบทรัพยากร Dependency โดยนัยโดยอิงตามเป้าหมาย cc_library

หากต้องการจำกัดการใช้งานกฎไว้เฉพาะแพ็กเกจบางรายการ ให้ใช้ การแสดงผลการโหลดแทน

การแสดงผลและมาโครสัญลักษณ์

ส่วนนี้จะอธิบายวิธีที่ระบบการแสดงผลโต้ตอบกับ มาโครสัญลักษณ์

ตำแหน่งภายในมาโครสัญลักษณ์

รายละเอียดที่สำคัญของระบบการแสดงผลคือวิธีที่เรากำหนดตำแหน่งของการประกาศ สำหรับเป้าหมายที่ไม่ได้ประกาศในมาโครสัญลักษณ์ ตำแหน่งจะเป็นเพียงแพ็กเกจที่เป้าหมายอยู่ นั่นคือแพ็กเกจของไฟล์ BUILD แต่สำหรับเป้าหมายที่สร้างขึ้นในมาโครสัญลักษณ์ ตำแหน่งจะเป็นแพ็กเกจที่มีไฟล์ .bzl ซึ่งคำจำกัดความของมาโคร (คำสั่ง my_macro = macro(...)) ปรากฏอยู่ เมื่อสร้างเป้าหมายภายในเป้าหมายที่ซ้อนกันหลายรายการ ระบบจะใช้คำจำกัดความของมาโครสัญลักษณ์ที่อยู่ด้านในสุดเสมอ

ระบบเดียวกันนี้ใช้เพื่อกำหนดตำแหน่งที่จะตรวจสอบการแสดงผลของทรัพยากร Dependency ที่กำหนด หากสร้างเป้าหมายที่ใช้ภายในมาโคร เราจะดูคำจำกัดความของมาโครที่อยู่ด้านในสุดแทนที่จะดูแพ็กเกจที่เป้าหมายที่ใช้เป้าหมายนั้นอยู่

ซึ่งหมายความว่ามาโครทั้งหมดที่มีการกำหนดโค้ดไว้ในแพ็กเกจเดียวกันจะเป็น "เพื่อน" กันโดยอัตโนมัติ เป้าหมายใดก็ตามที่สร้างขึ้นโดยตรงโดยมาโคร ที่กำหนดไว้ใน //lib:defs.bzl จะมองเห็นได้จากมาโครอื่นๆ ที่กำหนดไว้ใน //lib, ไม่ว่ามาโครจะมีการสร้างอินสแตนซ์ในแพ็กเกจใดก็ตาม เช่นเดียวกัน มาโครเหล่านี้จะมองเห็นและมองเห็นได้โดยเป้าหมายที่ประกาศโดยตรงใน //lib/BUILD และมาโครเดิม ในทางกลับกัน เป้าหมายที่อยู่ในแพ็กเกจเดียวกันอาจมองไม่เห็นกันและกันหากเป้าหมายอย่างน้อย 1 รายการสร้างขึ้นโดยมาโครสัญลักษณ์

ภายในฟังก์ชันการใช้งานของมาโครสัญลักษณ์ พารามิเตอร์ visibility จะมีค่าที่มีผลของแอตทริบิวต์ visibility ของมาโครหลังจากต่อท้ายตำแหน่งที่เรียกใช้มาโคร วิธีมาตรฐานสำหรับมาโครในการส่งออกเป้าหมายรายการใดรายการหนึ่งไปยังผู้เรียกคือการส่งต่อค่านี้ไปยังการประกาศของเป้าหมาย เช่น some_rule(..., visibility = visibility) เป้าหมายที่ละเว้นแอตทริบิวต์นี้จะไม่แสดงต่อผู้เรียกของมาโคร เว้นแต่ผู้เรียกจะอยู่ในแพ็กเกจเดียวกับคำจำกัดความของมาโคร ลักษณะการทำงานนี้จะรวมกันในแง่ที่ว่าการเรียกใช้มาโครย่อยที่ซ้อนกันเป็นลำดับอาจส่ง visibility = visibility ซึ่งจะส่งออกเป้าหมายที่ส่งออกของมาโครภายในไปยังผู้เรียกในแต่ละระดับ โดยไม่เปิดเผยรายละเอียดการใช้งานของมาโคร

การมอบสิทธิ์ให้กับมาโครย่อย

โมเดลการแสดงผลมีฟีเจอร์พิเศษที่ช่วยให้มาโครมอบสิทธิ์ให้กับมาโครย่อยได้ ซึ่งเป็นสิ่งสำคัญสำหรับการแยกตัวประกอบและการรวมมาโคร

สมมติว่าคุณมีมาโคร my_macro ที่สร้างขอบทรัพยากร Dependency โดยใช้กฎ some_library จากแพ็กเกจอื่น

# //macro/defs.bzl
load("//lib:defs.bzl", "some_library")

def _impl(name, visibility, ...):
    ...
    native.genrule(
        name = name + "_dependency"
        ...
    )
    some_library(
        name = name + "_consumer",
        deps = [name + "_dependency"],
        ...
    )

my_macro = macro(implementation = _impl, ...)

# //pkg/BUILD

load("//macro:defs.bzl", "my_macro")

my_macro(name = "foo", ...)

เป้าหมาย //pkg:foo_dependency ไม่ได้ระบุ visibility จึงแสดงเฉพาะภายใน //macro ซึ่งใช้ได้ดีกับเป้าหมายที่ใช้ ทีนี้จะเกิดอะไรขึ้นหากผู้เขียน //lib ปรับโครงสร้าง some_library ให้ใช้งานโดยใช้มาโครแทน

# //lib:defs.bzl

def _impl(name, visibility, deps, ...):
    some_rule(
        # Main target, exported.
        name = name,
        visibility = visibility,
        deps = deps,
        ...)

some_library = macro(implementation = _impl, ...)

การเปลี่ยนแปลงนี้ทำให้ตำแหน่งของ //pkg:foo_consumer กลายเป็น //lib แทนที่จะเป็น //macro ดังนั้นการใช้งาน //pkg:foo_dependency จึงละเมิดการแสดงผลของทรัพยากร Dependency ผู้เขียน my_macro ไม่ควรส่ง visibility = ["//lib"] ไปยังการประกาศทรัพยากร Dependency เพียงเพื่อหลีกเลี่ยงรายละเอียดการใช้งานนี้

ด้วยเหตุนี้ เมื่อทรัพยากร Dependency ของเป้าหมายเป็นค่าแอตทริบิวต์ของมาโครที่ประกาศเป้าหมายด้วย เราจะตรวจสอบการแสดงผลของทรัพยากร Dependency โดยอิงตามตำแหน่งของมาโครแทนที่จะอิงตามตำแหน่งของเป้าหมายที่ใช้

ในตัวอย่างนี้ หากต้องการตรวจสอบว่า //pkg:foo_consumer มองเห็น //pkg:foo_dependency ได้หรือไม่ เราจะเห็นว่า //pkg:foo_dependency ถูกส่งเป็นอินพุตไปยังการเรียกใช้ some_library ภายใน my_macro ด้วย และตรวจสอบการแสดงผลของทรัพยากร Dependency โดยอิงตามตำแหน่งของการเรียกใช้นี้ นั่นคือ //macro แทน

กระบวนการนี้สามารถทำซ้ำแบบเรียกซ้ำได้ ตราบใดที่การประกาศเป้าหมายหรือมาโครอยู่ภายในมาโครสัญลักษณ์อื่นที่ใช้ป้ายกำกับของทรัพยากร Dependency ในแอตทริบิวต์ประเภทป้ายกำกับรายการใดรายการหนึ่ง

Finalizer

เป้าหมายที่ประกาศใน Finalizer ของกฎ (มาโครสัญลักษณ์ที่มี finalizer = True) นอกเหนือจากการมองเห็นเป้าหมายตามกฎการแสดงผลมาโครสัญลักษณ์ปกติแล้ว ยังสามารถ มองเห็นเป้าหมายทั้งหมดที่แสดงต่อแพ็กเกจของเป้าหมาย Finalizer ได้ด้วย

กล่าวอีกนัยหนึ่งคือ หากคุณย้ายข้อมูลมาโครเดิมที่อิงตาม native.existing_rules() ไปยัง Finalizer เป้าหมายที่ประกาศโดย Finalizer จะยังคงมองเห็นทรัพยากร Dependency เดิมได้

คุณสามารถกำหนดเป้าหมายที่ Finalizer ตรวจสอบได้โดยใช้ native.existing_rules() แต่ Finalizer จะใช้เป้าหมายเหล่านั้นเป็นทรัพยากร Dependency ภายใต้ระบบการมองเห็นไม่ได้ ตัวอย่างเช่น หากเป้าหมายที่กำหนดโดยมาโครไม่แสดงต่อแพ็กเกจของตัวเองหรือต่อคำจำกัดความของมาโคร Finalizer และไม่ได้มอบสิทธิ์ให้กับ Finalizer, Finalizer จะมองไม่เห็นเป้าหมายดังกล่าว อย่างไรก็ตาม โปรดทราบว่ามาโครเดิมที่อิงตาม native.existing_rules() จะมองไม่เห็นเป้าหมายดังกล่าวด้วย

การแสดงผลการโหลด

การแสดงผลการโหลด จะควบคุมว่าไฟล์ .bzl จะโหลดจากไฟล์ BUILD หรือไฟล์ .bzl อื่นๆ นอกแพ็กเกจปัจจุบันได้หรือไม่

ในทำนองเดียวกันกับการแสดงผลเป้าหมายที่ปกป้องซอร์สโค้ดซึ่งห่อหุ้มด้วยเป้าหมาย การแสดงผลการโหลดจะปกป้องตรรกะการสร้างที่ห่อหุ้มด้วยไฟล์ .bzl ตัวอย่างเช่น ผู้เขียนไฟล์ BUILD อาจต้องการแยกตัวประกอบการประกาศเป้าหมายที่ซ้ำกันบางรายการลงในมาโครในไฟล์ .bzl หากไม่มีการปกป้องการแสดงผลการโหลด ผู้เขียนอาจพบว่าผู้ทำงานร่วมกันคนอื่นๆ ในพื้นที่ทำงานเดียวกันนำมาโครไปใช้ซ้ำ ซึ่งการแก้ไขมาโครจะทำให้การสร้างของทีมอื่นหยุดทำงาน

โปรดทราบว่าไฟล์ .bzl อาจมีหรือไม่มีเป้าหมายไฟล์แหล่งที่มาที่เกี่ยวข้องก็ได้ หากมี เราไม่รับประกันว่าการแสดงผลการโหลดและการแสดงผลเป้าหมายจะตรงกัน นั่นคือ ไฟล์ BUILD เดียวกันอาจโหลดไฟล์ .bzl ได้ แต่ไม่แสดงไฟล์นั้นใน srcs ของ filegroup, หรือในทางกลับกัน ซึ่งบางครั้งอาจทำให้เกิดปัญหาสำหรับกฎที่ต้องการใช้ไฟล์ .bzl เป็นซอร์สโค้ด เช่น สำหรับการสร้างเอกสารหรือการทดสอบ

สำหรับการสร้างต้นแบบ คุณสามารถปิดใช้การบังคับใช้การแสดงผลการโหลดได้โดยตั้งค่า --check_bzl_visibility=false เช่นเดียวกับ --check_visibility=false ไม่ควรทำเช่นนี้กับโค้ดที่ส่ง

การแสดงผลการโหลดพร้อมให้บริการแล้วตั้งแต่ Bazel 6.0 เป็นต้นไป

การประกาศการแสดงผลการโหลด

หากต้องการตั้งค่าการแสดงผลการโหลดของไฟล์ .bzl ให้เรียกใช้ visibility() ฟังก์ชันจากภายในไฟล์ อาร์กิวเมนต์ของ visibility() คือรายการข้อกำหนดแพ็กเกจ เช่นเดียวกับ แอตทริบิวต์ packages ของ package_group อย่างไรก็ตาม visibility() ไม่ยอมรับข้อกำหนดแพ็กเกจเชิงลบ

การเรียกใช้ visibility() ต้องเกิดขึ้นเพียงครั้งเดียวต่อไฟล์ ที่ระดับบนสุด (ไม่อยู่ภายในฟังก์ชัน) และควรเกิดขึ้นทันทีหลังคำสั่ง load()

การแสดงผลการโหลดเริ่มต้นจะเป็นสาธารณะเสมอ ซึ่งแตกต่างจากการแสดงผลเป้าหมาย ไฟล์ที่ไม่ได้เรียกใช้ visibility() จะโหลดได้จากทุกที่ในพื้นที่ทำงานเสมอ เราขอแนะนำให้เพิ่ม visibility("private") ที่ด้านบนของไฟล์ .bzl ใหม่ใดก็ตามที่ไม่ได้มีไว้สำหรับการใช้งานภายนอกแพ็กเกจโดยเฉพาะ

ตัวอย่าง

# //mylib/internal_defs.bzl

# Available to subpackages and to mylib's tests.
visibility(["//mylib/...", "//tests/mylib/..."])

def helper(...):
    ...

# //mylib/rules.bzl

load(":internal_defs.bzl", "helper")
# Set visibility explicitly, even though public is the default.
# Note the [] can be omitted when there's only one entry.
visibility("public")

myrule = rule(
    ...
)

# //someclient/BUILD

load("//mylib:rules.bzl", "myrule")          # ok
load("//mylib:internal_defs.bzl", "helper")  # error

...

แนวทางปฏิบัติเกี่ยวกับการแสดงผลการโหลด

ส่วนนี้จะอธิบายเคล็ดลับสำหรับการจัดการการประกาศการแสดงผลการโหลด

การแยกตัวประกอบการแสดงผล

เมื่อไฟล์ .bzl หลายไฟล์ควรมีการแสดงผลเหมือนกัน การแยกตัวประกอบข้อกำหนดแพ็กเกจลงในรายการที่ใช้ร่วมกันอาจเป็นประโยชน์ ตัวอย่างเช่น

# //mylib/internal_defs.bzl

visibility("private")

clients = [
    "//foo",
    "//bar/baz/...",
    ...
]

# //mylib/feature_A.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

# //mylib/feature_B.bzl

load(":internal_defs.bzl", "clients")
visibility(clients)

...

วิธีนี้จะช่วยป้องกันการเบี่ยงเบนโดยไม่ตั้งใจระหว่างการแสดงผลของไฟล์ .bzl ต่างๆ นอกจากนี้ ยังอ่านง่ายกว่าเมื่อรายการ clients มีขนาดใหญ่

การรวมการแสดงผล

บางครั้งไฟล์ .bzl อาจต้องแสดงต่อรายการที่อนุญาตซึ่งประกอบด้วยรายการที่อนุญาตขนาดเล็กหลายรายการ ซึ่งคล้ายกับวิธีที่ a package_group สามารถรวม package_group อื่นๆ ผ่านแอตทริบิวต์ includes

สมมติว่าคุณกำลังเลิกใช้งานมาโครที่ใช้กันอย่างแพร่หลาย คุณต้องการให้มาโครแสดงเฉพาะต่อผู้ใช้ปัจจุบันและต่อแพ็กเกจที่เป็นของทีมคุณเอง คุณอาจเขียนโค้ดดังนี้

# //mylib/macros.bzl

load(":internal_defs.bzl", "our_packages")
load("//some_big_client:defs.bzl", "their_remaining_uses")

# List concatenation. Duplicates are fine.
visibility(our_packages + their_remaining_uses)

การขจัดข้อมูลซ้ำด้วยกลุ่มแพ็กเกจ

คุณไม่สามารถกำหนดการแสดงผลการโหลดในแง่ของ package_group ได้ ซึ่งแตกต่างจากการแสดงผลเป้าหมาย หากต้องการใช้รายการที่อนุญาตเดียวกันซ้ำสำหรับการแสดงผลเป้าหมายและการแสดงผลการโหลด ทางที่ดีควรย้ายรายการข้อกำหนดแพ็กเกจไปยังไฟล์ .bzl ซึ่งการประกาศทั้ง 2 ประเภทจะอ้างอิงถึงรายการนี้ได้ โดยอิงตามตัวอย่างใน การแยกตัวประกอบการแสดงผล ด้านบน คุณอาจเขียนโค้ดดังนี้

# //mylib/BUILD

load(":internal_defs", "clients")

package_group(
    name = "my_pkg_grp",
    packages = clients,
)

วิธีนี้จะใช้ได้ก็ต่อเมื่อรายการไม่มีข้อกำหนดแพ็กเกจเชิงลบ

การปกป้องสัญลักษณ์แต่ละรายการ

ระบบจะโหลดสัญลักษณ์ Starlark ใดก็ตามที่ชื่อขึ้นต้นด้วยขีดล่างจากไฟล์อื่นไม่ได้ ซึ่งทำให้สร้างสัญลักษณ์ส่วนตัวได้ง่าย แต่ไม่อนุญาตให้คุณแชร์สัญลักษณ์เหล่านี้กับไฟล์ที่เชื่อถือได้จำนวนจำกัด ในทางกลับกัน การแสดงผลการโหลดจะช่วยให้คุณควบคุมได้ว่าแพ็กเกจอื่นๆ จะมองเห็น .bzl fileของคุณได้หรือไม่ แต่ไม่อนุญาตให้คุณป้องกันไม่ให้โหลดสัญลักษณ์ที่ไม่มีขีดล่าง

โชคดีที่คุณสามารถรวมฟีเจอร์ทั้ง 2 นี้เข้าด้วยกันเพื่อควบคุมได้อย่างละเอียด

# //mylib/internal_defs.bzl

# Can't be public, because internal_helper shouldn't be exposed to the world.
visibility("private")

# Can't be underscore-prefixed, because this is
# needed by other .bzl files in mylib.
def internal_helper(...):
    ...

def public_util(...):
    ...

# //mylib/defs.bzl

load(":internal_defs", "internal_helper", _public_util="public_util")
visibility("public")

# internal_helper, as a loaded symbol, is available for use in this file but
# can't be imported by clients who load this file.
...

# Re-export public_util from this file by assigning it to a global variable.
# We needed to import it under a different name ("_public_util") in order for
# this assignment to be legal.
public_util = _public_util

bzl-visibility Buildifier Lint

มี Buildifier lint ที่แสดงคำเตือนหากผู้ใช้โหลดไฟล์จากไดเรกทอรีที่ชื่อ internal หรือ private ในกรณีที่ไฟล์ของผู้ใช้ไม่ได้อยู่ภายใต้ไดเรกทอรีระดับบนของ ไดเรกทอรีนั้น เครื่องมือวิเคราะห์ซอร์สโค้ดนี้มีมาก่อนฟีเจอร์การแสดงผลการโหลดและไม่จำเป็นในพื้นที่ทำงานที่ไฟล์ .bzl ประกาศการแสดงผล