Để xem tài liệu về bản phát hành ổn định, vui lòng sử dụng trình đơn thả xuống "Tài liệu được tạo phiên bản". Chế độ xem mặc định phản ánh phiên bản mới nhất ở HEAD.

Trang này được dịch bởi Cloud Translation API.

Chế độ hiển thị

Báo cáo sự cố Xem nguồn

Trang này đề cập đến hai hệ thống hiển thị của Bazel: chế độ hiển thị mục tiêu và chế độ hiển thị tải.

Cả hai loại chế độ hiển thị đề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 triển khai chi tiết của API đó, đồng thời giúp thực thi cấu trúc khi không gian làm việc của bạn mở rộng. Bạn cũng có thể sử dụng chế độ hiển thị khi ngừng sử dụng một API công khai để cho phép người dùng hiện tại trong khi từ chối các API mới.

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

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

A mục tiêu sẽ hiển thị với B mục tiêu 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 đó, gói là đơn vị 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 sẽ thất bại trong quá trình phân tích.

Lưu ý rằng việc cấp chế độ hiển thị cho một gói không tự 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 Khái niệm và thuật ngữ.

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

Cách chính để kiểm soát chế độ hiển thị là sử dụng thuộc tính visibility trên các mục tiêu 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ề chế độ hiển thị

Tất cả các mục tiêu quy tắc đều có thuộc tính visibility nhận danh sách các 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à 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. (Có thể 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ỉ các mục tiêu trong gói này mới có thể sử dụng mục tiêu này. (Có thể 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 cho các gói con của nó).
"//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.
- Các nhóm gói sử dụng một cú pháp khác để chỉ định 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ục tiêu này có thể được sử dụng bởi bất kỳ mục tiêu nào thuộc cây nguồn //some/package/..., cũng như các mục tiêu được xác định trong //tests/BUILD, chứ không phải bởi các mục tiêu được xác định trong //tests/integration/BUILD.

Phương pháp hay nhất: Để hiển thị nhiều mục tiêu trên 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 từng mục tiêu. Điều này giúp tăng khả năng đọc và ngăn danh sách bị đồng bộ hoá.

Phương pháp hay nhất: Khi cấp quyền hiển thị cho dự án của một nhóm khác, hãy ưu tiên __subpackages__ hơn __pkg__ để tránh tình trạng rời bỏ chế độ hiển thị không cần thiết khi dự án phát triển và thêm các gói con mới.

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

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

Giá trị của thuộc tính visibility, nếu được đặt; hoặc nếu không
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ó nội dung khai báo như vậy; hoặc nếu không,
//visibility:private.

Phương pháp hay nhất: Tránh đặt default_visibility ở chế độ công khai. Việc này có thể thuận tiện cho việc tạo nguyên mẫu hoặc trong cơ sở mã nhỏ, nhưng nguy cơ vô tình tạo các mục tiêu công khai sẽ tăng lên khi cơ sở mã tăng trưởng. Bạn nên thông báo rõ ràng về những mục tiêu nằm trong giao diện công khai của 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 đã tạo

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

Chế độ hiển thị của mục tiêu tệp nguồn

Bạn có thể thiết lập rõ ràng chế độ hiển thị của đích tệp nguồn bằng cách gọi exports_files. Khi không có đối số visibility nào được chuyển vào exports_files, chế độ hiển thị sẽ hiển thị công khai. Bạn không thể dùng exports_files để ghi đè chế độ hiển thị của tệp đã tạo.

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

Nếu cờ này được đặt thì chế độ hiển thị sẽ là riêng tư.
Ngược lại, hành vi cũ sẽ được áp dụng: Chế độ hiển thị sẽ giống như 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 nội dung khai báo exports_files bất cứ khi nào mục tiêu tệp nguồn cần chế độ hiển thị không ở chế độ 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 quy tắc thay vì tệp nguồn. Ví dụ: thay vì gọi exports_files trên tệp .java, hãy gói tệp này trong một mục tiêu java_library không riêng tư. Nhìn chung, các mục tiêu quy tắc chỉ nên tham chiếu trực tiếp 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 chưa thực thi chế độ hiển thị cho các mục tiêu config_setting được tham chiếu trong các khoá của select(). Có hai cờ để xoá hành vi cũ này:

--incompatible_enforce_config_setting_visibility cho phép kiểm tra chế độ hiển thị cho các mục tiêu này. Để hỗ trợ quá trình di chuyể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 để tuân theo default_visibility của gói và dự phòng chế độ hiển thị riêng tư, giống như mọi mục tiêu quy tắc khác. Thuộc tính này sẽ không hoạt động nếu bạn không đặt --incompatible_enforce_config_setting_visibility.

Tránh dựa vào hành vi cũ. Mọi config_setting muốn sử 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

Các mục tiêu package_group không có thuộc tính visibility. Chúng luôn được hiển thị công khai.

Chế độ 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 ẩn – các phần phụ thuộc không được viết trong tệp BUILD nhưng vốn có trong mọi thực thể của quy tắc đó. Ví dụ: quy tắc cc_library có thể tạo phần phụ thuộc ngầm ẩn từ mỗi quy tắc nhắm mục tiêu đến mục tiêu có thể thực thi đại diện cho trình biên dịch C++.

Chế độ hiển thị của một phần phụ thuộc ngầm ẩn như vậy được kiểm tra đối với gói chứa tệp .bzl mà trong đó quy tắc (hoặc khía cạnh) được xác định. Trong ví dụ của chúng tôi, trình biên dịch C++ có thể ở chế độ 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. Ở dạng phương án dự phòng, nếu phần phụ thuộc ngầm ẩn không hiển thị trong định nghĩa, thì phần phụ thuộc đó sẽ được kiểm tra theo mục tiêu cc_library.

Nếu bạn muốn hạn chế việc sử dụng quy tắc cho một số gói nhất định, hãy dùng chế độ hiển thị tải.

Tải chế độ hiển thị

Chế độ hiển thị tải kiểm soát việc tệp .bzl có thể được tải từ các tệp BUILD hoặc .bzl khác ngoài gói hiện tại hay không.

Tương tự như chế độ hiển thị mục tiêu bảo vệ mã nguồn được mục tiêu đóng gói, chế độ hiển thị tải bảo vệ logic bản dựng được các tệp .bzl đóng gói. 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 macro trong tệp .bzl. Nếu không có biện pháp bảo vệ khả năng hiển thị tải, họ có thể thấy macro của mình được các 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 các 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 tệp nguồn tương ứng. Nếu có, không có nghĩa là chế độ hiển thị tải và chế độ 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ều này đôi khi có thể gây ra sự cố đối với những quy tắc muốn sử dụng tệp .bzl làm mã nguồn, chẳng hạn như để tạo hoặc kiểm thử tài liệu.

Để tạo nguyên 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ư với --check_visibility=false, bạn không nên thực hiện việc này đối với mã đã gửi.

Chế độ hiển thị tải có sẵn kể 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() từ trong tệp. Đối số đối với visibility() là danh sách thông số kỹ thuật của gói, giống như thuộc tính packages của package_group. Tuy nhiên, visibility() không chấp nhận quy cách gói phủ định.

Lệnh gọi đến visibility() chỉ được thực hiện một lần cho mỗi tệp, ở cấp cao nhất (không phải bên 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 công khai. Các tệp không gọi visibility() luôn 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 nhằm mục đích sử dụng riê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 về chế độ hiển thị tải

Phần này mô tả các mẹo quản lý nội dung khai báo về chế độ hiển thị tải.

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

Khi nhiều tệp .bzl có cùng chế độ hiển thị, bạn nên đưa thông số kỹ thuật của gói vào 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 sai lệch ngẫu nhiên giữa chế độ hiển thị của nhiều tệp .bzl. Mã này cũng dễ đọc hơn khi danh sách clients lớn.

Chế độ hiển thị khi kết hợp

Đôi khi, tệp .bzl có thể cần hiển thị với danh sách cho phép gồm nhiều danh sách cho phép nhỏ hơn. Điều này tương tự như việc 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 sắp ngừng sử dụng macro được sử dụng rộng rãi. Bạn chỉ muốn hiển thị hồ sơ này với người dùng hiện tại và các gói do nhóm của bạn sở hữu. 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ỏ trùng lặp với các nhóm gói

Không giống như chế độ hiển thị mục tiêu, bạn không thể xác định chế độ hiển thị tải về package_group. Nếu muốn sử 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ị tải, tốt nhất bạn nên chuyển danh sách thông số gói vào một tệp .bzl mà cả hai loại nội dung khai báo đều có thể tham chiếu đến tệp đó. Dựa trên ví dụ trong phần Phân tích 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,
)

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

Bảo vệ từng biểu tượng

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 biểu tượng riêng tư nhưng không cho phép chia sẻ các biểu tượng này với một nhóm hạn chế các 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ể nhìn thấy .bzl file của bạn, nhưng không cho phép bạn ngăn việc tải mọi biểu tượng không có dấu gạch dưới.

May mắn là bạn có thể kết hợp hai tính năng này để có quyền 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

Tìm lỗi mã nguồn cho trình tạo khả năng hiển thị bzl

Có một Trình tìm lỗi mã nguồn của trình tạo đư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 internal hoặc private, trong khi tệp của người dùng không nằm trong thư mục mẹ của thư mục đó. Trình tìm lỗi mã nguồn này ra trước tính năng hiển thị tải và không cần thiết trong những không gian làm việc nơi các tệp .bzl khai báo chế độ hiển thị.