Tệp .bzl

Báo cáo sự cố Hằng đêm · 7,3 · 7.2 · 7.1 · 7,0 · 6,5

Các phương thức chung có trong tất cả tệp .bzl.

Hội viên

analysis_test_transition

transition analysis_test_transition(settings)

Tạo một quá trình chuyển đổi cấu hình để áp dụng cho các phần phụ thuộc của quy tắc phân tích-kiểm thử. Hiệu ứng chuyển đổi này chỉ có thể áp dụng cho các thuộc tính của quy tắc có analysis_test = True. Các 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ị giới hạn), vì vậy, các hiệu ứng 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 hiệu ứng chuyển đổi được tạo bằng transition().

Hàm này chủ yếu được thiết kế để hỗ trợ thư viện cốt lõi 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.

Tham số

Thông số 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 cần được đặt trong quá trình chuyển đổi cấu hình này. Khoá là các nhãn cài đặt bản dựng và giá trị là giá trị mới sau khi chuyển đổi. Mọi chế độ cài đặt khác đều không thay đổi. Sử dụng lệnh này để khai báo các chế độ cài đặt cấu hình cụ thể mà kiểm thử phân tích yêu cầu phải được thiết lập để có thể vượt qua.

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 một khía cạnh mới. Kết quả của hàm này phải được lưu trữ trong một giá trị toàn cục. Vui lòng xem phần giới thiệu về Aspects để biết thêm thông tin chi tiết.

Tham số

Thông số Mô tả
implementation bắt buộc
Một hàm Starlark triển khai phương diện này với đúng 2 tham số: Target (mục tiêu mà tỷ lệ được áp dụng) và ctx (bối cảnh quy tắc dùng để tạo mục tiêu). Các thuộc tính của mục tiêu có sẵn thông qua trường ctx.rule. Hàm này được đánh giá trong giai đoạn phân tích cho mỗi ứng dụng của một khía cạnh cho một 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. Đối tượng này sẽ truyền theo các phần phụ thuộc được chỉ định trong 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 depsexports. Danh sách này cũng có thể chứa một chuỗi "*" duy nhất để truyền cùng tất cả các phần phụ thuộc của một mục tiêu.
attrs dict; giá trị mặc định là {}
Một từ điển khai báo tất cả các thuộc tính của một phương diện. Thuộc tính này ánh xạ từ tên thuộc tính đến một đối tượng thuộc tính, như "attr.label" hoặc "attr.string" (xem mô-đun attr). Các thuộc tính 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ó cá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 thuộ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 khía cạnh này với các quy tắc có các thuộc tính 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 khía cạnh đó giới hạn việc truyền nội dung ở những mục tiêu có quy tắc quảng cáo 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, nhưng 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 các nhà cung cấp chưa lồng nhau sẽ tự động được chuyển thành danh sách chứa một danh sách các nhà cung cấp. Tức là [FooInfo, BarInfo] sẽ tự động được chuyển đổi thành [[FooInfo, BarInfo]].

Để hiển thị một số mục tiêu theo quy tắc (ví dụ: some_rule) cho một khía cạnh, some_rule phải quảng cáo tất cả các nhà cung cấp của í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 khía cạnh là [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], thì khía cạnh 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 QuxInfo.

required_aspect_providers giá trị 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, nhưng 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 các nhà cung cấp chưa lồng nhau sẽ tự động được chuyển thành danh sách chứa một danh sách các nhà cung cấp. Tức 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), other_aspect phải cung cấp cho tất cả các 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]], khía cạnh 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 QuxInfo.

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

Sẽ không có 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 trong 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ó trong danh sách này.

Mỗi phần tử của danh sách là một đối tượng *Info được provider() trả về, ngoại trừ việc trì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 trình cung cấp được yêu cầu, thì bạn không cần chỉ định trình cung cấp đó tại đây. Hàm triển khai trả về giá trị đó là đủ. Tuy nhiên, phương pháp hay nhất là chỉ định mã này, mặc dù điều này không bắt buộc. Tuy nhiên, trường required_providers của một đối tượng phải được chỉ định nhà cung cấp tại đây.

requires trình tự của Khung hình; mặc định là []
Danh sách các phương diện bắt buộc phải đượ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à thành phần này cần có 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à khía cạnh này yêu cầu trong cấu hình máy chủ.
toolchains trình tự; giá trị mặc định là []
Nếu được đặt, tập hợp các chuỗi công cụ mà quy tắc này yêu cầu. Danh sách này có thể chứa các đối tượng Chuỗi, Nhãn hoặc StarlarkToolchainTypeApi theo bất kỳ cách kết hợp nào. Bạn sẽ tìm thấy chuỗi công cụ bằng cách kiểm tra nền tảng hiện tại và được cung cấp cho việc triển khai quy tắc thông qua ctx.toolchain.
incompatible_use_toolchain_transition giá trị mặc định là False
Không dùng nữa, chính sách này không còn được sử dụng nữa và phải được xoá.
doc string; hoặc None; giá trị mặc định là None
Nội dung mô tả về một khía cạnh có thể được trích xuất bằng các công cụ tạo tài liệu.
apply_to_generating_rules giá trị 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 khung hình truyền tải bắc cầu qua thuộc tính "deps" và khung hình đó được áp dụng cho mục tiêu "alpha". Giả sử `alpha` có `deps = [':beta_output']`, trong đó `beta_output` là kết quả đầu ra được khai báo của `beta` mục tiêu. Giả sử "beta" có một "charlie" mục tiêu là một trong các "dep" của nó. Nếu "apply_to_creating_rules=True" cho một khung hình, thì khung hình đó sẽ truyền qua "alpha", "beta" và "charlie". Nếu là False, thì khung hình sẽ chỉ truyền sang "alpha".

False 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) vào exec_group. Nếu được đặt, hãy cho phép các 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 thuộc loại label. Một giá trị "có giới hạn muộn" nếu hệ thống yêu cầu tạo cấu hình trước khi xác định giá trị. Mọi thuộc tính sử dụng giá trị này làm giá trị phải ở chế độ 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 trong quá trình triển khai quy tắc:

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

Tham số

Thông số 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 của giá trị cần lấy từ mảnh cấu hình.

phần tách rời

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

Tạo một tập hợp. Tham số direct là một danh sách các phần tử trực tiếp của tập hợp lại và tham số transitive là một danh sách các phần tử phụ thuộc mà các phần tử đó trở thành phần tử gián tiếp của tập hợp đã tạo. Thứ tự các phần tử được trả về khi tập hợp được chuyển đổi thành một danh sách được chỉ định bằng tham số order. Xem Tổng quan về phần phụ thuộc để 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ải thuộc cùng một kiểu, như thu được trong 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ỏ các bản sao trong quá trình lặp lại, nên tất cả phần tử của một tập hợp đều có thể băm được. Tuy nhiên, bất biến này hiện không được kiểm tra một cách nhất quán trong tất cả các hàm khởi tạo. Sử dụng cờ --incompatible_always_check_depset_classes để cho phép 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 thành phần hiện phải ở dạng không thể thay đổi, mặc dù quy định hạn chế này sẽ được nới lỏng trong tương lai.

Thứ tự của phần phụ thuộc đượ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 đơn đặt hàng đó.

Tham số

Thông số Mô tả
direct trình tự; hoặc None; giá trị mặc định là None
Danh sách các phần tử trực tiếp của một tập hợp.
order giá trị 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ụ; hoặc None; mặc định là None
Danh sách các phần tử phụ thuộc mà các phần tử của nó sẽ trở thành phần tử gián tiếp của tập hợp.

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.

Tham số

Thông số Mô tả
toolchains trình tự; giá trị mặc định là []
Tập hợp các chuỗi công cụ mà nhóm thực thi này yêu cầu. Danh sách này có thể chứa các đối tượng Chuỗi, Nhãn hoặc StarlarkToolchainTypeApi theo bất kỳ cách 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.

Tham số

Thông số Mô tả
implementation bắt buộc
Hàm triển khai tiện ích mô-đun này. Phải có một tham số duy nhất là module_ctx. Hàm này được gọi một lần ở đầ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à {}
Một từ điển để khai báo tất cả các lớp thẻ mà tiện ích sử dụng. Lớp này liên kết từ tên của lớp thẻ đến đối tượng tag_class.
doc string; hoặc None; giá trị mặc định là None
Nội dung mô tả về tiện ích mô-đun có thể được 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 giá trị 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 giá trị 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

provider

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

Xác định biểu tượng nhà cung cấp. Trình cung cấp này có thể được tạo thực thể bằng cách gọi hoặc được sử dụng trực tiếp làm khoá để truy xuất một thực thể của trình cung cấp đó từ 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 phần 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 init không được chỉ định.

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

Tham số

Thông số Mô tả
doc string; hoặc None; giá trị mặc định là None
Nội dung mô tả về nhà cung cấp có thể được trích xuất 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 nhóm trường được phép.
Các giá trị có thể sử dụng là:
  • danh sách trường:
    provider(fields = ['a', 'b'])

  • tên trường trong 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 có thể gọi; hoặc None; giá trị 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 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ô.

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

Cho P là biểu tượng 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 đượ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 sẽ thực hiện những việc sau:

  • Nếu args không phải là giá trị trống, sẽ xảy ra lỗi.
  • Sẽ có lỗi xảy ra nếu tham số fields được chỉ định khi gọi provider() và nếu kwargs chứa khoá bất kỳ không được liệt kê trong fields.
  • Nếu không, c sẽ trả về một thực thể mới có một trường có tên k với giá trị v cho mỗi mục nhập k: v trong kwargs.
Trong trường hợp không cung cấp lệnh gọi lại init, lệnh gọi đến biểu tượng P sẽ đóng vai trò là 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) trả về c(*args, **kwargs). Chẳng hạn,
MyInfo = provider()
m = MyInfo(foo = 1)
sẽ đơn giản hoá sao cho m là một thực thể MyInfom.foo == 1.

Tuy nhiên, trong trường hợp bạn chỉ định init, thì 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), tức là có cùng đối số vị trí và đối số từ khoá như đã được truyền đến P.
  2. Giá trị trả về của init được dự kiến là một từ điển d, trong đó khoá là các chuỗi tên trường. Nếu không thì sẽ xảy ra lỗi.
  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 với các mục nhập của d làm đối số từ khoá, như trong c(**d).

NB: các bước ở trên ngụ ý rằng sẽ xảy ra lỗi nếu *args hoặc **kwargs không khớp với chữ ký của init hoặc việc đánh giá phần nội dung của init không thành công (có thể do 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 tổng quát hoá quá trình tạo 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. Chính sách này không cho phép tránh né danh sách fields được phép.

Khi chỉ định init, giá trị trả về của provider() sẽ trở thành một bộ dữ liệu (P, r), trong đó rhàm khởi tạo thô. Trên thực tế, hành vi của r chính xác là hành vi của hàm khởi tạo mặc định 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 để chỉ có tệp .bzl hiện tại mới có quyền truy cập trực tiếp vào tệp đó:

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 mới cho kho lưu trữ. Lưu trữ tệp này trong một giá trị chung để bạn có thể tải và gọi tệp từ tệp WORKSPACE.

Tham số

Thông số 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 thực thể của quy tắc.
attrs dict; hoặc None; giá trị mặc định là None
từ điển để khai báo tất cả thuộc tính của quy tắc. Thuộc tính 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 ẩn trên một nhãn vào tệp (quy tắc kho lưu trữ không được phụ thuộc vào cấu phần phần mềm được tạo). Thuộc tính name được ngầm thêm vào và không được chỉ định.
local giá trị mặc định là False
Cho biết rằng quy tắc này tìm nạp mọi thứ từ hệ thống cục bộ và sẽ được đánh giá lại vào mỗi lần tìm nạp.
environ trình tự của chuỗi; mặc định là []
Không dùng nữa. Thông số này không được dùng nữa. Thay vào đó, hãy chuyển sang repository_ctx.getenv.
Cung cấp một danh sách biến môi trường mà quy tắc kho lưu trữ này phụ thuộc vào. 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 giá trị 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 giá trị mặc định là False
Thử nghiệm. Thông số này đang trong giai đoạn thử nghiệm và có thể thay đổi bất cứ lúc nào. Vui lòng đừng phụ thuộc vào tính năng này. Tính năng này có thể được bật trên cơ sở thử nghiệm bằng cách thiết lập ---experimental_repo_remote_exec
Tương thích với thực thi từ xa
doc string; hoặc None; giá trị mặc định là None
Nội dung mô tả về quy tắc kho 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.

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

Quy tắc thử nghiệm 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 các mục tiêu của chúng.)

Tham số

Thông số Mô tả
implementation bắt buộc
hàm Starlark triển khai quy tắc này phải có đúng một tham số: ctx. Hàm này được gọi trong giai đoạn phân tích cho mỗi thực thể 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. Lớp này phải tạo các thao tác để tạo tất cả dữ liệu đầu ra đã khai báo.
test bool; giá trị 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 đó có thể là chủ thể của lệnh blaze test hay không. Tất 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 khuyến khích) đặt executable = True một cách rõ ràng cho quy tắc kiểm thử. Giá trị mặc định là False. 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. Thuộc tính 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 ẩn vào một 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, testonlyfeatures được ngầm thêm vào và không ghi đè được. Hầu hết các quy tắc chỉ cần một số thuộc tính. Để giới hạn mức sử dụng bộ nhớ, hàm quy tắc đặt ra giới hạn về kích thước của thuộc tính.
outputs dict; hoặc None; hoặc hàm; 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 đừng phụ thuộc vào tính năng này. Tính năng này đã bị tắt với ---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 yêu cầu sắp xoá.
Tham số này không được dùng nữa. Hãy di chuyển các quy tắc để sử dụng OutputGroupInfo hoặc attr.output.

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

Giá trị của đối số này là một từ điển hoặc một hàm callback có chức năng tạo ra một từ điển. Lệnh gọi lại hoạt động tương tự như các thuộc tính phần phụ thuộc đã tính toán: Tên tham số của hàm được so khớp với các thuộc tính của quy tắc. Chẳng hạn, nếu bạn truyền outputs = _my_func 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 srcsdeps. Dù được chỉ định trực tiếp hay qua một hàm, từ điển vẫn đượ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à một giá trị nhận dạng và giá trị là một mẫu chuỗi xác định nhãn của đầu ra. Trong hàm triển khai của quy tắc, giá trị nhận dạng sẽ trở thành tên trường dùng để truy cập vào File của dữ liệu đầu ra trong ctx.outputs. Nhãn của đầu ra 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.
  • Các thuộc tính được nhập nhãn trở thành một phần của nhãn nằm sau gói trừ đi đuôi tệp. Ví dụ: nhãn "//pkg:a/b.c" sẽ trở thành "a/b".
  • Các thuộc tính kiểu đầu ra trở thành một phần của nhãn sau gói, bao gồm cả đuôi tệp (trong 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ỗ bắt buộc phải có đúng một phần tử. Phiên bản 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}%{basename} sẽ mở rộng đến các phần đó của nhãn quy tắc, ngoại trừ gói. Ví dụ: trong "//pkg:a/b.c", tên dirname 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ả đầu ra dict {"bin": "%{name}.exe"} sẽ khai báo trước một đầu ra có tên foo.exe có thể truy cập được trong hàm triển khai dưới dạng ctx.outputs.bin.

executable bool; giá trị mặc định là unbound
Liệu quy tắc này có được coi là có thể thực thi hay không, tức là liệu quy tắc đó 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. Xem trang Quy tắc để biết thêm thông tin.
output_to_genfiles giá trị mặc định là False
Nếu giá trị là true, các tệp sẽ được tạo trong thư mục genfiles thay vì thư mục bin. Trừ khi bạn cần 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++), không đặt cờ 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à 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ủ.
_skylark_testable giá trị mặc định là False
(Thử nghiệm)

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

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

Sẽ không có 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 trong 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ó trong danh sách này.

Mỗi phần tử của danh sách là một đối tượng *Info được provider() trả về, ngoại trừ việc trì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 trình cung cấp được yêu cầu, thì bạn không cần chỉ định trình cung cấp đó tại đây. Hàm triển khai trả về giá trị đó là đủ. Tuy nhiên, phương pháp hay nhất là chỉ định mã này, mặc dù điều này không bắt buộc. Tuy nhiên, trường required_providers của một đối tượng phải được 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 tất cả mục tiêu của loại quy tắc này.
analysis_test giá trị mặc định là False
Nếu đúng, thì quy tắc này được coi là một thử nghiệm phân tích.

Lưu ý: Các quy tắc kiểm thử việ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 phần Kiểm thử để biết hướng dẫn.

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

  • Các 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 mà chúng có thể có.
  • Quy tắc này được xem là quy tắc kiểm thử (như thể test=True đã được đặt). Thao tác này sẽ thay thế giá trị của test
  • Chức năng triển khai quy tắc có thể không đăng ký thao tác. Thay vào đó, lớp này phải đăng ký kết quả đạt/không đạt thông qua việc cung cấp AnalysisTestResultInfo.
build_setting BuildSetting; hoặc None; giá trị 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 giá trị này, thuộc tính bắt buộc có tên là "build_setting_default" sẽ tự động được thêm vào quy tắc này, kèm theo loại tương ứng với giá trị được chuyển vào đây.
cfg giá trị mặc định là None
Nếu được đặt, các điểm đến chuyển đổi cấu hình mà quy tắc sẽ áp dụng cho cấu hình riêng 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) vào exec_group. Nếu được đặt, hãy cho phép các quy tắc chạy 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 giá trị 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 này được gọi tại thời điểm tải cho mỗi thực thể của quy tắc. Thuộc tính này được gọi bằng name và 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ụ: tags).

Phương thức này phải trả về một từ điển từ tên thuộc tính đến các 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 giá trị mặc định được chỉ định trong một đị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 định nghĩa thuộc tính (trừ trường hợp 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 bắt buộc. Bạn nên bỏ qua các chế độ cài đặt mặc định/bắt buộc trong định nghĩa thuộc tính trong những trường hợp như vậy.

Bạn nên dùng **kwargs cho các thuộc tính chưa được xử lý.

Trong trường hợp quy tắc mở rộng, tất cả các trình khởi tạo được gọi được gọi từ cấp độ 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 mà trình khởi tạo biết.

parent giá trị 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 sẽ đượ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 executabletest từ nhà xuất bản mẹ. Các giá trị của fragments, toolchains, exec_compatible_withexec_groups được hợp nhất. Không thể đặt các tham số cũ hoặc không được dùng nữa. Quá trình chuyển đổi cấu hình đến cfg của nhà xuất bản mẹ sẽ được áp dụng sau khi có cấu hình sắp tới của quy tắc này.
extendable bool; hoặc Label; 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 các quy tắc có thể mở rộng quy tắc này. Bạn cũng có thể đặt giá trị này 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 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 giúp định cấu hình thuộc tính quy tắc. Xem b bách khoa toàn thư về bản dựng để biết thông tin chi tiết.

Tham số

Thông số Mô tả
x bắt buộc
Lệnh chính ánh xạ các đ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 xác định một bản sao config_setting hoặc Constraintt_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 giá trị 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=[])

Tạo 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 một biến toàn cục trước khi có thể sử dụng.

Tham số

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

Quy tắc phụ chỉ có thể có các thuộc tính riêng tư có nhãn (ví dụ: nhãn hoặc danh sách nhãn). Các giá trị đã được 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 các đối số đã đặt tên (do đó, hàm triển khai phải chấp nhận các tham số đã đặ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 khác của nhãn
  • [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, thì tập hợp các chuỗi công cụ mà quy tắc phụ này yêu cầu. Danh sách này có thể chứa các đối tượng Chuỗi, Nhãn hoặc StarlarkToolchainTypeApi theo bất kỳ cách 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à được cung cấp cho hoạt động 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 mà quy tắc phụ này cần sử dụng.

tag_class

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

Tạo một đối tượng tag_class mới, đối tượng này 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 bằng tiện ích mô-đun.

Tham số

Thông số Mô tả
attrs giá trị mặc định là {}
Một từ điển để khai báo tất cả các thuộc tính của lớp thẻ này. Thuộc tính 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ể được 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 chi phối việc các tệp BUILD và .bzl khác có thể tải mô-đun đó hay không. (Điều 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ô-đ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ột mô-đun luôn có thể được tải trong gói của riêng nó, 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, chứ không phải bên trong hàm. Kiểu được ưu tiên là đặt lệnh gọi này ngay bên dưới 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, các lỗi vi phạm về chế độ hiển thị khi tải sẽ phát ra cảnh báo nhưng không khiến bản dựng gặp lỗi.

Tham số

Thông số 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 giống như thông số kỹ thuật của package_group, ngoại trừ việc không được phép sử dụng thông số kỹ thuật phủ định cho gói. Tức là một 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ả gói hoặc không có gói nào tương ứng

"@" không cho phép sử dụng cú pháp; tất cả thông số kỹ thuật đều đượ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 quyền hiển thị cho mô-đun này là tập hợp các gói được biểu thị theo từng thông số kỹ thuật. (Danh sách trống có tác dụng tương tự như private.) Nếu value là một chuỗi đơn, thì giá trị này được xử lý như thể đó là danh sách singleton [value].

Lưu ý cờ --incompatible_package_group_has_public_syntax--incompatible_fix_package_group_reporoot_syntax không ảnh hưởng đến đối số này. Các giá trị "public""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".