Mức độ hiển thị

Báo cáo vấn đề Xem nguồn

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Trang này trình bày 2 hệ thống hiển thị của Bazel: khả năng hiển thị mục tiêu và khả năng hiển thị khi tải.

Cả hai loại chế độ hiển thị này đều giúp các nhà phát triển khác phân biệt giữa API công khai của thư viện và thông tin chi tiết về việc triển khai, đồng thời giúp thực thi cấu trúc khi không gian làm việc của bạn phát triển. Bạn cũng có thể sử dụng khả năng hiển thị khi không dùng nữa một API công khai để cho phép người dùng hiện tại trong khi từ chối người dùng mới.

Chế độ hiển thị mục tiêu

Chế độ hiển thị mục tiêu kiểm soát những đối tượng có thể phụ thuộc vào mục tiêu của bạn, tức là những đối tượng có thể sử dụng nhãn của mục tiêu trong một thuộc tính như deps.

Một mục tiêu A sẽ hiển thị cho một mục tiêu B nếu chúng nằm trong cùng một gói hoặc nếu A cấp quyền hiển thị cho gói của B. Do đó, các gói là đơn vị chi tiết để quyết định có cho phép truy cập hay không. Nếu B phụ thuộc vào A nhưng A không hiển thị với B, thì mọi nỗ lực tạo B đều không thành công trong quá trình phân tích.

Xin lưu ý rằng việc cấp quyền hiển thị cho một gói không tự động cấp quyền hiển thị cho các gói con của gói đó. Để biết thêm thông tin chi tiết về gói và gói con, hãy xem phần Các khái niệm và thuật ngữ.

Để tạo mẫu, bạn có thể tắt chế độ thực thi khả năng hiển thị mục tiêu bằng cách đặt cờ --check_visibility=false. Bạn không nên làm việc này cho mục đích sử dụng trong môi trường phát hành trong mã đã gửi.

Cách chính để kiểm soát chế độ hiển thị là dùng thuộc tính visibility trên các mục tiêu của quy tắc. Phần này mô tả định dạng của thuộc tính này và cách xác định khả năng hiển thị của mục tiêu.

Quy cách về khả năng hiển thị

Tất cả mục tiêu của quy tắc đều có thuộc tính visibility nhận danh sách nhãn. Mỗi nhãn có một trong các dạng sau. Ngoại trừ biểu mẫu cuối cùng, đây chỉ là các phần giữ chỗ cú pháp không tương ứng với bất kỳ mục tiêu thực tế nào.

• "//visibility:public": Cấp quyền truy cập vào tất cả các gói. (Không được kết hợp với bất kỳ quy cách nào khác.)

• "//visibility:private": Không cấp thêm quyền truy cập nào; chỉ những mục tiêu trong gói này mới có thể sử dụng mục tiêu này. (Không được kết hợp với bất kỳ quy cách nào khác.)

• "//foo/bar:__pkg__": Cấp quyền truy cập vào //foo/bar (nhưng không cấp quyền truy cập vào các gói con của //foo/bar).

• "//foo/bar:__subpackages__": Cấp quyền truy cập //foo/bar và tất cả các gói con trực tiếp và gián tiếp của gói này.

• "//some_pkg:my_package_group": Cấp quyền truy cập vào tất cả các gói thuộc package_group đã cho.

  • Nhóm gói sử dụng cú pháp khác để chỉ định các gói. Trong một nhóm gói, các biểu mẫu "//foo/bar:__pkg__" và "//foo/bar:__subpackages__" lần lượt được thay thế bằng "//foo/bar" và "//foo/bar/...". Tương tự, "//visibility:public" và "//visibility:private" chỉ là "public" và "private".

Ví dụ: nếu //some/package:mytarget có visibility được đặt thành [":__subpackages__", "//tests:__pkg__"], thì mọi mục tiêu thuộc cây nguồn //some/package/... cũng như các mục tiêu được xác định trong //tests/BUILD đều có thể sử dụng mục tiêu này, nhưng các mục tiêu được xác định trong //tests/integration/BUILD thì không.

Cách hay nhất: Để hiển thị một số mục tiêu cho cùng một nhóm gói, hãy sử dụng package_group thay vì lặp lại danh sách trong thuộc tính visibility của mỗi mục tiêu. Điều này giúp tăng khả năng đọc và ngăn danh sách bị lệch.

Lưu ý: Thuộc tính visibility có thể không chỉ định các mục tiêu không phải package_group. Thao tác này sẽ kích hoạt lỗi "Nhãn không tham chiếu đến một nhóm gói" hoặc "Vòng lặp trong biểu đồ phần phụ thuộc".

Khả năng hiển thị mục tiêu của quy tắc

Chế độ hiển thị của mục tiêu theo quy tắc là:

1. Giá trị của thuộc tính visibility (nếu được đặt); hoặc

2. Giá trị của đối số default_visibility của câu lệnh package trong tệp BUILD của mục tiêu, nếu có khai báo như vậy; hoặc

3. //visibility:private.

Phương pháp hay nhất: Tránh đặt default_visibility thành công khai. Điều này có thể thuận tiện cho việc tạo mẫu hoặc trong các cơ sở mã nhỏ, nhưng nguy cơ vô tình tạo ra các mục tiêu công khai sẽ tăng lên khi cơ sở mã phát triển. Bạn nên chỉ rõ những mục tiêu nào thuộc giao diện công khai của một gói.

Ví dụ:

Tệp //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"],
)

Tệp //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",
    ],
)

Chế độ hiển thị mục tiêu của tệp được tạo

Mục tiêu của tệp được tạo có cùng chế độ hiển thị với mục tiêu của quy tắc tạo ra tệp đó.

Chế độ hiển thị của tệp nguồn

Bạn có thể đặt chế độ hiển thị của mục tiêu tệp nguồn một cách rõ ràng bằng cách gọi exports_files. Khi không có đối số visibility nào được truyền đến exports_files, đối số này sẽ đặt chế độ hiển thị thành công khai. Bạn không thể dùng exports_files để ghi đè chế độ hiển thị của một tệp đã tạo.

Đối với những đích đến của tệp nguồn không xuất hiện trong lệnh gọi đến exports_files, khả năng hiển thị phụ thuộc vào giá trị của cờ --incompatible_no_implicit_file_export:

• Nếu bạn đặt cờ này, chế độ hiển thị sẽ là riêng tư.

• Nếu không, hành vi cũ sẽ được áp dụng: Chế độ hiển thị giống với default_visibility của tệp BUILD hoặc ở chế độ riêng tư nếu bạn không chỉ định chế độ hiển thị mặc định.

Tránh dựa vào hành vi cũ. Luôn viết một exports_fileskhai báo bất cứ khi nào đích của tệp nguồn cần có chế độ hiển thị không riêng tư.

Phương pháp hay nhất: Khi có thể, hãy ưu tiên hiển thị mục tiêu của quy tắc thay vì tệp nguồn. Ví dụ: thay vì gọi exports_files trên tệp .java, hãy bao bọc tệp trong một mục tiêu java_library không riêng tư. Thông thường, các mục tiêu quy tắc chỉ nên tham chiếu trực tiếp đến các tệp nguồn nằm trong cùng một gói.

Ví dụ:

Tệp //frobber/data/BUILD:

exports_files(["readme.txt"])

Tệp //frobber/bin/BUILD:

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

Chế độ hiển thị chế độ cài đặt cấu hình

Trước đây, Bazel không thực thi khả năng hiển thị cho các mục tiêu config_setting được tham chiếu trong khoá của select(). Có 2 cờ để xoá hành vi cũ này:

• --incompatible_enforce_config_setting_visibility cho phép kiểm tra khả năng hiển thị cho các mục tiêu này. Để hỗ trợ việc di chuyển, thao tác này cũng khiến mọi config_setting không chỉ định visibility đều được coi là công khai (bất kể default_visibility ở cấp gói).

• --incompatible_config_setting_private_default_visibility khiến config_setting không chỉ định visibility phải tuân theo default_visibility của gói và quay lại chế độ hiển thị riêng tư, giống như mọi mục tiêu quy tắc khác. Đây là một thao tác không có hiệu lực nếu --incompatible_enforce_config_setting_visibility chưa được đặt.

Tránh dựa vào hành vi cũ. Mọi config_setting dự định được dùng bên ngoài gói hiện tại đều phải có visibility rõ ràng, nếu gói đó chưa chỉ định default_visibility phù hợp.

Chế độ hiển thị mục tiêu của nhóm gói

Mục tiêu package_group không có thuộc tính visibility. Chúng luôn hiển thị công khai.

Mức hiển thị của các phần phụ thuộc ngầm ẩn

Một số quy tắc có phần phụ thuộc ngầm – những phần phụ thuộc không được nêu rõ trong tệp BUILD nhưng vốn có trong mọi phiên bản của quy tắc đó. Ví dụ: quy tắc cc_library có thể tạo một phần phụ thuộc ngầm từ mỗi mục tiêu quy tắc của nó đến một mục tiêu thực thi đại diện cho trình biên dịch C++.

Hiện tại, vì mục đích hiển thị, các phần phụ thuộc ngầm này được coi như mọi phần phụ thuộc khác. Điều này có nghĩa là mục tiêu đang được phụ thuộc (chẳng hạn như trình biên dịch C++ của chúng tôi) phải hiển thị cho mọi phiên bản của quy tắc. Trên thực tế, điều này thường có nghĩa là mục tiêu phải có chế độ hiển thị công khai.

Bạn có thể thay đổi hành vi này bằng cách đặt --incompatible_visibility_private_attributes_at_definition. Khi được bật, mục tiêu được đề cập chỉ cần hiển thị cho quy tắc khai báo mục tiêu đó là một phần phụ thuộc ngầm. Tức là tệp này phải hiển thị cho gói chứa tệp .bzl mà trong đó quy tắc được xác định. Trong ví dụ của chúng ta, trình biên dịch C++ có thể là riêng tư miễn là trình biên dịch đó nằm trong cùng một gói với định nghĩa của quy tắc cc_library.

Chế độ hiển thị tải

Khả năng hiển thị khi tải kiểm soát việc một tệp .bzl có thể được tải từ các tệp BUILD hoặc .bzl khác hay không.

Tương tự như cách chế độ hiển thị mục tiêu bảo vệ mã nguồn được đóng gói theo mục tiêu, chế độ hiển thị tải bảo vệ logic xây dựng được đóng gói theo các tệp .bzl. Ví dụ: tác giả tệp BUILD có thể muốn đưa một số định nghĩa mục tiêu lặp lại vào một macro trong tệp .bzl. Nếu không có tính năng bảo vệ khả năng hiển thị tải, họ có thể thấy macro của mình bị những cộng tác viên khác sử dụng lại trong cùng một không gian làm việc, do đó, việc sửa đổi macro sẽ làm hỏng bản dựng của các nhóm khác.

Xin lưu ý rằng tệp .bzl có thể có hoặc không có đích đến là tệp nguồn tương ứng. Nếu có, thì không có gì đảm bảo rằng khả năng hiển thị tải và khả năng hiển thị mục tiêu sẽ trùng khớp. Tức là cùng một tệp BUILD có thể tải tệp .bzl nhưng không liệt kê tệp đó trong srcs của filegroup hoặc ngược lại. Đôi khi, điều này có thể gây ra vấn đề cho các quy tắc muốn sử dụng tệp .bzl làm mã nguồn, chẳng hạn như để tạo tài liệu hoặc kiểm thử.

Để tạo mẫu, bạn có thể tắt tính năng thực thi chế độ hiển thị tải bằng cách đặt --check_bzl_visibility=false. Tương tự như --check_visibility=false, bạn không nên làm việc này đối với mã đã gửi.

Chế độ hiển thị tải có sẵn từ Bazel 6.0.

Khai báo chế độ hiển thị tải

Để đặt chế độ hiển thị tải của tệp .bzl, hãy gọi hàm visibility() trong tệp. Đối số cho visibility() là danh sách các quy cách gói, giống như thuộc tính packages của package_group. Tuy nhiên, visibility() không chấp nhận các quy cách gói âm.

Bạn chỉ được gọi visibility() một lần cho mỗi tệp, ở cấp cao nhất (không nằm trong một hàm) và tốt nhất là ngay sau các câu lệnh load().

Không giống như chế độ hiển thị mục tiêu, chế độ hiển thị tải mặc định luôn ở chế độ công khai. Các tệp không gọi visibility() luôn có thể tải được từ mọi nơi trong không gian làm việc. Bạn nên thêm visibility("private") vào đầu mọi tệp .bzl mới không dành riêng cho việc sử dụng bên ngoài gói.

Ví dụ:

# //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

...

Các phương pháp hay nhất về khả năng hiển thị khi tải

Phần này mô tả các mẹo để quản lý khai báo khả năng hiển thị tải.

Phân tích khả năng hiển thị

Khi nhiều tệp .bzl phải có cùng khả năng hiển thị, bạn có thể phân tích các quy cách gói của tệp đó thành một danh sách chung. Ví dụ:

# //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)

...

Điều này giúp ngăn chặn tình trạng lệch lạc vô tình giữa khả năng hiển thị của các tệp .bzl. Danh sách clients cũng dễ đọc hơn khi có kích thước lớn.

Chế độ hiển thị thành phần

Đôi khi, tệp .bzl có thể cần hiển thị cho một danh sách cho phép bao gồm nhiều danh sách cho phép nhỏ hơn. Điều này tương tự như cách một package_group có thể kết hợp các package_group khác thông qua thuộc tính includes.

Giả sử bạn đang ngừng sử dụng một macro được dùng rộng rãi. Bạn muốn chỉ những người dùng hiện tại và các gói thuộc quyền sở hữu của nhóm bạn mới nhìn thấy được. Bạn có thể viết:

# //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)

Loại bỏ các mục trùng lặp bằng nhóm gói

Không giống như khả năng hiển thị mục tiêu, bạn không thể xác định khả năng hiển thị tải theo package_group. Nếu muốn dùng lại cùng một danh sách cho phép cho cả chế độ hiển thị mục tiêu và chế độ hiển thị khi tải, tốt nhất là bạn nên di chuyển danh sách chỉ định gói vào một tệp .bzl, nơi cả hai loại khai báo đều có thể tham chiếu đến danh sách đó. Dựa trên ví dụ trong phần Tính toán khả năng hiển thị ở trên, bạn có thể viết:

# //mylib/BUILD

load(":internal_defs", "clients")

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

Điều này chỉ hoạt động nếu danh sách không chứa bất kỳ thông số kỹ thuật nào về gói phủ định.

Bảo vệ các ký hiệu riêng lẻ

Bạn không thể tải bất kỳ biểu tượng Starlark nào có tên bắt đầu bằng dấu gạch dưới từ một tệp khác. Điều này giúp bạn dễ dàng tạo các ký hiệu riêng tư, nhưng không cho phép bạn chia sẻ các ký hiệu này với một số ít tệp đáng tin cậy. Mặt khác, chế độ hiển thị tải cho phép bạn kiểm soát những gói khác có thể thấy .bzl file của bạn, nhưng không cho phép bạn ngăn bất kỳ biểu tượng không có dấu gạch dưới nào được tải.

May mắn thay, bạn có thể kết hợp hai tính năng này để kiểm soát chi tiết.

# //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

Có một Buildifier lint đưa ra cảnh báo nếu người dùng tải một tệp từ thư mục có tên là internal hoặc private, khi tệp của người dùng không nằm bên dưới thư mục mẹ của thư mục đó. Lint này có trước tính năng hiển thị tải và không cần thiết trong các không gian làm việc mà tệp .bzl khai báo khả năng hiển thị.