Tệp .bzl

Báo cáo vấn đề Nightly · 8.0 . 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Các phương thức toàn cục 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 kiểm thử phân tích. Bạn chỉ có thể áp dụng quá trình chuyển đổi này trên 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ề chức 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 về 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) của lớp này để biết các phương pháp hay nhất.

Tham số

Thông số Mô tả
settings dict; bắt buộc
Một từ điển chứa thông tin về các chế độ cài đặt cấu hình sẽ được đặt bằng quá trình chuyển đổi cấu hình này. Khoá là nhãn chế độ cài đặt bản dựng và giá trị là 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 thuộc tí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 để vượt qua.

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

Aspect aspect(implementation, attr_aspects=[], toolchains_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 phương diện 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ề các khía cạnh để biết thêm thông tin chi tiết.

Tham số

Thông số Mô tả
implementation function; bắt buộc
Hàm Starlark triển khai khía cạnh này, với đúng hai tham số: Target (mục tiêu áp dụng khía cạnh) và ctx (ngữ cảnh quy tắc tạo ra mục tiêu). Bạn có thể xem các thuộc tính của mục tiêu 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 lần áp dụng 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. Phương diện này sẽ lan truyền theo các phần phụ thuộc được chỉ định trong các thuộc tính của một mục tiêu có tên như vậ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 tải cùng với tất cả các phần phụ thuộc của một mục tiêu.
toolchains_aspects trình tự; giá trị mặc định là []
Danh sách các loại chuỗi công cụ. Phương diện này sẽ truyền đến các chuỗi công cụ mục tiêu khớp với các loại chuỗi công cụ này.
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 khía cạnh. Phương thức này liên kết từ tên thuộc tính đến đối tượng thuộc tính, chẳng hạn như attr.label hoặc attr.string (xem mô-đun attr). Các 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.

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ế khía cạnh chỉ được sử dụng với các quy tắc có thuộc tính cùng tên, loại và giá trị hợp lệ theo quy định hạn chế.

Các thuộc tính đã khai báo sẽ chuyển đổi None thành giá trị mặc định.
required_providers trình tự; 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 tải chỉ đế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ị này phải là một danh sách chứa các nhà cung cấp riêng lẻ hoặc danh sách các 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ệ còn [FooInfo, BarInfo, [BazInfo, QuxInfo]] thì không.

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

Để một số quy tắc (ví dụ: some_rule) nhắm đến một khía cạnh, some_rule phải quảng cáo tất cả các nhà cung cấp trong í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ể xem các mục tiêu some_rule nếu và chỉ khi some_rule cung cấp FooInfo, hoặc BarInfo, hoặc cả BazInfo và QuxInfo.

required_aspect_providers trình tự; 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ị này phải là một danh sách chứa các nhà cung cấp riêng lẻ hoặc danh sách các 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ệ còn [FooInfo, BarInfo, [BazInfo, QuxInfo]] thì không.

Danh sách nhà cung cấp không lồng nhau sẽ tự động được chuyển đổi thành danh sách chứa một danh sách 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 phương diện khác (ví dụ: other_aspect) cho phương diện này, other_aspect phải cung cấp tất cả nhà cung cấp từ ít nhất một trong các danh sách. Trong ví dụ về [[FooInfo], [BarInfo], [BazInfo, QuxInfo]], phương diện này có thể xem other_aspect nếu và chỉ khi other_aspect cung cấp FooInfo, hoặc BarInfo, hoặc cả BazInfo và QuxInfo.

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

Sẽ xảy ra lỗi nếu hàm triển khai bỏ qua bất kỳ loại 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 bổ sung không có trong danh sách tại đâ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 trình cung cấp cũ được biểu thị bằng tên chuỗi của trình cung cấp đó.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 bắt buộc, bạn không cần chỉ định trình cung cấp đó tại đây. Chỉ cần hàm triển khai trả về giá trị này là đủ. Tuy nhiên, bạn nên chỉ định giá trị 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 phương diện yêu cầu bạn phải chỉ định nhà cung cấp tại đây.

requires trình tự của Aspect; giá trị mặc định là []
Danh sách các khía cạnh cần được truyền trước khía cạnh này.
fragments trình tự của chuỗi; giá trị mặc định là []
Danh sách tên của các mảnh cấu hình mà khía cạnh yêu cầu trong cấu hình mục tiêu.
host_fragments trình tự của chuỗi; giá trị mặc định là []
Danh sách tên của các mảnh cấu hình mà khía cạnh 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à khía cạnh này yêu cầu. Danh sách này có thể chứa các đối tượng String, Label hoặc StarlarkToolchainTypeApi, theo bất kỳ cách kết hợp nào. Bạn có thể 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à cung cấp cho quá trình triển khai khía cạnh thông qua ctx.toolchain.
incompatible_use_toolchain_transition bool; 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à nên bị xoá.
doc chuỗi; hoặc None; mặc định là None
Nội dung mô tả về 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 bool; giá trị mặc định là False
Nếu đúng, khi áp dụng cho tệp đầu ra, phương diện sẽ áp dụng cho quy tắc tạo của tệp đầu ra.

Ví dụ: giả sử một khía cạnh truyền tải gián tiếp thông qua thuộc tính "deps" và được áp dụng cho mục tiêu "alpha". Giả sử "alpha" có "deps = [':beta_output']`, trong đó "beta_output" là đầu ra đã khai báo của mục tiêu "beta". Giả sử "beta" có mục tiêu "charlie" là một trong các "deps" của nó. Nếu "apply_to_generating_rules=True" cho khía cạnh, thì khía cạnh sẽ truyền tải thông qua "alpha", "beta" và "charlie". Nếu là False, thì khía cạnh sẽ chỉ truyền tải đến "alpha".

Giá trị mặc định là false.
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ả các thực thể của khía cạnh này.
exec_groups dict; hoặc None; mặc định là None
Dict của tên nhóm thực thi (chuỗi) thành exec_groups. Nếu được đặt, cho phép các khía cạnh chạy các 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 quy tắc phụ mà khía cạnh này sử dụng.

configuration_field

LateBoundDefault configuration_field(fragment, name)

Tham chiếu đến giá trị mặc định liên kết muộn cho một thuộc tính thuộc loại label (nhãn). Một giá trị được gọi là "giới hạn trễ" nếu giá trị đó yêu cầu cấu hình được tạo trước khi xác định giá trị. Mọi thuộc tính sử dụng giá trị này 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 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 string; bắt buộc
Tên của một mảnh cấu hình chứa giá trị liên kết muộn.
name string; bắt buộc
Tên của giá trị cần lấy từ mảnh cấu hình.

depset

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

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

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

Vì tập hợp dựa trên hàm băm được dùng để loại bỏ các phần tử trùng lặp trong quá trình lặp lại, nên tất cả các phần tử của một tập hợp phần phụ thuộc phải có thể băm. Tuy nhiên, hằng số này hiện không được kiểm tra nhất quán trong tất cả hàm khởi tạo. Sử dụng cờ --incompatible_always_check_depset_elements để 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; xem Vấn đề 10313.

Ngoài ra, các phần tử hiện phải 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 nhóm phần phụ thuộc được tạo phải tương thích với thứ tự của các nhóm phần phụ thuộc transitive. Thứ tự "default" tương thích với mọi thứ tự khác, tất cả các thứ tự khác chỉ tương thích với chính chúng.

Tham số

Thông số 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 depset.
order string; mặc định là "default"
Chiến lược duyệt qua cho depset mới. Hãy xem tại đây để biết các giá trị có thể có.
transitive trình tự của nhóm phần phụ thuộc; hoặc None; mặc định là None
Danh sách các nhóm phần phụ thuộc có phần tử sẽ trở thành phần tử gián tiếp của nhóm 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 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ự; 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 String, Label 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 điều kiện ràng buộc trên nền tảng thực thi.

exec_transition

transition exec_transition(implementation, inputs, outputs)

Một phiên bản chuyên biệt của transition() dùng để xác định quá trình chuyển đổi thực thi. Hãy xem tài liệu (hoặc cách triển khai) của lớp này để biết các phương pháp hay nhất. Chỉ có thể sử dụng từ các thành phần tích hợp sẵn của Bazel.

Tham số

Thông số Mô tả
implementation có thể gọi; bắt buộc
inputs trình tự của chuỗi; bắt buộc
outputs trình tự của chuỗi; bắt buộc

macro

macro macro(implementation, attrs={}, inherit_attrs=None, finalizer=False, doc=None)

Xác định một macro tượng trưng có thể được gọi trong các tệp BUILD hoặc macro (cũ hoặc tượng trưng) để xác định các mục tiêu – có thể là nhiều mục tiêu.

Giá trị do macro(...) trả về phải được gán cho một biến toàn cục trong tệp .bzl; tên của biến toàn cục sẽ là tên của ký hiệu vĩ mô.

Hãy xem phần Macro để biết hướng dẫn toàn diện về cách sử dụng macro tượng trưng.

Tham số

Thông số Mô tả
implementation function; required
Hàm Starlark triển khai macro này. Các giá trị của thuộc tính của macro được truyền vào hàm triển khai dưới dạng đối số từ khoá. Hàm triển khai phải có ít nhất hai tham số được đặt tên là name và visibility, và nếu macro kế thừa các thuộc tính (xem inherit_attrs bên dưới), thì macro đó phải có tham số từ khoá còn lại **kwargs.

Theo quy ước, hàm triển khai phải có tham số được đặt tên cho mọi thuộc tính mà macro cần kiểm tra, sửa đổi hoặc truyền đến các mục tiêu không phải "chính", trong khi các thuộc tính kế thừa "hàng loạt" sẽ được truyền đến mục tiêu "chính" không thay đổi được truyền dưới dạng **kwargs.

Hàm triển khai không được trả về giá trị. Thay vào đó, hàm triển khai khai báo các mục tiêu bằng cách gọi quy tắc hoặc biểu tượng macro.

Tên của bất kỳ mục tiêu hoặc macro tượng trưng bên trong nào được khai báo bằng macro tượng trưng (bao gồm cả bất kỳ hàm Starlark nào mà hàm triển khai của macro gọi một cách bắc cầu) phải bằng name (đây được gọi là mục tiêu "chính") hoặc bắt đầu bằng name, theo sau là một ký tự phân cách ("_", "-" hoặc ".") và một hậu tố chuỗi. (Bạn được phép khai báo các mục tiêu vi phạm lược đồ đặt tên này, nhưng không thể tạo, định cấu hình hoặc phụ thuộc vào các mục tiêu đó.)

Theo mặc định, các mục tiêu được khai báo bằng một macro tượng trưng (bao gồm cả bất kỳ hàm Starlark nào mà hàm triển khai của macro gọi chuyển tiếp) chỉ hiển thị trong gói chứa tệp .bzl xác định macro. Để khai báo các mục tiêu hiển thị bên ngoài, bao gồm cả đối tượng gọi của macro biểu tượng, hàm triển khai phải đặt visibility một cách thích hợp – thường là bằng cách truyền visibility = visibility đến quy tắc hoặc biểu tượng macro đang được gọi.

Các API sau đây không có trong hàm triển khai macro và mọi hàm Starlark mà hàm đó gọi một cách bắc cầu:

attrs dict; mặc định là {}
Một từ điển về các thuộc tính mà macro này hỗ trợ, tương tự như rule.attrs. Khoá là tên thuộc tính và giá trị là đối tượng thuộc tính như attr.label_list(...) (xem mô-đun attr) hoặc None. Mục nhập None có nghĩa là macro không có thuộc tính theo tên đó, ngay cả khi macro đó đã kế thừa thuộc tính thông qua inherit_attrs (xem bên dưới).

Thuộc tính name đặc biệt được khai báo trước và không được đưa vào từ điển. Tên thuộc tính visibility được đặt trước và không được đưa vào từ điển.

Các thuộc tính có tên bắt đầu bằng _ là thuộc tính riêng tư – không thể truyền các thuộc tính này tại vị trí gọi của quy tắc. Bạn có thể chỉ định giá trị mặc định cho các thuộc tính như vậy (như trong attr.label(default="//pkg:foo")) để tạo một phần phụ thuộc ngầm ẩn trên nhãn.

Để giới hạn mức sử dụng bộ nhớ, có giới hạn về số lượng thuộc tính có thể khai báo.

inherit_attrs quy tắc; hoặc macro; hoặc chuỗi; hoặc None; mặc định là None
Biểu tượng quy tắc, biểu tượng macro hoặc tên của danh sách thuộc tính phổ biến tích hợp sẵn (xem bên dưới) mà từ đó macro sẽ kế thừa các thuộc tính.

Nếu inherit_attrs được đặt thành chuỗi "common", macro sẽ kế thừa các định nghĩa thuộc tính quy tắc chung mà tất cả quy tắc Starlark sử dụng.

Xin lưu ý rằng nếu giá trị trả về của rule() hoặc macro() không được gán cho một biến toàn cục trong tệp .bzl, thì giá trị đó chưa được đăng ký làm quy tắc hoặc biểu tượng macro, do đó không thể dùng cho inherit_attrs.

Cơ chế kế thừa hoạt động như sau:

  1. Các thuộc tính name và visibility đặc biệt không bao giờ được kế thừa;
  2. Các thuộc tính ẩn (những thuộc tính có tên bắt đầu bằng "_") không bao giờ được kế thừa;
  3. Các thuộc tính có tên đã được xác định trong từ điển attrs sẽ không bao giờ được kế thừa (mục trong attrs được ưu tiên; lưu ý rằng bạn có thể đặt một mục thành None để đảm bảo rằng không có thuộc tính nào có tên đó được xác định trên macro);
  4. Tất cả các thuộc tính khác được kế thừa từ quy tắc hoặc macro và được hợp nhất hiệu quả vào từ điển attrs.

Khi một thuộc tính không bắt buộc được kế thừa, giá trị mặc định của thuộc tính đó sẽ được ghi đè thành None, bất kể giá trị đó được chỉ định trong quy tắc hoặc macro ban đầu là gì. Điều này đảm bảo rằng khi macro chuyển tiếp giá trị của thuộc tính đến một thực thể của quy tắc hoặc macro được gói – chẳng hạn như bằng cách truyền vào **kwargs chưa sửa đổi – giá trị không có trong lệnh gọi của macro bên ngoài cũng sẽ không có trong lệnh gọi của quy tắc hoặc macro bên trong (vì việc truyền None đến một thuộc tính được coi giống như việc bỏ qua thuộc tính đó). Điều này rất quan trọng vì việc bỏ qua một thuộc tính có ngữ nghĩa khác biệt một chút so với việc truyền giá trị mặc định rõ ràng của thuộc tính đó. Cụ thể, các thuộc tính bị bỏ qua sẽ không xuất hiện trong một số định dạng đầu ra bazel query và giá trị mặc định được tính toán chỉ thực thi khi giá trị bị bỏ qua. Nếu macro cần kiểm tra hoặc sửa đổi một thuộc tính kế thừa – ví dụ: để thêm một giá trị vào thuộc tính tags kế thừa – bạn phải đảm bảo xử lý trường hợp None trong hàm triển khai của macro.

Ví dụ: macro sau đây kế thừa tất cả thuộc tính từ native.cc_library, ngoại trừ cxxopts (bị xoá khỏi danh sách thuộc tính) và copts (được cung cấp định nghĩa mới). Bạn cũng cần kiểm tra giá trị None mặc định của thuộc tính tags kế thừa trước khi thêm một thẻ bổ sung. 

def _my_cc_library_impl(name, visibility, tags, **kwargs):
    # Append a tag; tags attr was inherited from native.cc_library, and
    # therefore is None unless explicitly set by the caller of my_cc_library()
    my_tags = (tags or []) + ["my_custom_tag"]
    native.cc_library(
        name = name,
        visibility = visibility,
        tags = my_tags,
        **kwargs
    )

my_cc_library = macro(
    implementation = _my_cc_library_impl,
    inherit_attrs = native.cc_library,
    attrs = {
        "cxxopts": None,
        "copts": attr.string_list(default = ["-D_FOO"]),
    },
)

Nếu bạn đặt inherit_attrs, thì hàm triển khai của macro phải có tham số từ khoá còn lại **kwargs.

Theo quy ước, macro phải truyền các thuộc tính kế thừa, không bị ghi đè mà không thay đổi cho quy tắc "chính" hoặc biểu tượng macro mà macro đang gói. Thông thường, hầu hết các thuộc tính kế thừa sẽ không có tham số trong danh sách tham số của hàm triển khai và sẽ chỉ được truyền qua **kwargs. Hàm triển khai có thể thuận tiện khi có các tham số rõ ràng cho một số thuộc tính kế thừa (phổ biến nhất là tags và testonly) nếu macro cần truyền các thuộc tính đó đến cả mục tiêu "chính" và không phải "chính" – nhưng nếu macro cũng cần kiểm tra hoặc thao tác các thuộc tính đó, bạn phải cẩn thận xử lý giá trị mặc định None của các thuộc tính kế thừa không bắt buộc.

finalizer bool; mặc định là False
Liệu macro này có phải là trình hoàn tất quy tắc hay không, đây là một macro bất kể vị trí của macro đó trong tệp BUILD, được đánh giá ở cuối quá trình tải gói, sau khi tất cả các mục tiêu không phải là trình hoàn tất đã được xác định.

Không giống như các macro tượng trưng thông thường, trình kết thúc quy tắc có thể gọi native.existing_rule() và native.existing_rules() để truy vấn tập hợp các mục tiêu quy tắc không phải là trình kết thúc được xác định trong gói hiện tại. Xin lưu ý rằng native.existing_rule() và native.existing_rules() không thể truy cập vào các mục tiêu do bất kỳ trình hoàn tất quy tắc nào xác định, bao gồm cả mục tiêu này.

doc chuỗi; hoặc None; giá trị mặc định là None
Nội dung mô tả về macro có thể được trích xuất bằng các công cụ tạo tài liệu.

module_extension

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

Tạo một phần mở rộng mô-đun mới. Lưu trữ giá trị này trong một giá trị toàn cục để có thể xuất và sử dụng trong tệp MODULE.bazel bằng use_extension.

Tham số

Thông số Mô tả
implementation có thể gọi được; bắt buộc
Hàm triển khai tiện ích mô-đun này. Phải nhận một tham số duy nhất, 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ữ hiện có.
tag_classes dict; 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. Phương thức 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; mặc định là None
Nội dung mô tả về phần mở rộng 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; giá trị 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, tiện ích sẽ được đánh giá lại.
os_dependent bool; mặc định là False
Cho biết liệu tiện ích này có phụ thuộc vào hệ điều hành hay không
arch_dependent bool; mặc định là False
Cho biết liệu 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. Kết quả của hàm này phải được lưu trữ trong một giá trị toàn cục. Bạn có thể tạo thực thể của trình cung cấp bằng cách gọi trình cung cấp đó hoặc sử dụng trực tiếp làm khoá để truy xuấ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
    ...

Hãy xem phần Quy tắc (Nhà cung cấp) để biết hướng dẫn toàn diện về cách sử dụng nhà cung cấp.

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

Nếu init được chỉ định, hãy 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 phần 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.

Tham số

Thông số Mô tả
doc chuỗi; hoặc None; 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 từ điển; hoặc None; mặc định là None
Nếu được chỉ định, hãy hạn chế tập hợp các trường được phép.
Các giá trị có thể có 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 có thể 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 nhà cung cấp trong quá trình tạo bản sao. 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 trì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; hãy xem phần Quy tắc (Khởi chạy tuỳ chỉnh của trình cung cấp) để thảo luận và tìm hiểu các trường hợp sử dụng trực quan.

Hãy đặt P làm biểu tượng nhà cung cấp được tạo bằng cách gọi provider(). Về mặt khái niệm, một thực thể của P được tạo bằng cách gọi hàm 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, lỗi sẽ xảy ra.
  • 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ó trong fields, thì lỗi sẽ xảy ra.
  • Nếu không, c sẽ trả về một thực thể mới có, đối với mỗi mục k: v trong kwargs, một trường có tên là k với giá trị v.
Trong trường hợp lệnh gọi lại init không được cung cấp, lệnh gọi đến biểu tượng P sẽ đóng vai trò là lệnh gọi đến 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ẽ giúp m trở thành một thực thể MyInfo với m.foo == 1.

Tuy nhiên, trong trường hợp init được chỉ định, 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 là init(*args, **kwargs), tức là có các đối số từ khoá và vị trí giống hệt như đã truyền vào 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, lỗi sẽ 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 với các mục của d làm đối số từ khoá, như trong c(**d).

Lưu ý: các bước trên ngụ ý rằng 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 việc đánh giá nội dung của init không thành công (có thể là do chủ ý 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ẽ tổng quát hoá việc 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. Phương thức này không cho phép bỏ qua 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 giống hệt như 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ó tên bắt đầu bằng dấu gạch dưới, để 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 mới cho kho lưu trữ. Lưu trữ giá trị này trong một giá trị toàn cục để có thể tải và gọi từ hàm triển khai module_extension() hoặc được use_repo_rule() sử dụng.

Tham số

Thông số Mô tả
implementation có thể gọi; bắt buộc
hàm triển khai quy tắc này. Phải có một tham số duy nhất, 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
Một từ điển để khai báo tất cả thuộc tính của quy tắc kho lưu trữ. Phương thức này liên kết từ tên thuộc tính đến đối tượng thuộc tính (xem mô-đun attr). Các thuộc tính bắt đầu bằng _ là thuộc tính riêng tư và có thể được dùng để thêm một phần phụ thuộc ngầm ẩn trên một nhãn vào một tệp (quy tắc kho lưu trữ không thể phụ thuộc vào một cấu phần phần mềm được tạo). Thuộc tính name được thêm ngầm ẩn và không được chỉ định.

Các thuộc tính đã khai báo sẽ chuyển đổi None thành giá trị mặc định.
local bool; 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à []
Không dùng nữa. Thông số này không còn được dùng nữa. Hãy di chuyển sang repository_ctx.getenv.
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 vào. Nếu một biến môi trường trong danh sách đó thay đổi, kho lưu trữ sẽ được tìm nạp lại.
configure bool; giá trị mặc định là False
Cho biết kho lưu trữ kiểm tra hệ thống cho mục đích cấu hình
remotable bool; mặc định là False
Thử nghiệm. Tham 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 không phụ thuộc vào tính năng này. Bạn có thể bật tính năng này trên cơ sở thử nghiệm bằng cách đặt --experimental_repo_remote_exec
Tương thích với việc thực thi từ xa
doc string; hoặc None; mặc định là None
Nội dung mô tả 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=[], dependency_resolution_rule=False, exec_compatible_with=[], analysis_test=False, build_setting=None, cfg=None, exec_groups=None, initializer=None, parent=None, extendable=None, subrules=[])

Tạo một 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 gán 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.

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, chứ không áp dụng cho mục tiêu của các quy tắc đó.)

Tham số

Thông số Mô tả
implementation hàm; 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. Phương thức này 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 hành động để tạo tất cả các đầu ra đã khai báo.
test bool; mặc định là unbound
Liệu quy tắc này có phải là quy tắc kiểm thử hay không, tức là liệu quy tắc này có thể là đối tượng của lệnh blaze test hay không. Tất cả quy tắc kiểm thử đều tự động được coi là executable; bạn không cần thiết (và không nên) đặt rõ ràng executable = True cho 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à {}
Một từ điển để khai báo tất cả thuộc tính của quy tắc. Phương thức này liên kết từ tên thuộc tính đến đối tượng thuộc tính (xem mô-đun attr). Các thuộc tính bắt đầu bằng _ là thuộc tính riêng tư và có thể được dùng để thêm một phần phụ thuộc ngầm ẩn trên nhãn. Thuộc tính name được thêm ngầm ẩn 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 số thuộc tính. Để giới hạn mức sử dụng bộ nhớ, có giới hạn về số lượng thuộc tính có thể khai báo.

Các thuộc tính đã khai báo sẽ chuyển đổi None thành giá trị mặc đị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òn được dùng nữa và sẽ sớm bị xoá. Vui lòng không phụ thuộc vào tính năng 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 sắp bị xoá.
Thông số này không còn đượ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 đầu ra được khai báo trước. Không giống như các thuộc tính output và output_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ề đầ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 gọi lại 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 đượ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, ví dụ: nếu bạn truyền outputs = _my_func với định nghĩa def _my_func(srcs, deps): ..., thì hàm này sẽ có quyền truy cập vào các thuộc tính srcs và deps. Cho dù bạn chỉ định trực tiếp từ điển hay thông qua một hàm, từ điển đó sẽ được diễn giải như sau.

Mỗi mục trong từ điển tạo ra 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 đầ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 có kiểu chuỗi được thay thế nguyên văn.
  • Các thuộc tính được nhập bằng nhãn sẽ trở thành một phần của nhãn sau gói, trừ đ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 đầ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 (trong ví dụ trên là "a/b.c").
  • Tất cả thuộc tính kiểu danh sách (ví dụ: attr.label_list) dùng trong phần giữ chỗ đều phải có chính xác một phần tử. Lượt chuyển đổi của chúng giống với phiên bản không phải 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ỗ.
  • Phần giữ chỗ không phải thuộc tính đặc biệt %{dirname} và %{basename} mở rộng đến các phần đó của nhãn quy tắc, ngoại trừ gói của nhãn. Ví dụ: trong "//pkg:a/b.c", dirname là a và basename 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ột mục tiêu có tên "foo", tập hợp từ điển đầu ra {"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; 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 này có thể là đối tượng của lệnh blaze run hay không. Giá trị mặc định là False. Hãy xem trang Quy tắc để biết thêm thông tin.
output_to_genfiles bool; giá trị mặc định là False
Nếu đúng, các tệp sẽ được tạo trong thư mục genfiles thay vì thư mục bin. Trừ phi bạn cần cờ này để 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++), đừng đặt cờ này.
fragments trình tự của chuỗi; giá trị 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; giá trị 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 bool; 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 của nó để kiểm tra bằng 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().

Bạn chỉ nên sử dụng phương thức này để 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 String, Label hoặc StarlarkToolchainTypeApi, theo bất kỳ cách kết hợp nào. Bạn có thể 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à cung cấp cho quá trình triển khai quy tắc thông qua ctx.toolchain.
incompatible_use_toolchain_transition bool; 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à nên bị xoá.
doc chuỗi; hoặc None; mặc định là None
Nội dung mô tả quy tắc có thể được trích xuất bằng các công cụ tạo tài liệu.
provides trình tự; giá trị mặc định là []
Danh sách các nhà cung cấp mà hàm triển khai phải trả về.

Sẽ xảy ra lỗi nếu hàm triển khai bỏ qua bất kỳ loại 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 bổ sung không có trong danh sách tại đâ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 trình cung cấp cũ được biểu thị bằng tên chuỗi của trình cung cấp đó.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 bắt buộc, bạn không cần chỉ định trình cung cấp đó tại đây. Chỉ cần hàm triển khai trả về giá trị này là đủ. Tuy nhiên, bạn nên chỉ định giá trị 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 phương diện yêu cầu bạn phải chỉ định nhà cung cấp tại đây.

dependency_resolution_rule bool; giá trị mặc định là False
Nếu được đặt, quy tắc có thể là một phần phụ thuộc thông qua các thuộc tính cũng được đánh dấu là có trong trình tạo nội dung. Mọi thuộc tính của quy tắc có cờ này được đặt phải được đánh dấu là có trong trình tạo nội dung. Điều này là để các quy tắc được đánh dấu không thể phụ thuộc vào các quy tắc không được đánh dấu.
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ả các mục tiêu của loại quy tắc này.
analysis_test bool; 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ử 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 cốt lõi. 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 kiểm thử phân tích, thì quy tắc đó đượ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 của quy tắc đó, nhưng phải chọn một số quy định 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 coi là quy tắc kiểm thử (như thể test=True đã được đặt). Giá trị này 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 đó, bạn 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 thuộc tính này, một thuộc tính bắt buộc có tên "build_setting_default" sẽ tự động được thêm 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 quá trình chuyển đổi cấu hình mà quy tắc sẽ áp dụng cho cấu hình của chính nó trước khi phân tích.
exec_groups dict; hoặc None; mặc định là None
Dict của tên nhóm thực thi (chuỗi) thành exec_groups. Nếu được đặt, 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. 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 này được gọi tại thời điểm tải cho mỗi thực thể của quy tắc. Phương thức này được gọi bằng name và các giá trị của thuộc tính công khai do quy tắc xác định (không phải bằng 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.

Phương thức 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 chạy chứa giá trị mặc định, thì tham số đó sẽ ghi đè giá trị mặc định từ định nghĩa thuộc tính (ngoại 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 chạy 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 trên định nghĩa thuộc tính trong những trường hợp như vậy.

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 chạy đều được gọi từ phần tử con đến phần tử cấp trên. Mỗi trình khởi chạy chỉ được truyền các thuộc tính công khai mà trình khởi chạy đó biết.

parent mặc định là None
Thử nghiệm: quy tắc Stalark được mở rộng. Khi được đặ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 executable và test từ phần tử mẹ. Các giá trị của fragments, toolchains, exec_compatible_with và exec_groups được hợp nhất. Bạn không thể đặt các tham số cũ hoặc không dùng nữa. Quá trình chuyển đổi cấu hình sắp tới cfg của phần tử mẹ được áp dụng sau cấu hình sắp tới của thisrule.
extendable bool; hoặc Nhãn; hoặc chuỗi; hoặc None; 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 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 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 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 thuộc tính quy tắc có thể định cấu hình. Hãy xem phần tạo bách khoa toàn thư để biết thông tin chi tiết.

Tham số

Thông số Mô tả
x dict; bắt buộc
Một dict ánh xạ các điều kiện cấu hình đến 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 thực thể config_setting hoặc constraint_value. Hãy 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 string; giá trị mặc định là ''
Lỗi tuỳ chỉnh không bắt buộc để 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ụ. Bạn phải lưu trữ kết quả của hàm này trong một biến toàn cục thì mới 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à {}
Một 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ư thuộc loại 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 truyền vào hàm triển khai của quy tắc phụ dưới dạng đối số có tên (do đó, hàm triển khai phải chấp nhận các tham số có tên khớp với tên thuộc tính). Các loại 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ả thuộc tính nhãn khác
  • [Target] cho tất cả các thuộc tính danh sách nhãn
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 phụ này yêu cầu. Danh sách này có thể chứa các đối tượng String, Label hoặc StarlarkToolchainTypeApi, theo bất kỳ cách kết hợp nào. Bạn có thể 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à cung cấp cho quá trình triển khai quy tắc phụ thông qua ctx.toolchains. Xin lưu ý rằng bạn cần bật AEG trên(các) quy tắc sử dụng nếu đặt tham số này. Trong trường hợp bạn chưa di chuyển sang AEG, hãy xem https://bazel.build/extending/auto-exec-groups#migration-aegs.
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.

tag_class

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

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

Tham số

Thông số Mô tả
attrs dict; giá trị mặc định là {}
. Một từ điển để khai báo tất cả thuộc tính của lớp thẻ này. Phương thức này liên kết từ tên thuộc tính đến đối tượng thuộc tính (xem mô-đun attr).

Xin lưu ý rằng không giống như rule(), aspect() và repository_rule(), các thuộc tính đã khai báo sẽ không chuyển đổi None thành giá trị mặc định. Để sử dụng giá trị mặc định, phương thức gọi phải bỏ qua hoàn toàn thuộc tính này.
doc chuỗi; 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 đang được khởi chạy.

Mức độ hiển thị tải của một mô-đun sẽ quyết định liệu 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 quản lý 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 đang tải phải nằm trong một gói đã được cấp quyền hiển thị cho mô-đun đó. Bạn luôn có thể tải một mô-đun trong gói của chính mô-đun đó, bất kể chế độ hiển thị của mô-đun.

Bạn chỉ có thể gọi visibility() 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 một hàm. Bạn nên đặ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 hỏng bản dựng.

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.

Quy cách gói tuân theo định dạng tương tự như package_group, ngoại trừ việc không cho phép quy cách gói âm. 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ương ứng là tất cả gói hoặc không có gói nào

Không được 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à danh sách các 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ị bằng từng thông số kỹ thuật. (Danh sách trống có tác dụng giống như private.) Nếu value là một chuỗi đơn, thì chuỗi này được coi như danh sách singleton [value].

Xin 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 diễn giải là "tất cả các gói trong kho lưu trữ hiện tại".