ระดับการเข้าถึง

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

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

ระดับการเข้าถึงเป้าหมาย

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

เป้าหมาย A จะมองเห็นเป้าหมาย B ได้หากอยู่ในแพ็กเกจเดียวกัน หรือหาก A ให้สิทธิ์เข้าถึงแพ็กเกจของ B ดังนั้น แพ็กเกจคือหน่วยของรายละเอียดในการตัดสินใจว่าจะอนุญาตการเข้าถึงหรือไม่ หาก B ขึ้นอยู่กับ A แต่ B มองไม่เห็น 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" และ "//foo/bar/..." จะแทนที่รูปแบบ "//foo/bar:__pkg__" และ "//foo/bar:__subpackages__" ตามลำดับ ในทำนองเดียวกัน "//visibility:public" และ "//visibility:private" เป็นเพียง "public" และ "private"

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

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

ระดับการเข้าถึงเป้าหมายของกฎ

ระดับการเข้าถึงของเป้าหมายกฎมีดังนี้

1. ค่าของแอตทริบิวต์ visibility หากมีการตั้งค่า หรืออื่นๆ

2. ค่าของอาร์กิวเมนต์ default_visibility ของคำสั่ง package ในไฟล์ BUILD ของเป้าหมาย หากมีการประกาศดังกล่าว หรือ

3. //visibility:private

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

ตัวอย่าง

ไฟล์ //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 เมื่อไม่มีการส่งvisibility อาร์กิวเมนต์ไปยัง exports_files ระบบจะทําให้ระดับการเข้าถึงเป็นแบบสาธารณะ คุณใช้ exports_files เพื่อลบล้างระดับการแชร์ของไฟล์ที่สร้างขึ้นไม่ได้

สําหรับเป้าหมายไฟล์ต้นฉบับที่ไม่ได้ปรากฏในการเรียกใช้ exports_files ระดับการมองเห็นจะขึ้นอยู่กับค่าของ Flag --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 โดยนัย

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

ปัจจุบันทรัพยากร Dependency แบบโดยนัยต่างๆ จะเหมือนกับทรัพยากร Dependency อื่นๆ เพื่อจุดประสงค์ด้านการมองเห็น ซึ่งหมายความว่าเป้าหมายที่ขึ้นอยู่กับ (เช่น คอมไพเลอร์ C++) จะต้องแสดงในทุกอินสแตนซ์ของกฎ ในทางปฏิบัติ มักหมายความว่าเป้าหมายต้องเข้าถึงได้แบบสาธารณะ

คุณเปลี่ยนลักษณะการทำงานนี้ได้โดยการตั้งค่า --incompatible_visibility_private_attributes_at_definition เมื่อเปิดใช้ เป้าหมายที่เป็นปัญหาจะต้องปรากฏต่อกฎที่ประกาศการขึ้นต่อกันโดยปริยายเท่านั้น กล่าวคือ แพ็กเกจที่มีไฟล์ .bzl ที่กําหนดกฎต้องมองเห็นไฟล์นั้น ในตัวอย่างของเรา คอมไพเลอร์ C++ อาจเป็นแบบส่วนตัวได้ตราบใดที่อยู่ในแพ็กเกจเดียวกับคำจำกัดความของกฎ cc_library

โหลดระดับการมองเห็น

ระดับการมองเห็นการโหลดจะควบคุมว่าระบบจะโหลดไฟล์ .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 อาจต้องปรากฏในรายการที่อนุญาตซึ่งประกอบด้วยรายการที่อนุญาตขนาดเล็กหลายรายการ ซึ่งคล้ายกับวิธีที่ 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

Lint บิลด์การมองเห็น bzl

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