Chương trình đăng ký tham gia sự kiện BazelCon 2024 đã bắt đầu!

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

Chế độ hiển thị

Báo cáo vấn đề Xem nguồn Hằng đêm · 7,4 của Google. 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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ị 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ề cách triển khai 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 phát triển. Bạn cũng có thể sử dụng chế độ hiển thị khi ngừng sử dụng 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.

Mức độ 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 bên trong một thuộc tính như deps.

A mục tiêu 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ị của mức độ 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à các gói con, hãy xem Khái niệm và thuật ngữ.

Để tạo bản mô hình, 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 làm việc này cho mục đích sử dụng 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 chế độ hiển thị của mục tiêu.

Thông số kỹ thuật về chế độ hiển thị

Tất cả mục tiêu quy tắc đều có thuộc tính visibility chứa 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, 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. (Có thể không kết hợp được 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. (Không thể kết hợp với bất kỳ sản phẩm nào khác specification.)
"//foo/bar:__pkg__": Cấp quyền truy cập vào //foo/bar (nhưng không phải các gói con của gói này).
"//foo/bar:__subpackages__": Cấp quyền truy cập //foo/bar và tất cả gói con trực tiếp và gián tiếp.
"//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 cho chỉ định các gói. Trong một nhóm gói, biểu mẫu "//foo/bar:__pkg__" và "//foo/bar:__subpackages__" lần lượt là đượ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ì đối tượng này có thể dùng đối tượng này là một phần của cây nguồn //some/package/..., cũng như các mục tiêu được xác định trong //tests/BUILD, nhưng 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 cho cùng một nhóm hãy sử dụng package_group thay vì lặp lại danh sách trong mỗi gói thuộc tính visibility của mục tiêu. Điều này giúp tăng khả năng đọc và ngăn các danh sách bị mất đồng bộ hoá.

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 khác
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; nếu không
//visibility:private.

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

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

Chế độ hiển thị mục tiêu 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ó visibility được truyền đến exports_files, nó sẽ làm cho chế độ hiển thị công khai. Không được 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ị 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ẽ á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 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 riêng tư.

Phương pháp hay nhất: Khi có thể, hãy 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, gói tệp này trong một mục tiêu java_library không riêng tư. Nhìn chung, 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 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 bật tính năng kiểm tra chế độ hiển thị cho các mục tiêu này. Để hỗ trợ quá trình di chuyển, tính năng này cũng khiến mọi config_setting không chỉ định visibility sẽ đượ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ư, chỉ giống như mọi mục tiêu quy tắc khác. Trang web này sẽ không hoạt động nếu Bạn chưa đặt --incompatible_enforce_config_setting_visibility.

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

Hiện tại, đối với mục đích hiển thị, các phần phụ thuộc ngầm ẩn 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 bị phụ thuộc vào (chẳng hạn như trình biên dịch C++) phải hiển thị với mọi bản sao của quy tắc. Trong thực tế, thường có nghĩa là mục tiêu phải được 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 nó là ngầm ẩn phần phụ thuộc. Tức là gói chứa tệp .bzl trong đó quy tắc được xác định phải hiển thị quy tắc đó. Trong ví dụ của chúng ta, trình biên dịch C++ có thể là riêng tư miễn là tệp này nằm trong cùng gói như định nghĩa của cc_library quy tắc.

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 BUILD hoặc .bzl.

Tương tự như cách chế độ hiển thị mục tiêu bảo vệ mã nguồn được đóng gói bằng các mục tiêu, chế độ hiển thị tải sẽ bảo vệ logic bản dựng được đóng gói bằng các tệp .bzl. Ví dụ: tác giả tệp BUILD có thể muốn tính đến một số yếu tố lặp lại định nghĩa mục tiêu thành macro trong tệp .bzl. Nếu không có tính năng bảo vệ chế độ 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 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ó mục tiêu tệp nguồn tương ứng. Nếu có, không có gì đảm bảo rằng chế độ hiển thị tải và chế độ hiển thị mục tiêu trùng khớp với nhau. 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ố cho các quy tắc muốn sử dụng .bzl làm mã nguồn, chẳng hạn như để tạo hoặc kiểm thử tài liệu.

Để tạo bản mô hình, 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. Cũng như --check_visibility=false, bạn không nên làm điều này cho 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 phương thức visibility() từ trong tệp. Đối số cho 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 gói phủ định thông số kỹ thuật.

Lệnh gọi đến visibility() chỉ được xảy ra 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âu lệnh load().

Không giống như chế độ hiển thị mục tiêu, chế độ hiển thị của tệp tải mặc định luôn là công khai. Các tệp không gọi visibility() luôn có thể tải được từ bất kỳ đâu 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

...

Phương pháp hiển thị tải

Phần này mô tả các mẹo để quản lý thông tin 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 tránh tình trạng sai lệch vô tình giữa các tệp .bzl khác nhau hiển thị. Việc này cũng dễ đọc hơn khi danh sách clients lớn.

Soạn chế độ hiển thị

Đôi khi, tệp .bzl có thể cần hiển thị với 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 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 không dùng macro được sử dụng rộng rãi. Bạn muốn phòng trưng bày chỉ hiển thị cho người dùng hiện tại và cho 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 bằng 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 theo package_group. Nếu bạn muốn sử dụng lại cùng một danh sách cho phép cho cả hai mục tiêu khả năng hiển thị và khả năng hiển thị tải, tốt nhất bạn nên di chuyển danh sách gói vào tệp .bzl, trong đó cả hai loại nội dung khai báo đều có thể tham chiếu đến nó. Dựa trên ví dụ trong phần Tính đến chế độ 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 thông số kỹ thuật gói phủ định nào.

Bảo vệ các biểu tượng riêng lẻ

Bất kỳ ký hiệu Starlark nào có tên bắt đầu bằng dấu gạch dưới đều không thể tải từ một tệp khác. Điều này giúp dễ dàng tạo các biểu tượng riêng tư, nhưng không cho phép bạn chia sẻ các biểu tượng này với một nhóm giới hạn 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 nào khác có thể thấy .bzl file của bạn, nhưng không cho phép bạn ngăn tải bất kỳ ký hiệu nào 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ó đượ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 bzl-visibility Buildifier

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