Tệp .bzl

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ế đó.

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 và QuxInfo.

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 và QuxInfo.

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.

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.

• 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' })

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.

MyInfo = provider()
m = MyInfo(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 đó r là hà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 = ...)

Giản đồ để xác định các đầ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 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 tạo ra 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 srcs và deps. 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} và %{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.

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.

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.

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 không đượ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.

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 đố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

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 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".