Tệp .bzl

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

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.

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.

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.

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.

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

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.

MyInfo = provider()
m = MyInfo(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 = ...)

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.

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.

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.

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 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 các thuộc tính chung, ví dụ: name hoặc 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.

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

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