Tệp .bzl

Báo cáo sự cố

Các phương thức chung có trong mọi tệp .bzl.

Hội viên

analysis_test_transition

transition analysis_test_transition(settings)

Tạo một lượt chuyển đổi cấu hình để áp dụng cho các phần phụ thuộc của quy tắc kiểm thử phân tích. Việc chuyển đổi này chỉ có thể áp dụng trên các thuộc tính của quy tắc có analysis_test = True. Những quy tắc như vậy bị hạn chế về khả năng (ví dụ: kích thước của cây phần phụ thuộc bị hạn chế), vì vậy, các lượt chuyển đổi được tạo bằng hàm này bị giới hạn trong phạm vi tiềm năng so với các lượt chuyển đổi được tạo bằng transition().

Chức năng này chủ yếu được thiết kế để hỗ trợ thư viện cốt lõi Analyze Test Framework (Khung kiểm thử phân tích). Hãy xem tài liệu (hoặc cách triển khai) để biết các phương pháp hay nhất.

Thông số

Thông số Nội dung mô tả
settings bắt buộc
Từ điển chứa thông tin về các chế độ cài đặt cấu hình sẽ được thiết lập trong quá trình chuyển đổi cấu hình này. Khoá là nhãn cài đặt bản dựng và giá trị là các giá trị mới sau khi chuyển đổi. Tất cả các chế độ cài đặt khác đều không thay đổi. Sử dụng mã này để khai báo các chế độ cài đặt cấu hình cụ thể mà bài kiểm thử phân tích yêu cầu phải thiết lập để đạt.

chương trình thành phần

Aspect aspect(implementation, attr_aspects=[], attrs={}, required_providers=[], required_aspect_providers=[], provides=[], requires=[], fragments=[], host_fragments=[], toolchains=[], incompatible_use_toolchain_transition=False, doc=None, *, apply_to_generating_rules=False, exec_compatible_with=[], exec_groups=None, subrules=[])

Tạo ra một khía cạnh mới. Kết quả của hàm này phải được lưu trữ trong giá trị chung. Vui lòng xem phần giới thiệu về các khía cạnh để biết thêm chi tiết.

Thông số

Thông số Nội dung mô tả
implementation bắt buộc
Hàm Starlark triển khai khía cạnh này, với chính xác hai thông số: Target (mục tiêu mà khía cạnh được áp dụng) và ctx (ngữ cảnh quy tắc được tạo từ mục tiêu). Các thuộc tính của mục tiêu có trong trường ctx.rule. Hàm này được đánh giá trong giai đoạn phân tích đối với mỗi lần áp dụng một thành phần cho mục tiêu.
attr_aspects trình tự của chuỗi; mặc định là []
Danh sách tên thuộc tính. Khung hiển thị sẽ truyền đi cùng với các phần phụ thuộc được chỉ định trong các thuộc tính của mục tiêu bằng các tên này. Các giá trị phổ biến ở đây bao gồm deps và exports. Danh sách này cũng có thể chứa một chuỗi "*" để truyền dọc theo tất cả các phần phụ thuộc của một mục tiêu.
attrs dict; mặc định là {}
Từ điển khai báo tất cả thuộc tính của khung hình. Tệp này liên kết từ một tên thuộc tính đến một đối tượng thuộc tính, chẳng hạn như "attr.label" hoặc "attr.string" (xem mô-đun attr). Thuộc tính tỷ lệ khung hình có sẵn cho hàm triển khai dưới dạng các trường của tham số ctx.

Các thuộc tính ngầm ẩn bắt đầu bằng _ phải có giá trị mặc định và có loại label hoặc label_list.

Các thuộc tính rõ ràng phải có loại string và phải sử dụng quy tắc hạn chế values. Thuộc tính rõ ràng hạn chế việc chỉ sử dụng một phần với các quy tắc có thuộc tính có cùng tên, loại và giá trị hợp lệ theo quy định hạn chế.

required_providers giá trị mặc định là []
Thuộc tính này cho phép thành phần hiển thị giới hạn việc truyền tải đến những mục tiêu có quy tắc quảng cáo các nhà cung cấp bắt buộc. Giá trị phải là một danh sách chứa từng nhà cung cấp hoặc danh sách nhà cung cấp, chứ không được chứa cả hai. Ví dụ: [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] là giá trị hợp lệ trong khi [FooInfo, BarInfo, [BazInfo, QuxInfo]] không hợp lệ.

Danh sách nhà cung cấp không trùng lặp sẽ tự động được chuyển thành danh sách chứa một danh sách nhà cung cấp. Nghĩa là, [FooInfo, BarInfo] sẽ tự động được chuyển đổi thành [[FooInfo, BarInfo]].

Để hiển thị một số mục tiêu quy tắc (ví dụ: some_rule) theo một khía cạnh, some_rule phải quảng cáo tất cả các nhà cung cấp từ ít nhất một trong các danh sách nhà cung cấp bắt buộc. Ví dụ: nếu required_providers của một khung hình là [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], thì khung hiển thị này có thể thấy các mục tiêu some_rule khi và chỉ khi some_rule cung cấp FooInfo, hoặc BarInfo, hoặc cả BazInfo và QuxInfo.

required_aspect_providers mặc định là []
Thuộc tính này cho phép khía cạnh này kiểm tra các khía cạnh khác. Giá trị phải là một danh sách chứa từng nhà cung cấp hoặc danh sách nhà cung cấp, chứ không được chứa cả hai. Ví dụ: [[FooInfo], [BarInfo], [BazInfo, QuxInfo]] là giá trị hợp lệ trong khi [FooInfo, BarInfo, [BazInfo, QuxInfo]] không hợp lệ.

Danh sách nhà cung cấp không trùng lặp sẽ tự động được chuyển thành danh sách chứa một danh sách nhà cung cấp. Nghĩa là, [FooInfo, BarInfo] sẽ tự động được chuyển đổi thành [[FooInfo, BarInfo]].

Để hiển thị một khía cạnh khác (ví dụ: other_aspect) cho khía cạnh này, other_aspect phải cung cấp tất cả các trình cung cấp thuộc ít nhất một trong các danh sách. Trong ví dụ về [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], thành phần này có thể thấy other_aspect khi và chỉ khi other_aspect cung cấp FooInfo, hoặc BarInfo, hoặc cả BazInfo và QuxInfo.

provides mặc định là []
Danh sách nhà cung cấp mà hàm triển khai phải trả về.

Đây là lỗi nếu hàm triển khai bỏ qua bất kỳ loại trình cung cấp nào được liệt kê ở đây khỏi giá trị trả về. Tuy nhiên, hàm triển khai có thể trả về các nhà cung cấp khác không được liệt kê ở đây.

Mỗi phần tử của danh sách là một đối tượng *Info do provider() trả về, ngoại trừ việc một nhà cung cấp cũ được biểu thị bằng tên chuỗi.Khi một mục tiêu của quy tắc được dùng làm phần phụ thuộc cho một mục tiêu khai báo nhà cung cấp bắt buộc, bạn không cần chỉ định nhà cung cấp đó tại đây. Chỉ cần hàm triển khai trả về giá trị là đủ. Tuy nhiên, phương pháp hay nhất là chỉ định mã, mặc dù đây không phải là yêu cầu bắt buộc. Tuy nhiên, trường required_providers của một quan điểm yêu cầu phải chỉ định nhà cung cấp tại đây.

requires trình tự của Các khía cạnh; mặc định là []
Danh sách các phương diện cần được truyền trước phương diện này.
fragments trình tự của chuỗi; mặc định là []
Danh sách tên của các mảnh cấu hình mà khung hiển thị yêu cầu ở cấu hình mục tiêu.
host_fragments trình tự của chuỗi; mặc định là []
Danh sách tên của các mảnh cấu hình mà khung này yêu cầu trong cấu hình máy chủ lưu trữ.
toolchains trình tự; giá trị mặc định là []
Nếu được đặt, bạn sẽ cần phải đặt chuỗi công cụ theo quy tắc này. Danh sách có thể chứa các đối tượng Chuỗi, Nhãn hoặc StarlarkToolchainTypeApi trong bất kỳ kết hợp nào. Bạn có thể tìm thấy các chuỗi công cụ bằng cách kiểm tra nền tảng hiện tại và cung cấp các chuỗi công cụ này thông qua ctx.toolchain cho quá trình triển khai quy tắc.
incompatible_use_toolchain_transition giá trị mặc định là False
Không dùng nữa, thuộc tính này không còn được sử dụng và bạn nên xoá.
doc string; hoặc None; mặc định là None
Nội dung mô tả về khía cạnh có thể trích xuất bằng các công cụ tạo tài liệu.
apply_to_generating_rules mặc định là False
Nếu đúng, khung hình sẽ áp dụng cho quy tắc tạo của tệp đầu ra khi được áp dụng cho tệp đầu ra.

Ví dụ: giả sử một thành phần truyền bắc cầu qua thuộc tính "phụ thuộc" và áp dụng cho thuộc tính "alpha". Giả sử "alpha" có "phụ thuộc = [":beta_output"]", trong đó "beta_output" là đầu ra đã khai báo của khía cạnh "beta". Giả sử "beta" có mục tiêu "charlie" là một trong các giá trị "phụ thuộc". Nếu "áp dụng_alpha_có_các_quy_tắc=True" cho khía cạnh "áp dụng".

Sai theo mặc định.
exec_compatible_with trình tự của chuỗi; mặc định là []
Danh sách các quy tắc ràng buộc trên nền tảng thực thi áp dụng cho mọi thực thể của khía cạnh này.
exec_groups dict; hoặc None; giá trị mặc định là None
Nhập tên nhóm thực thi (chuỗi) thành exec_groups. Nếu được đặt, hãy cho phép các chương trình thành phần chạy hành động trên nhiều nền tảng thực thi trong một thực thể. Hãy xem tài liệu về nhóm thực thi để biết thêm thông tin.
subrules trình tự của Quy tắc phụ; mặc định là []
Thử nghiệm: danh sách các quy tắc phụ mà khía cạnh này sử dụng.

configuration_field

LateBoundDefault configuration_field(fragment, name)

Tham chiếu giá trị mặc định giới hạn trễ cho một thuộc tính của loại nhãn. Giá trị "giới hạn muộn" nếu yêu cầu tạo cấu hình trước khi xác định giá trị. Mọi thuộc tính dùng giá trị này làm giá trị đều phải riêng tư.

Ví dụ về cách sử dụng:

Xác định thuộc tính quy tắc: 

'_foo': attr.label(default=configuration_field(fragment='java', name='toolchain'))

Truy cập khi triển khai quy tắc: 

  def _rule_impl(ctx):
    foo_info = ctx.attr._foo
    ...

Thông số

Thông số Nội dung mô tả
fragment bắt buộc
Tên của một mảnh cấu hình chứa giá trị giới hạn trễ.
name bắt buộc
Tên giá trị cần nhận từ mảnh cấu hình.

phần phụ thuộc

depset depset(direct=None, order="default", *, transitive=None)

Tạo một phần phụ thuộc. Tham số direct là danh sách các phần tử trực tiếp của phần phụ thuộc, còn tham số transitive là danh sách các phần phụ thuộc có các phần tử trở thành phần tử gián tiếp của phần phụ thuộc đã tạo. Tham số order chỉ định thứ tự các phần tử được trả về khi phần phụ thuộc được chuyển đổi thành danh sách. Hãy xem bài viết Tổng quan về phần cài đặt để biết thêm thông tin.

Tất cả các phần tử (trực tiếp và gián tiếp) của một tập hợp phụ thuộc phải cùng loại, như có được qua biểu thức type(x).

Vì tập hợp dựa trên hàm băm được dùng để loại bỏ trùng lặp trong quá trình lặp lại, nên tất cả các phần tử của tập hợp phụ thuộc đều phải có thể băm. Tuy nhiên, sự bất biến này hiện chưa được kiểm tra một cách nhất quán trong mọi hàm khởi tạo. Dùng cờ --incompatible_always_check_depset_element để bật tính năng kiểm tra nhất quán. Đây sẽ là hành vi mặc định trong các bản phát hành sau này; hãy xem Vấn đề 10313.

Ngoài ra, các phần tử hiện phải không thể thay đổi được, dù quy định hạn chế này sẽ được nới lỏng trong tương lai.

Thứ tự của các phần phụ thuộc đã tạo phải tương thích với thứ tự của các phần phụ thuộc transitive. Đơn đặt hàng "default" tương thích với mọi đơn đặt hàng khác, tất cả các đơn đặt hàng khác chỉ tương thích với chính chúng.

Thông số

Thông số Nội dung mô tả
direct trình tự; hoặc None; mặc định là None
Danh sách các phần tử trực tiếp của một phần phụ thuộc.
order mặc định là "default"
Chiến lược truyền tải cho phần phụ thuộc mới. Hãy xem tại đây để biết các giá trị có thể có.
transitive trình tự của phần phụ thuộc; hay None; mặc định là None
Danh sách các phần phụ thuộc có phần tử sẽ trở thành phần tử gián tiếp của phần phụ thuộc.

exec_group

exec_group exec_group(toolchains=[], exec_compatible_with=[])

Tạo một nhóm thực thi có thể dùng để tạo các hành động cho một nền tảng thực thi cụ thể trong quá trình triển khai quy tắc.

Thông số

Thông số Nội dung mô tả
toolchains trình tự; mặc định là []
Tập hợp chuỗi công cụ mà nhóm thực thi này yêu cầu. Danh sách có thể chứa các đối tượng Chuỗi, Nhãn hoặc StarlarkToolchainTypeApi trong bất kỳ kết hợp nào.
exec_compatible_with trình tự của chuỗi; mặc định là []
Danh sách các quy tắc ràng buộc trên nền tảng thực thi.

module_extension

unknown module_extension(implementation, *, tag_classes={}, doc=None, environ=[], os_dependent=False, arch_dependent=False)

Tạo một tiện ích mô-đun mới. Lưu trữ mã này trong một giá trị chung để có thể xuất và sử dụng trong tệp MODULE.bazel.

Thông số

Thông số Nội dung mô tả
implementation bắt buộc
Hàm triển khai tiện ích mô-đun này. Phải lấy một tham số duy nhất là module_ctx. Hàm này được gọi một lần khi bắt đầu bản dựng để xác định tập hợp các kho lưu trữ có sẵn.
tag_classes giá trị mặc định là {}
Từ điển để khai báo tất cả các lớp thẻ mà tiện ích sử dụng. Phương thức này ánh xạ từ tên của lớp thẻ đến đối tượng tag_class.
doc string; hoặc None; mặc định là None
Nội dung mô tả về phần mở rộng mô-đun có thể trích xuất bằng các công cụ tạo tài liệu.
environ trình tự của chuỗi; mặc định là []
Cung cấp danh sách biến môi trường mà tiện ích mô-đun này phụ thuộc. Nếu một biến môi trường trong danh sách đó thay đổi, thì tiện ích sẽ được đánh giá lại.
os_dependent mặc định là False
Cho biết tiện ích này có phụ thuộc vào hệ điều hành hay không
arch_dependent mặc định là False
Cho biết tiện ích này có phụ thuộc vào cấu trúc hay không

nhà cung cấp

unknown provider(doc=None, *, fields=None, init=None)

Xác định biểu tượng nhà cung cấp. Trình cung cấp có thể được tạo thực thể bằng cách gọi hoặc dùng trực tiếp làm khoá để truy xuất một thực thể của trình cung cấp đó qua một mục tiêu. Ví dụ:
MyInfo = provider()
...
def _my_library_impl(ctx):
    ...
    my_info = MyInfo(x = 2, y = 3)
    # my_info.x == 2
    # my_info.y == 3
    ...

Xem Quy tắc (Nhà cung cấp) để biết hướng dẫn đầy đủ về cách sử dụng nhà cung cấp.

Trả về giá trị có thể gọi Provider nếu bạn không chỉ định init.

Nếu bạn chỉ định init, hàm này sẽ trả về một bộ dữ liệu gồm 2 phần tử: giá trị có thể gọi Provider và giá trị có thể gọi hàm khởi tạo thô. Xem Quy tắc (Khởi chạy tuỳ chỉnh của nhà cung cấp tuỳ chỉnh) và nội dung thảo luận về tham số init bên dưới để biết thông tin chi tiết.

Thông số

Thông số Nội dung mô tả
doc string; hoặc None; mặc định là None
Nội dung mô tả về trình cung cấp có thể trích xuất được bằng các công cụ tạo tài liệu.
fields trình tự của chuỗi; hoặc dict; hoặc None; giá trị mặc định là None
Nếu được chỉ định, hãy giới hạn tập hợp các trường được phép.
Các giá trị có thể là:
  • danh sách trường:
    provider(fields = ['a', 'b'])

  • tên trường từ điển -> tài liệu:
    provider(
       fields = { 'a' : 'Documentation for a', 'b' : 'Documentation for b' })
Tất cả các trường đều không bắt buộc.
init gọi; hoặc None; mặc định là None
Lệnh gọi lại không bắt buộc để xử lý trước và xác thực các giá trị trường của trình cung cấp trong quá trình tạo thực thể. Nếu bạn chỉ định init, provider() sẽ trả về một bộ dữ liệu gồm 2 phần tử: biểu tượng nhà cung cấp thông thường và hàm khởi tạo thô.

Phần mô tả chính xác như sau; xem Quy tắc (Khởi chạy tuỳ chỉnh của nhà cung cấp) để thảo luận và các trường hợp sử dụng trực quan.

Cho phép P là biểu tượng của nhà cung cấp được tạo bằng cách gọi provider(). Về mặt lý thuyết, một thực thể của P sẽ được tạo bằng cách gọi hàm khởi tạo mặc định c(*args, **kwargs). Hàm này thực hiện những việc sau:

  • Nếu args không trống, sẽ xảy ra lỗi.
  • Nếu tham số fields được chỉ định khi provider() được gọi và nếu kwargs chứa bất kỳ khoá nào không được liệt kê trong fields, thì sẽ xảy ra lỗi.
  • Nếu không, c sẽ trả về một thực thể mới, đối với mỗi mục nhập k: v trong kwargs, sẽ có một trường có tên k với giá trị v.
Trong trường hợp lệnh gọi lại init không được cung cấp, thì lệnh gọi đến biểu tượng P sẽ đóng vai trò như một lệnh gọi đến hàm hàm khởi tạo mặc định c; nói cách khác, P(*args, **kwargs) sẽ trả về c(*args, **kwargs). Ví dụ:
MyInfo = provider()
m = MyInfo(foo = 1)
sẽ trình bày rõ ràng để m là một thực thể MyInfo có m.foo == 1.

Nhưng trong trường hợp bạn chỉ định init, lệnh gọi P(*args, **kwargs) sẽ thực hiện các bước sau:

  1. Lệnh gọi lại được gọi dưới dạng init(*args, **kwargs), có nghĩa là với các đối số từ khoá và vị trí giống hệt như đã được truyền đến P.
  2. Giá trị trả về của init dự kiến sẽ là một từ điển (d), có khoá là các chuỗi tên trường. Nếu không, sẽ có lỗi xảy ra.
  3. Một thực thể mới của P được tạo như thể bằng cách gọi hàm khởi tạo mặc định có các mục nhập của d làm đối số từ khoá, như trong c(**d).

Lưu ý: các bước trên ngụ ý rằng một lỗi sẽ xảy ra nếu *args hoặc **kwargs không khớp với chữ ký của init, hoặc quá trình đánh giá phần nội dung của init không thành công (có thể là cố ý thông qua lệnh gọi đến fail()) hoặc nếu giá trị trả về của init không phải là từ điển có giản đồ dự kiến.

Bằng cách này, lệnh gọi lại init sẽ khái quát hoá quy trình xây dựng trình cung cấp thông thường bằng cách cho phép các đối số vị trí và logic tuỳ ý để xử lý trước và xác thực. Thao tác này không cho phép việc tránh né danh sách fields được phép.

Khi init được chỉ định, giá trị trả về của provider() sẽ trở thành một bộ dữ liệu (P, r), trong đó r là hàm khởi tạo thô. Trên thực tế, hành vi của r hoàn toàn giống với hành vi của hàm khởi tạo mặc định c được thảo luận ở trên. Thông thường, r được liên kết với một biến có tiền tố là dấu gạch dưới, do đó chỉ tệp .bzl hiện tại mới có quyền truy cập trực tiếp vào biến đó:

MyInfo, _new_myinfo = provider(init = ...)

repository_rule

callable repository_rule(implementation, *, attrs=None, local=False, environ=[], configure=False, remotable=False, doc=None)

Tạo quy tắc kho lưu trữ mới. Lưu trữ tệp này trong một giá trị chung để có thể tải và gọi tệp từ tệp WORKSPACE.

Thông số

Thông số Nội dung mô tả
implementation bắt buộc
hàm triển khai quy tắc này. Phải có một tham số duy nhất là repository_ctx. Hàm này được gọi trong giai đoạn tải cho mỗi phiên bản của quy tắc.
attrs dict; hoặc None; mặc định là None
từ điển để khai báo tất cả thuộc tính của quy tắc. Tham số này ánh xạ từ tên thuộc tính đến một đối tượng thuộc tính (xem mô-đun attr). Các thuộc tính bắt đầu bằng _ là riêng tư và có thể dùng để thêm phần phụ thuộc ngầm định trên nhãn vào tệp (quy tắc kho lưu trữ không thể phụ thuộc vào cấu phần phần mềm đã tạo). Thuộc tính name được ngầm thêm vào và không được chỉ định.
local mặc định là False
Cho biết quy tắc này tìm nạp mọi thứ từ hệ thống cục bộ và cần được đánh giá lại mỗi lần tìm nạp.
environ trình tự của chuỗi; mặc định là []
Cung cấp danh sách biến môi trường mà quy tắc kho lưu trữ này phụ thuộc. Nếu một biến môi trường trong danh sách đó thay đổi, thì kho lưu trữ sẽ được tìm nạp lại.
configure mặc định là False
Cho biết rằng kho lưu trữ kiểm tra hệ thống cho mục đích định cấu hình
remotable mặc định là False
Thử nghiệm. Đây là thông số thử nghiệm và có thể thay đổi bất cứ lúc nào. Vui lòng không phụ thuộc vào công cụ này. Bạn có thể bật tính năng này trong giai đoạn thử nghiệm bằng cách đặt ---experimental_repo_remote_exec
Tương thích với tính năng thực thi từ xa
doc string; hoặc None; mặc định là None
Nội dung mô tả về quy tắc lưu trữ có thể được trích xuất bằng các công cụ tạo tài liệu.

quy tắc

callable rule(implementation, *, test=unbound, attrs={}, outputs=None, executable=unbound, output_to_genfiles=False, fragments=[], host_fragments=[], _skylark_testable=False, toolchains=[], incompatible_use_toolchain_transition=False, doc=None, provides=[], exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])

Tạo quy tắc mới, có thể được gọi từ tệp BUILD hoặc macro để tạo mục tiêu.

Bạn phải chỉ định quy tắc cho các biến toàn cục trong tệp .bzl; tên của biến toàn cục là tên của quy tắc.

Các quy tắc kiểm thử bắt buộc phải có tên kết thúc bằng _test, trong khi tất cả các quy tắc khác không được có hậu tố này. (Hạn chế này chỉ áp dụng cho các quy tắc, không áp dụng cho mục tiêu của các quy tắc đó).

Thông số

Thông số Nội dung mô tả
implementation bắt buộc
hàm Starlark triển khai quy tắc này phải có chính xác một thông số: ctx. Hàm được gọi trong giai đoạn phân tích cho mỗi trường hợp của quy tắc. Ứng dụng có thể truy cập vào các thuộc tính do người dùng cung cấp. Hàm này phải tạo các thao tác để tạo tất cả kết quả đầu ra đã khai báo.
test bool; mặc định là unbound
Cho dù quy tắc này có phải là quy tắc kiểm thử hay không, tức là quy tắc này có thể là đối tượng của lệnh blaze test hay không. Tất cả các quy tắc kiểm thử sẽ tự động được coi là có thể thực thi. Bạn không cần thiết (và không nên) đặt executable = True một cách rõ ràng cho một quy tắc kiểm thử. Giá trị mặc định là False. Hãy xem trang Quy tắc để biết thêm thông tin.
attrs dict; giá trị mặc định là {}
từ điển để khai báo tất cả thuộc tính của quy tắc. Tham số này ánh xạ từ tên thuộc tính đến một đối tượng thuộc tính (xem mô-đun attr). Các thuộc tính bắt đầu bằng _ là riêng tư và có thể dùng để thêm phần phụ thuộc ngầm định vào nhãn. Thuộc tính name được ngầm thêm vào và không được chỉ định. Các thuộc tính visibility, deprecation, tags, testonly và features được thêm ngầm và không thể ghi đè. Hầu hết các quy tắc chỉ cần một vài thuộc tính. Để hạn chế mức sử dụng bộ nhớ, hàm quy tắc đặt ra giới hạn cho kích thước của các thuộc tính.
outputs dict; hoặc None; hoặc function; mặc định là None
Không dùng nữa. Tham số này không được dùng nữa và sẽ sớm bị xoá. Vui lòng không phụ thuộc vào công cụ này. Tính năng này bị tắt bằng ---incompatible_no_rule_outputs_param. Sử dụng cờ này để xác minh rằng mã của bạn tương thích với việc mã sắp bị xoá.
Tham số này không được dùng nữa. Di chuyển các quy tắc để sử dụng OutputGroupInfo hoặc attr.output.

Giản đồ để xác định dữ liệu đầu ra được khai báo trước. Không giống như thuộc tính output và output_list, người dùng không chỉ định nhãn cho những tệp này. Hãy xem trang Quy tắc để biết thêm thông tin về kết quả được khai báo trước.

Giá trị của đối số này là từ điển hoặc hàm callback cho ra từ điển. Lệnh gọi lại hoạt động tương tự như các thuộc tính phụ thuộc được tính toán: Tên tham số của hàm được so khớp với thuộc tính của quy tắc, do đó, chẳng hạn như nếu bạn truyền outputs = _my_func cùng với định nghĩa def _my_func(srcs, deps): ..., thì hàm sẽ có quyền truy cập vào các thuộc tính srcs và deps. Cho dù từ điển được chỉ định trực tiếp hay thông qua một hàm thì từ điển đều được diễn giải như sau.

Mỗi mục nhập trong từ điển sẽ tạo một đầu ra được khai báo trước, trong đó khoá là giá trị nhận dạng và giá trị là một mẫu chuỗi xác định nhãn của dữ liệu đầu ra. Trong hàm triển khai của quy tắc, giá trị nhận dạng trở thành tên trường dùng để truy cập vào File của đầu ra trong ctx.outputs. Nhãn của kết quả có cùng gói với quy tắc và phần sau gói được tạo bằng cách thay thế từng phần giữ chỗ của biểu mẫu "%{ATTR}" bằng một chuỗi được tạo từ giá trị của thuộc tính ATTR:

  • Các thuộc tính kiểu chuỗi được thay thế nguyên văn.
  • Những thuộc tính có nhãn sẽ trở thành một phần của nhãn sau gói, trừ đi đuôi tệp. Ví dụ: nhãn "//pkg:a/b.c" trở thành "a/b".
  • Các thuộc tính được nhập dữ liệu đầu ra sẽ trở thành một phần của nhãn sau gói, bao gồm cả đuôi tệp (đối với ví dụ trên là "a/b.c").
  • Tất cả thuộc tính dạng danh sách (ví dụ: attr.label_list) dùng trong phần giữ chỗ đều bắt buộc phải có chính xác một phần tử. Lượt chuyển đổi của họ giống với phiên bản không có trong danh sách (attr.label).
  • Các loại thuộc tính khác có thể không xuất hiện trong phần giữ chỗ.
  • Các phần giữ chỗ đặc biệt không phải thuộc tính %{dirname} và %{basename} mở rộng đến các phần đó trong nhãn của quy tắc, ngoại trừ gói của quy tắc. Ví dụ: trong "//pkg:a/b.c", tên thư mục là a và tên cơ sở là b.c.

Trong thực tế, phần giữ chỗ thay thế phổ biến nhất là "%{name}". Ví dụ: đối với mục tiêu có tên "foo", kết quả ra lệnh {"bin": "%{name}.exe"} sẽ khai báo trước một đầu ra có tên là foo.exe. Kết quả này có thể truy cập được trong hàm triển khai dưới dạng ctx.outputs.bin.

executable bool; mặc định là unbound
Liệu quy tắc này có được xem là có thể thực thi hay không, tức là quy tắc này có thể là chủ thể của lệnh blaze run hay không. Thuộc tính này mặc định là False. Hãy xem trang Quy tắc để biết thêm thông tin.
output_to_genfiles mặc định là False
Nếu đúng, tệp sẽ được tạo trong thư mục genfiles thay vì thư mục bin. Không đặt cờ này trừ phi bạn cần để tương thích với các quy tắc hiện có (ví dụ: khi tạo tệp tiêu đề cho C++).
fragments trình tự của chuỗi; mặc định là []
Danh sách tên của các mảnh cấu hình mà quy tắc yêu cầu trong cấu hình mục tiêu.
host_fragments trình tự của chuỗi; mặc định là []
Danh sách tên của các mảnh cấu hình mà quy tắc yêu cầu trong cấu hình máy chủ lưu trữ.
_skylark_testable mặc định là False
(Thử nghiệm)

Nếu đúng, quy tắc này sẽ cho thấy các hành động để kiểm tra theo các quy tắc phụ thuộc vào trình cung cấp Actions. Trình cung cấp này cũng khả dụng cho chính quy tắc bằng cách gọi ctx.created_actions().

Bạn chỉ nên sử dụng phương thức này để kiểm tra hành vi trong thời gian phân tích của các quy tắc Starlark. Cờ này có thể bị xoá trong tương lai.
toolchains trình tự; giá trị mặc định là []
Nếu được đặt, bạn sẽ cần phải đặt chuỗi công cụ theo quy tắc này. Danh sách có thể chứa các đối tượng Chuỗi, Nhãn hoặc StarlarkToolchainTypeApi trong bất kỳ kết hợp nào. Bạn có thể tìm thấy các chuỗi công cụ bằng cách kiểm tra nền tảng hiện tại và cung cấp các chuỗi công cụ này thông qua ctx.toolchain cho quá trình triển khai quy tắc.
incompatible_use_toolchain_transition giá trị mặc định là False
Không dùng nữa, thuộc tính này không còn được sử dụng và bạn nên xoá.
doc string; hoặc None; mặc định là None
Nội dung mô tả về quy tắc có thể trích xuất bằng các công cụ tạo tài liệu.
provides mặc định là []
Danh sách nhà cung cấp mà hàm triển khai phải trả về.

Đây là lỗi nếu hàm triển khai bỏ qua bất kỳ loại trình cung cấp nào được liệt kê ở đây khỏi giá trị trả về. Tuy nhiên, hàm triển khai có thể trả về các nhà cung cấp khác không được liệt kê ở đây.

Mỗi phần tử của danh sách là một đối tượng *Info do provider() trả về, ngoại trừ việc một nhà cung cấp cũ được biểu thị bằng tên chuỗi.Khi một mục tiêu của quy tắc được dùng làm phần phụ thuộc cho một mục tiêu khai báo nhà cung cấp bắt buộc, bạn không cần chỉ định nhà cung cấp đó tại đây. Chỉ cần hàm triển khai trả về giá trị là đủ. Tuy nhiên, phương pháp hay nhất là chỉ định mã, mặc dù đây không phải là yêu cầu bắt buộc. Tuy nhiên, trường required_providers của một quan điểm yêu cầu phải chỉ định nhà cung cấp tại đây.

exec_compatible_with trình tự của chuỗi; mặc định là []
Danh sách các quy tắc ràng buộc trên nền tảng thực thi áp dụng cho mọi mục tiêu của loại quy tắc này.
analysis_test mặc định là False
Nếu đúng, thì quy tắc này được coi là kiểm thử phân tích.

Lưu ý: Các quy tắc kiểm thử trong công cụ Phân tích chủ yếu được xác định bằng cách sử dụng cơ sở hạ tầng được cung cấp trong các thư viện Starlark chính. Hãy xem bài viết Thử nghiệm để biết hướng dẫn.

Nếu một quy tắc được xác định là quy tắc kiểm tra bản phân tích, thì quy tắc đó được phép sử dụng các lượt chuyển đổi cấu hình được xác định bằng cách sử dụng analysis_test_transition trên các thuộc tính của quy tắc đó, nhưng chọn áp dụng một số hạn chế:

  • Mục tiêu của quy tắc này bị giới hạn về số lượng phần phụ thuộc bắc cầu có thể có.
  • Quy tắc này được xem là quy tắc thử nghiệm (như thể bạn đã đặt test=True). Thao tác này sẽ thay thế giá trị của test
  • Hàm triển khai quy tắc có thể không đăng ký các hành động. Thay vào đó, hàm này phải đăng ký kết quả đạt/không đạt bằng cách cung cấp AnalysisTestResultInfo.
build_setting BuildSetting; hoặc None; mặc định là None
Nếu được đặt, hãy mô tả loại build setting của quy tắc này. Xem mô-đun config. Nếu bạn đặt chính sách này, hệ thống sẽ tự động thêm thuộc tính bắt buộc có tên "build_setting_default" vào quy tắc này, với loại tương ứng với giá trị được truyền vào đây.
cfg mặc định là None
Nếu được đặt, hãy trỏ đến phần chuyển đổi cấu hình mà quy tắc sẽ áp dụng cho cấu hình của chính quy tắc đó trước khi phân tích.
exec_groups dict; hoặc None; giá trị mặc định là None
Nhập tên nhóm thực thi (chuỗi) thành exec_groups. Nếu được đặt, hãy cho phép các quy tắc chạy các hành động trên nhiều nền tảng thực thi trong một mục tiêu duy nhất. Hãy xem tài liệu về nhóm thực thi để biết thêm thông tin.
initializer mặc định là None
Thử nghiệm: Hàm Stalark khởi tạo các thuộc tính của quy tắc.

Hàm được gọi vào thời gian tải cho mỗi trường hợp của quy tắc. Phương thức này được gọi bằng các giá trị của các thuộc tính công khai được xác định theo quy tắc (không phải bằng các thuộc tính chung, ví dụ như name hoặc tags).

Phương thức này phải trả về giá trị từ điển của các tên thuộc tính đến giá trị mong muốn. Các thuộc tính không được trả về sẽ không bị ảnh hưởng. Việc trả về None dưới dạng giá trị sẽ dẫn đến việc sử dụng giá trị mặc định được chỉ định trong định nghĩa thuộc tính.

Trình khởi tạo được đánh giá trước các giá trị mặc định được chỉ định trong định nghĩa thuộc tính. Do đó, nếu một tham số trong chữ ký của trình khởi tạo chứa các giá trị mặc định, thì tham số đó sẽ ghi đè giá trị mặc định trong phần định nghĩa thuộc tính (trừ phi trả về None).

Tương tự, nếu một tham số trong chữ ký của trình khởi tạo không có giá trị mặc định, thì tham số đó sẽ trở thành tham số bắt buộc. Trong những trường hợp như vậy, bạn nên bỏ qua các chế độ cài đặt mặc định/bắt buộc đối với phần định nghĩa thuộc tính.

Bạn nên sử dụng **kwargs cho các thuộc tính không được xử lý.

Trong trường hợp quy tắc mở rộng, tất cả trình khởi tạo sẽ được gọi từ thành phần con đến đối tượng cấp trên. Mỗi trình khởi tạo chỉ được truyền các thuộc tính công khai đã biết.

parent mặc định là None
Thử nghiệm: Quy tắc Stalark được mở rộng. Khi đặt, các thuộc tính công khai được hợp nhất cũng như các nhà cung cấp được quảng cáo. Quy tắc này khớp với executable và test từ đơn vị gốc. Giá trị của fragments, toolchains, exec_compatible_with và exec_groups được hợp nhất. Bạn có thể không đặt các thông số cũ hoặc không dùng nữa.
extendable bool; hoặc Nhãn; hoặc chuỗi; hoặc None; giá trị mặc định là None
Thử nghiệm: Nhãn của danh sách cho phép xác định những quy tắc có thể mở rộng quy tắc này. Bạn cũng có thể đặt thành True/False để luôn cho phép/không cho phép mở rộng. Theo mặc định, Bazel luôn cho phép các tiện ích.
subrules trình tự của Quy tắc phụ; mặc định là []
Thử nghiệm: Danh sách các quy tắc phụ mà quy tắc này sử dụng.

chọn

unknown select(x, no_match_error='')

select() là hàm trợ giúp tạo thuộc tính quy tắc có thể định cấu hình. Xem nội dung bách khoa toàn thư về xây dựng để biết thông tin chi tiết.

Thông số

Thông số Nội dung mô tả
x bắt buộc
Một lệnh ánh xạ điều kiện cấu hình với các giá trị. Mỗi khoá là một Nhãn hoặc một chuỗi nhãn giúp xác định một thực thể config_setting hoặcconstrain_value. Xem tài liệu về macro để biết thời điểm sử dụng Nhãn thay vì chuỗi.
no_match_error mặc định là ''
Lỗi tuỳ chỉnh (không bắt buộc) cần báo cáo nếu không có điều kiện nào khớp.

quy tắc phụ

Subrule subrule(implementation, attrs={}, toolchains=[], fragments=[], subrules=[])

Xây dựng một thực thể mới của quy tắc phụ. Kết quả của hàm này phải được lưu trữ trong biến toàn cục trước khi có thể sử dụng.

Thông số

Thông số Nội dung mô tả
implementation hàm; bắt buộc
Hàm Starlark triển khai quy tắc phụ này
attrs dict; mặc định là {}
Một từ điển để khai báo tất cả thuộc tính (private) của quy tắc phụ.

Quy tắc phụ chỉ được có các thuộc tính riêng tư được nhập theo nhãn (tức là nhãn hoặc danh sách nhãn). Các giá trị đã phân giải tương ứng với các nhãn này được Bazel tự động chuyển đến hàm triển khai của quy tắc phụ dưới dạng đối số được đặt tên (do đó, hàm triển khai cần phải chấp nhận các tham số được đặt tên khớp với tên thuộc tính). Loại của các giá trị này sẽ là:

  • FilesToRunProvider cho các thuộc tính nhãn có executable=True
  • File cho các thuộc tính nhãn có allow_single_file=True
  • Target đối với tất cả các thuộc tính nhãn khác
  • [Target] cho tất cả thuộc tính danh sách nhãn
toolchains trình tự; giá trị mặc định là []
Nếu được đặt, quy tắc phụ này sẽ yêu cầu phải có chuỗi công cụ. Danh sách có thể chứa các đối tượng Chuỗi, Nhãn hoặc StarlarkToolchainTypeApi trong bất kỳ kết hợp nào. Bạn sẽ tìm thấy các chuỗi công cụ bằng cách kiểm tra nền tảng hiện tại và cung cấp các chuỗi công cụ cho phương thức triển khai quy tắc phụ thông qua ctx.toolchains.
fragments trình tự của chuỗi; mặc định là []
Danh sách tên của các mảnh cấu hình mà quy tắc phụ yêu cầu trong cấu hình mục tiêu.
subrules trình tự của Quy tắc phụ; mặc định là []
Danh sách các quy tắc phụ khác cần thiết cho quy tắc phụ này.

tag_class

tag_class tag_class(attrs={}, *, doc=None)

Tạo đối tượng tag_class mới để xác định giản đồ thuộc tính cho một lớp thẻ. Đây là các đối tượng dữ liệu có thể sử dụng được trong tiện ích mô-đun.

Thông số

Thông số Nội dung mô tả
attrs giá trị mặc định là {}
Từ điển để khai báo tất cả thuộc tính của lớp thẻ này. Tham số này ánh xạ từ tên thuộc tính đến một đối tượng thuộc tính (xem mô-đun attr).
doc string; hoặc None; giá trị mặc định là None
Nội dung mô tả về lớp thẻ có thể trích xuất bằng các công cụ tạo tài liệu.

mức hiển thị

None visibility(value)

Đặt chế độ hiển thị tải của mô-đun .bzl hiện đang được khởi chạy.

Chế độ hiển thị tải của một mô-đun kiểm soát liệu các tệp BUILD và .bzl khác có thể tải mô-đun đó hay không. (Chế độ hiển thị này khác với chế độ hiển thị mục tiêu của tệp nguồn .bzl cơ bản, tệp này chi phối việc tệp có thể xuất hiện dưới dạng phần phụ thuộc của các mục tiêu khác hay không.) Chế độ hiển thị tải hoạt động ở cấp gói: Để tải một mô-đun, tệp thực hiện tải phải nằm trong gói đã được cấp chế độ hiển thị cho mô-đun. Mô-đun luôn có thể được tải trong gói riêng, bất kể chế độ hiển thị của mô-đun đó.

visibility() chỉ có thể được gọi một lần cho mỗi tệp .bzl và chỉ ở cấp cao nhất, không phải bên trong một hàm. Kiểu ưu tiên là đặt lệnh gọi này ngay bên dưới các câu lệnh load() và mọi logic ngắn gọn cần thiết để xác định đối số.

Nếu bạn đặt cờ --check_bzl_visibility thành false, thì các lỗi vi phạm chế độ hiển thị tải sẽ phát ra cảnh báo nhưng không làm lỗi trong quá trình tạo.

Thông số

Thông số Nội dung mô tả
value bắt buộc
Danh sách các chuỗi thông số kỹ thuật của gói hoặc một chuỗi thông số kỹ thuật của gói.

Thông số kỹ thuật của gói sẽ tuân theo định dạng của package_group, ngoại trừ việc bạn không được dùng thông số kỹ thuật phủ định về gói. Tức là thông số kỹ thuật có thể có các dạng:

  • "//foo": gói //foo
  • "//foo/...": gói //foo và tất cả các gói con của gói đó.
  • "public" hoặc "private": tất cả các gói hoặc không có gói nào tương ứng

Không được phép sử dụng cú pháp "@"; tất cả thông số kỹ thuật được diễn giải tương ứng với kho lưu trữ của mô-đun hiện tại.

Nếu value là một danh sách chuỗi, thì tập hợp các gói được cấp chế độ hiển thị cho mô-đun này là tập hợp các gói được đại diện theo từng thông số kỹ thuật. (Danh sách trống cũng có tác dụng như private.) Nếu value là một chuỗi thì chuỗi này sẽ được xử lý như thể đó là danh sách singleton [value].

Lưu ý rằng cờ --incompatible_package_group_has_public_syntax và --incompatible_fix_package_group_reporoot_syntax không ảnh hưởng đến đối số này. Các giá trị "public" và "private" luôn có sẵn, và "//..." luôn được hiểu là "tất cả các gói trong kho lưu trữ hiện tại".