Hàm

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

Nội dung

• gói
• package_group
• exports_files
• toàn cầu
• chọn
• gói con

gói hàng

package(default_deprecation, default_package_metadata, default_testonly, default_visibility, features)

Hàm này khai báo siêu dữ liệu áp dụng cho mọi quy tắc trong gói. Mã này được sử dụng tối đa một lần trong gói (tệp BUILD).

Đối với phần đối chiếu khai báo siêu dữ liệu áp dụng cho mọi quy tắc trong toàn bộ kho lưu trữ, hãy dùng hàm repo() trong tệp REPO.bazel ở gốc kho lưu trữ. Hàm repo() nhận chính xác các đối số giống như package().

Hàm package() phải được gọi ngay sau tất cả các câu lệnh tải() ở đầu tệp, trước bất kỳ quy tắc nào.

Đối số

Thuộc tính	Nội dung mô tả
default_applicable_licenses	Bí danh của default_package_metadata.
default_visibility	Danh sách nhãn; mặc định là [] Chế độ hiển thị mặc định của các quy tắc trong gói này. Mọi quy tắc trong gói này đều có chế độ hiển thị được chỉ định trong thuộc tính này, trừ phi có quy định khác trong thuộc tính visibility của quy tắc. Để biết thông tin chi tiết về cú pháp của thuộc tính này, hãy xem tài liệu về chế độ hiển thị. Chế độ hiển thị mặc định của gói không áp dụng cho exports_files, là công khai theo mặc định.
default_deprecation	Chuỗi; giá trị mặc định là "" Đặt thông báo deprecation mặc định cho tất cả quy tắc trong gói này.
default_package_metadata	Danh sách nhãn; mặc định là [] Đặt danh sách mục tiêu siêu dữ liệu mặc định áp dụng cho tất cả các mục tiêu khác trong gói. Đây thường là các mục tiêu liên quan đến việc khai báo giấy phép và gói OSS. Hãy xem rules_license để biết ví dụ.
default_testonly	Boolean; giá trị mặc định là False ngoại trừ như có ghi chú Đặt thuộc tính testonly mặc định cho tất cả các quy tắc trong gói này. Trong các gói thuộc javatests, giá trị mặc định là True.
features	Chuỗi danh sách; mặc định là [] Đặt nhiều cờ ảnh hưởng đến ngữ nghĩa của tệp BUILD này. Tính năng này chủ yếu được những người làm việc trên hệ thống xây dựng sử dụng để gắn thẻ các gói cần xử lý đặc biệt. Không sử dụng thuộc tính này trừ phi có người làm việc trên hệ thống xây dựng yêu cầu rõ ràng.

Ví dụ

Phần khai báo dưới đây khai báo rằng các quy tắc trong gói này chỉ hiển thị cho các thành viên của nhóm gói //foo:target. Nội dung khai báo riêng lẻ về chế độ hiển thị trên một quy tắc (nếu có) sẽ ghi đè quy cách này.

package(default_visibility = ["//foo:target"])

package_group

package_group(name, packages, includes)

Hàm này xác định một tập hợp các gói và liên kết nhãn với tập hợp đó. Bạn có thể tham chiếu nhãn trong các thuộc tính visibility.

Các nhóm gói chủ yếu được dùng để kiểm soát chế độ hiển thị. Mục tiêu hiển thị công khai có thể được tham chiếu từ mọi gói trong cây nguồn. Một mục tiêu hiển thị riêng tư chỉ có thể được tham chiếu trong gói riêng của nó (không phải gói con). Giữa các trường hợp này, mục tiêu có thể cho phép truy cập vào gói riêng của mình cùng với bất kỳ gói nào mà một hoặc nhiều nhóm gói mô tả. Để biết nội dung giải thích chi tiết hơn về hệ thống hiển thị, hãy xem thuộc tính chế độ hiển thị.

Một gói nhất định được coi là nằm trong nhóm nếu khớp với thuộc tính packages hoặc đã nằm trong một trong các nhóm gói khác được đề cập trong thuộc tính includes.

Nhóm gói là mục tiêu về mặt kỹ thuật nhưng không được tạo theo quy tắc và không có biện pháp bảo vệ chế độ hiển thị nào.

Đối số

Thuộc tính	Nội dung mô tả
name	Tên; bắt buộc Tên duy nhất cho mục tiêu này.
packages	Danh sách chuỗi; mặc định là [] Danh sách không có hoặc có nhiều thông số kỹ thuật của gói. Mỗi chuỗi thông số kỹ thuật của gói có thể có một trong các dạng sau: Tên đầy đủ của một gói, không có kho lưu trữ, bắt đầu bằng 2 dấu gạch chéo. Ví dụ: //foo/bar chỉ định gói có tên đó và nằm trong cùng một kho lưu trữ với nhóm gói. Như trên, nhưng có /... theo sau. Ví dụ: //foo/... chỉ định một tập hợp //foo và tất cả các gói con của tập hợp đó. //... chỉ định tất cả các gói trong kho lưu trữ hiện tại. Các chuỗi public hoặc private, lần lượt chỉ định mỗi gói hoặc không có gói nào. (Biểu mẫu này yêu cầu bạn phải đặt cờ --incompatible_package_group_has_public_syntax.) Ngoài ra, hai kiểu thông số kỹ thuật đầu tiên của gói cũng có thể được thêm tiền tố - để cho biết rằng chúng bị phủ định. Nhóm gói chứa bất kỳ gói nào phù hợp với ít nhất một trong các thông số kỹ thuật dương của nhóm và không có thông số kỹ thuật tiêu cực nào của nhóm. Ví dụ: giá trị [//foo/..., -//foo/tests/...] bao gồm mọi gói con của //foo mà không phải là gói con của //foo/tests. (//foo được đưa vào trong khi //foo/tests thì không.) Ngoài chế độ hiển thị công khai, không có cách nào để chỉ định trực tiếp các gói bên ngoài kho lưu trữ hiện tại. Nếu thiếu thuộc tính này, việc này cũng giống như việc đặt thuộc tính này thành một danh sách trống, cũng giống như việc đặt thuộc tính này thành một danh sách chỉ chứa private. Lưu ý: Trước Bazel 6.0, quy cách //... có hành vi cũ giống như public. Hành vi này được khắc phục khi --incompatible_fix_package_group_reporoot_syntax được bật (đây là chế độ mặc định sau Bazel 6.0). Lưu ý: Trước Bazel 6.0, khi thuộc tính này được chuyển đổi tuần tự như một phần của bazel query --output=proto (hoặc --output=xml), các dấu gạch chéo ở đầu sẽ bị bỏ qua. Ví dụ: //pkg/foo/... sẽ cho ra kết quả dưới dạng \"pkg/foo/...\". Hành vi này được khắc phục khi --incompatible_package_group_includes_double_slash được bật (đây là chế độ mặc định sau Bazel 6.0).
includes	Danh sách nhãn; mặc định là [] Các nhóm gói khác được bao gồm trong mục này. Nhãn trong thuộc tính này phải tham chiếu đến các nhóm gói khác. Các gói trong nhóm gói đã tham chiếu sẽ được đưa vào nhóm gói này. Đây là mang tính bắc cầu – nếu nhóm gói a bao gồm nhóm gói b và b bao gồm nhóm gói c, thì mọi gói trong c cũng sẽ là một thành viên của a. Khi được sử dụng cùng với thông số kỹ thuật của gói bị bỏ qua, hãy lưu ý rằng tập hợp các gói cho từng nhóm sẽ được tính toán độc lập trước tiên, sau đó kết quả sẽ được hợp nhất với nhau. Điều này có nghĩa là các thông số kỹ thuật bị loại bỏ trong một nhóm sẽ không ảnh hưởng đến các thông số kỹ thuật trong một nhóm khác.

Ví dụ

Nội dung khai báo package_group sau đây chỉ định một nhóm gói có tên là "nhiệt đới" chứa trái cây nhiệt đới.

package_group(
    name = "tropical",
    packages = [
        "//fruits/mango",
        "//fruits/orange",
        "//fruits/papaya/...",
    ],
)

Nội dung khai báo sau đây chỉ định nhóm gói của một ứng dụng hư cấu:

package_group(
    name = "fooapp",
    includes = [
        ":controller",
        ":model",
        ":view",
    ],
)

package_group(
    name = "model",
    packages = ["//fooapp/database"],
)

package_group(
    name = "view",
    packages = [
        "//fooapp/swingui",
        "//fooapp/webui",
    ],
)

package_group(
    name = "controller",
    packages = ["//fooapp/algorithm"],
)

exports_files

exports_files([label, ...], visibility, licenses)

exports_files() chỉ định danh sách các tệp thuộc gói này và được xuất sang các gói khác.

Tệp BUILD cho một gói chỉ có thể tham chiếu trực tiếp đến các tệp nguồn thuộc về một gói khác nếu những tệp đó được xuất rõ ràng bằng câu lệnh exports_files(). Đọc thêm về khả năng hiển thị của tệp.

Theo một hành vi cũ, các tệp được đề cập là dữ liệu đầu vào cho quy tắc sẽ được xuất với chế độ hiển thị mặc định cho đến khi cờ --incompatible_no_implicit_file_export được lật ngược. Tuy nhiên, bạn không nên dựa vào và chủ động di chuyển khỏi hành vi này.

Đối số

Đối số là danh sách tên của các tệp trong gói hiện tại. Bạn cũng có thể chỉ định phần khai báo chế độ hiển thị; trong trường hợp này, tệp sẽ hiển thị cho các mục tiêu được chỉ định. Nếu bạn không chỉ định chế độ hiển thị, các tệp sẽ hiển thị với mọi gói, ngay cả khi chế độ hiển thị mặc định của gói được chỉ định trong hàm package. Bạn cũng có thể chỉ định giấy phép.

Ví dụ:

Ví dụ sau đây xuất golden.txt (một tệp văn bản từ gói test_data) để các gói khác có thể sử dụng tệp này, chẳng hạn như trong thuộc tính data của kiểm thử.

# from //test_data/BUILD

exports_files(["golden.txt"])

hình cầu

glob(include, exclude=[], exclude_directories=1, allow_empty=True)

Glob là một hàm trợ giúp giúp tìm tất cả các tệp khớp với một số mẫu đường dẫn nhất định và trả về một danh sách mới, có thể thay đổi và được sắp xếp cho các đường dẫn của các đường dẫn đó. Glob chỉ tìm kiếm các tệp trong gói riêng và chỉ tìm các tệp nguồn (không phải các tệp đã tạo hay các mục tiêu khác).

Nhãn của tệp nguồn sẽ được đưa vào kết quả nếu đường dẫn tương đối theo gói của tệp khớp với bất kỳ mẫu include nào và không có mẫu exclude nào.

Danh sách include và exclude chứa các mẫu đường dẫn liên quan đến gói hiện tại. Mỗi mẫu có thể bao gồm một hoặc nhiều phân đoạn đường dẫn. Như thường lệ với đường dẫn Unix, các phân đoạn này được phân tách bằng /. Các phân đoạn có thể chứa ký tự đại diện *: ký tự này khớp với bất kỳ chuỗi con nào trong phân đoạn đường dẫn (kể cả chuỗi con trống), ngoại trừ dấu phân cách thư mục /. Bạn có thể dùng ký tự đại diện này nhiều lần trong một phân đoạn đường dẫn. Ngoài ra, ký tự đại diện ** có thể khớp với 0 hoặc nhiều phân đoạn đường dẫn hoàn chỉnh, nhưng phải được khai báo là phân đoạn đường dẫn độc lập.

Ví dụ:

• foo/bar.txt khớp chính xác với tệp foo/bar.txt trong gói này
• foo/*.txt khớp với mọi tệp trong thư mục foo/ nếu tệp đó kết thúc bằng .txt (trừ phi foo/ là gói con)
• foo/a*.htm* khớp với mọi tệp trong thư mục foo/ bắt đầu bằng a, sau đó có một chuỗi tuỳ ý (có thể để trống), sau đó có .htm và kết thúc bằng một chuỗi tuỳ ý khác; chẳng hạn như foo/axx.htm và foo/a.html hoặc foo/axxx.html
• **/a.txt khớp với mọi tệp a.txt trong mọi thư mục con của gói này
• **/bar/**/*.txt khớp với mọi tệp .txt trong mọi thư mục con của gói này, nếu ít nhất một thư mục trên đường dẫn kết quả được gọi là bar, chẳng hạn như xxx/bar/yyy/zzz/a.txt hoặc bar/a.txt (hãy lưu ý rằng ** cũng khớp với các phân đoạn 0) hoặc bar/zzz/a.txt
• ** khớp với mọi tệp trong mọi thư mục con của gói này
• foo**/a.txt là mẫu không hợp lệ vì ** phải đứng riêng như một phân đoạn

Nếu đối số exclude_directories được bật (đặt thành 1), thì các tệp thuộc thư mục loại sẽ bị loại khỏi kết quả (mặc định là 1).

Nếu bạn đặt đối số allow_empty thành False, hàm glob sẽ bị lỗi nếu kết quả là danh sách trống.

Có một số giới hạn và cảnh báo quan trọng:

1. Vì glob() chạy trong quá trình đánh giá tệp BUILD, glob() sẽ chỉ so khớp các tệp trong cây nguồn, chứ không bao giờ so khớp với các tệp được tạo. Nếu đang tạo một mục tiêu yêu cầu cả tệp nguồn lẫn tệp được tạo, bạn phải thêm danh sách rõ ràng các tệp đã tạo vào khối cầu. Hãy xem ví dụ bên dưới với :mylib và :gen_java_srcs.

2. Nếu một quy tắc có cùng tên với tệp nguồn phù hợp, thì quy tắc đó sẽ "ẩn" tệp đó.

   Để hiểu điều này, hãy nhớ rằng glob() trả về danh sách các đường dẫn, vì vậy, việc sử dụng glob() trong thuộc tính của quy tắc khác (ví dụ: srcs = glob(["*.cc"])) cũng có tác dụng tương tự như việc liệt kê các đường dẫn khớp một cách rõ ràng. Ví dụ: nếu glob() tạo ra ["Foo.java", "bar/Baz.java"] nhưng cũng có một quy tắc trong gói có tên là "Foo.java" (được phép, mặc dù Bazel cảnh báo về quy tắc này), thì người sử dụng glob() sẽ sử dụng quy tắc "Foo.java" (kết quả đầu ra của quy tắc) thay vì tệp "Foo.java". Hãy xem Vấn đề GitHub #10395 để biết thêm thông tin chi tiết.

3. Tệp hình ảnh có thể khớp với các tệp trong thư mục con. Đồng thời, tên thư mục con có thể được ký tự đại diện. Tuy nhiên...

4. Nhãn không được phép vượt qua ranh giới của gói và tệp toàn cầu sẽ không khớp với các tệp trong các gói con.

   Ví dụ: biểu thức hình cầu **/*.cc trong gói x không bao gồm x/y/z.cc nếu x/y tồn tại dưới dạng một gói (dưới dạng x/y/BUILD hoặc một vị trí khác trên đường dẫn gói). Điều này có nghĩa là kết quả của biểu thức toàn cầu thực sự phụ thuộc vào sự tồn tại của các tệp BUILD. Điều này có nghĩa là, biểu thức glob tương tự sẽ bao gồm x/y/z.cc nếu không có gói nào được gọi là x/y hoặc gói đó được đánh dấu là đã xoá bằng cờ --deleted_packages.

5. Quy định hạn chế ở trên áp dụng cho mọi biểu thức toàn cầu, bất kể chúng sử dụng ký tự đại diện nào.
6. Một tệp ẩn có tên tệp bắt đầu bằng . hoàn toàn khớp với cả ký tự đại diện ** và *. Nếu bạn muốn so khớp tệp ẩn với mẫu phức hợp, mẫu của bạn cần phải bắt đầu bằng .. Ví dụ: * và .*.txt sẽ khớp với .foo.txt, nhưng *.txt thì không. Các thư mục ẩn cũng được so khớp theo cách tương tự. Các thư mục ẩn có thể chứa những tệp không cần thiết làm dữ liệu đầu vào, đồng thời có thể làm tăng số lượng tệp được cầu nối và mức sử dụng bộ nhớ một cách không cần thiết. Để loại trừ các thư mục ẩn, hãy thêm các thư mục đó vào đối số danh sách "loại trừ".
7. Ký tự đại diện "**" có một kiểu viết hoa ở góc: mẫu "**" không khớp với đường dẫn thư mục của gói. Điều này có nghĩa là glob(["**"], exclude_directories = 0) khớp với mọi tệp và thư mục theo cách bắc cầu và nằm hoàn toàn trong thư mục của gói hiện tại (nhưng tất nhiên sẽ không đi vào thư mục của các gói con – hãy xem ghi chú trước về việc này).

Nói chung, bạn nên thử cung cấp một tiện ích thích hợp (ví dụ: *.html) thay vì sử dụng '*' đơn thuần cho mẫu cầu nối. Tên rõ ràng hơn vừa tự ghi thành tài liệu vừa đảm bảo rằng bạn không vô tình khớp các tệp sao lưu hoặc các tệp tự động lưu emacs/vi/...

Khi viết các quy tắc bản dựng, bạn có thể liệt kê các phần tử của khối cầu. Ví dụ: điều này cho phép tạo từng quy tắc cho mọi dữ liệu đầu vào. Hãy xem phần ví dụ về cụm từ tìm kiếm mở rộng ở bên dưới.

Ví dụ về ánh sáng loá

Tạo một thư viện Java được xây dựng từ tất cả các tệp java trong thư mục này và tất cả các tệp do quy tắc :gen_java_srcs tạo.

java_library(
    name = "mylib",
    srcs = glob(["*.java"]) + [":gen_java_srcs"],
    deps = "...",
)

genrule(
    name = "gen_java_srcs",
    outs = [
        "Foo.java",
        "Bar.java",
    ],
    ...
)

Bao gồm tất cả các tệp txt trong dữ liệu kiểm thử thư mục, ngoại trừ tệp experiment.txt. Lưu ý rằng các tệp trong thư mục con của dữ liệu kiểm thử sẽ không được đưa vào. Nếu bạn muốn đưa các tệp đó vào, hãy sử dụng hình cầu đệ quy (**).

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(
        ["testdata/*.txt"],
        exclude = ["testdata/experimental.txt"],
    ),
)

Ví dụ về vòng tròn đệ quy

Đảm bảo chương trình kiểm thử phụ thuộc vào tất cả các tệp txt trong thư mục dữ liệu kiểm thử cũng như mọi thư mục con của thư mục đó (và các thư mục con, v.v.). Các thư mục con chứa tệp BUILD sẽ bị bỏ qua. (Xem các giới hạn và cảnh báo ở trên.)

sh_test(
    name = "mytest",
    srcs = ["mytest.sh"],
    data = glob(["testdata/**/*.txt"]),
)

Tạo một thư viện được xây dựng từ tất cả các tệp java trong thư mục này và tất cả thư mục con, ngoại trừ những thư mục có đường dẫn chứa một thư mục có tên là kiểm thử. Bạn nên tránh dùng mẫu này nếu có thể, vì mẫu này có thể làm giảm mức độ gia tăng của bản dựng, từ đó làm tăng thời gian xây dựng.

java_library(
    name = "mylib",
    srcs = glob(
        ["**/*.java"],
        exclude = ["**/testing/**"],
    ),
)

Ví dụ về băng thông rộng mở rộng

Tạo một quy tắc chung cho *_test.cc trong thư mục hiện tại để đếm số dòng trong tệp.

# Conveniently, the build language supports list comprehensions.
[genrule(
    name = "count_lines_" + f[:-3],  # strip ".cc"
    srcs = [f],
    outs = ["%s-linecount.txt" % f[:-3]],
    cmd = "wc -l $< >$@",
 ) for f in glob(["*_test.cc"])]

Nếu tệp XÂY DỰNG ở trên nằm trong gói //foo và gói đó chứa 3 tệp phù hợp là a_test.cc, b_test.cc và c_test.cc, thì việc chạy bazel query '//foo:all' sẽ liệt kê tất cả quy tắc đã tạo:

$ bazel query '//foo:all' | sort
//foo:count_lines_a_test
//foo:count_lines_b_test
//foo:count_lines_c_test

chọn

select(
    {conditionA: valuesA, conditionB: valuesB, ...},
    no_match_error = "custom message"
)

select() là hàm trợ giúp giúp định cấu hình thuộc tính quy tắc. Tệp này có thể thay thế phần bên phải của hầu hết mọi thao tác chỉ định thuộc tính, vì vậy giá trị của thuộc tính này phụ thuộc vào cờ Bazel dòng lệnh. Ví dụ: bạn có thể sử dụng quy tắc này để xác định các phần phụ thuộc dành riêng cho nền tảng hoặc để nhúng các tài nguyên khác nhau, tuỳ thuộc vào việc quy tắc được tạo ở chế độ "nhà phát triển" hay chế độ "phát hành".

Dưới đây là cách sử dụng cơ bản:

sh_binary(
    name = "mytarget",
    srcs = select({
        ":conditionA": ["mytarget_a.sh"],
        ":conditionB": ["mytarget_b.sh"],
        "//conditions:default": ["mytarget_default.sh"]
    })
)

Thao tác này giúp bạn có thể định cấu hình thuộc tính srcs của sh_binary bằng cách thay thế trạng thái gán danh sách nhãn thông thường bằng lệnh gọi select ánh xạ các điều kiện cấu hình với các giá trị trùng khớp. Mỗi điều kiện là một nhãn tham chiếu đến config_setting hoặc constraint_value và sẽ "khớp" nếu cấu hình của mục tiêu khớp với một tập hợp giá trị dự kiến. Sau đó, giá trị của mytarget#srcs sẽ trở thành bất kỳ danh sách nhãn nào khớp với lệnh gọi hiện tại.

Lưu ý:

• Chỉ cần chọn đúng một điều kiện trên mọi lệnh gọi.
• Nếu có nhiều điều kiện trùng khớp và một điều kiện là chuyên môn của các điều kiện khác, thì chuyên môn sẽ được ưu tiên. Điều kiện B được coi là chuyên môn của điều kiện A nếu B có tất cả các cờ và giá trị ràng buộc giống như A cộng thêm một số cờ hoặc giá trị ràng buộc bổ sung. Điều này cũng có nghĩa là quá trình phân giải chuyên biệt không được thiết kế để tạo thứ tự như minh hoạ trong Ví dụ 2 bên dưới.
• Nếu nhiều điều kiện trùng khớp và một điều kiện không phải là chuyên môn của tất cả các điều kiện khác, thì Bazel sẽ gặp lỗi, trừ khi tất cả điều kiện đều giải quyết thành cùng một giá trị.
• Nhãn giả đặc biệt //conditions:default sẽ được xem là khớp nếu không có điều kiện nào khác khớp. Nếu điều kiện này bị bỏ qua, một số quy tắc khác phải khớp để tránh xảy ra lỗi.
• Bạn có thể nhúng select bên trong một lệnh chỉ định thuộc tính lớn hơn. Vì vậy, srcs = ["common.sh"] + select({ ":conditionA": ["myrule_a.sh"], ...}) và srcs = select({ ":conditionA": ["a.sh"]}) + select({ ":conditionB": ["b.sh"]}) là biểu thức hợp lệ.
• select hoạt động với hầu hết (nhưng không phải tất cả) thuộc tính. Các thuộc tính không tương thích được đánh dấu là nonconfigurable trong tài liệu tương thích.

  gói con

  subpackages(include, exclude=[], allow_empty=True)

  subpackages() là một hàm trợ giúp, tương tự như glob() liệt kê các gói con thay vì tệp và thư mục. Tệp này sử dụng các mẫu đường dẫn giống như glob() và có thể khớp với mọi gói con là thành phần con trực tiếp của tệp BUILD đang tải. Bạn có thể xem phần glob (toàn cầu) để biết nội dung giải thích chi tiết cũng như ví dụ về các mẫu bao gồm và loại trừ.

  Danh sách kết quả của các gói con được trả về theo thứ tự được sắp xếp và chứa các đường dẫn liên quan đến gói tải hiện tại khớp với các mẫu đã cho trong include chứ không phải các mẫu trong exclude.

  Ví dụ:

  Ví dụ sau đây liệt kê tất cả các gói con trực tiếp cho gói foo/BUILD

  # The following BUILD files exist:
  # foo/BUILD
  # foo/bar/baz/BUILD
  # foo/sub/BUILD
  # foo/sub/deeper/BUILD
  #
  # In foo/BUILD a call to
  subs = subpackages(include = ["**"])
  
  # results in subs == ["sub", "bar/baz"]
  #
  # 'sub/deeper' is not included because it is a subpackage of 'foo/sub' not of
  # 'foo'
  

  Nhìn chung, người dùng nên sử dụng mô-đun "subpackages" của skylib thay vì gọi trực tiếp hàm này.