Tệp .bzl

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

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

Các thuộc tính được khai báo sẽ chuyển đổi None thành giá trị mặc định.

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ả nhà cung cấp trong ít nhất một 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 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 khía cạnh khác (ví dụ: other_aspect) cho khía cạnh này, other_aspect phải cung cấp tất cả các nhà cung cấp từ í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 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 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 trì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 nhà cung cấp cũ được biểu thị bằng tên chuỗi của nhà cung cấp đó.Khi mục tiêu của quy tắc được dùng làm phần phụ thuộc cho mục tiêu khai báo nhà cung cấp bắt buộc, bạn không cần chỉ định nhà cung cấp đó ở đây. Hàm triển khai trả về là đủ. Tuy nhiên, bạn nên chỉ định tham số này (mặc dù không bắt buộc). Tuy nhiên, trường required_providers của khía cạnh 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 bá một cách bắc cầu 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à một đầ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". Nếu "apply_to_generating_rules=True" cho khía cạnh, thì khía cạnh sẽ truyền bá thông qua "alpha", "beta" và "charlie". Nếu là False, thì khía cạnh sẽ chỉ truyền bá đến "alpha".

Theo mặc định là False.

Theo quy ước, hàm triển khai phải có một 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 là "chính", trong khi các thuộc tính được kế thừa "hàng loạt" sẽ được truyền đến mục tiêu "chính" mà không thay đổi sẽ đượ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 các biểu tượng quy tắc hoặc macro.

Tên của mọi mục tiêu hoặc macro tượng trưng bên trong do một macro tượng trưng khai báo (kể cả bằng bất kỳ hàm Starlark nào mà hàm triển khai của macro gọi một cách gián tiếp) 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ó thể khai báo các mục tiêu vi phạm quy tắ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 do một macro tượng trưng khai báo (kể cả bằng 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) 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 có thể nhìn thấy bên ngoài, bao gồm cả người gọi macro tượng trư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 gián tiếp:

• package(), licenses()
• environment_group()
• native.glob() – thay vào đó, bạn có thể truyền một glob vào macro thông qua thuộc tính danh sách nhãn
• native.subpackages()
• (chỉ được phép trong các quy tắc kết thúc, xem finalizer bên dưới) native.existing_rules(), native.existing_rule()
• (cho WORKSPACE luồng) workspace(), register_toolchains(), register_execution_platforms(), bind(), khởi tạo quy tắc kho lưu trữ

Thuộc tính đặc biệt name được khai báo trước và không được đưa vào từ điển. Tên thuộc tính visibility được dành riêng 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à riêng tư – chúng không thể được truyền tại trang web gọi của quy tắc. Bạn có thể chỉ định một 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 trên một nhãn.

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

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ả các quy tắc Starlark đều sử dụng.

Xin lưu ý rằng nếu giá trị trả về của rule() hoặc macro() không được chỉ định cho một biến toàn cục trong tệp .bzl, thì giá trị đó sẽ không được đăng ký làm biểu tượng quy tắc hoặc macro, và 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 đặc biệt name và visibility 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 "_") sẽ 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 sẽ đượ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 theo tên đó được xác định trên macro);
4. Tất cả các thuộc tính khác đều được kế thừa từ quy tắc hoặc macro và được hợp nhất một cách 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ẽ bị ghi đè thành None, bất kể giá trị đó được chỉ định trong quy tắc hoặc macro ban đầu. Đ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 phiên bản của quy tắc hoặc macro được bao bọc – chẳng hạn như bằng cách truyền vào **kwargs chưa sửa đổi – một giá trị không có trong lệnh gọi macro bên ngoài cũng sẽ không có trong lệnh gọi quy tắc hoặc macro bên trong (vì việc truyền None đến một thuộc tính được coi là tương tự 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 tinh 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à các 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 được kế thừa – ví dụ: để thêm một giá trị vào thuộc tính tags được 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ả cá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 đưa ra một định nghĩa mới). Thao tác này cũng kiểm tra giá trị None mặc định của thuộc tính tags được 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ó một tham số từ khoá còn lại **kwargs.

Theo quy ước, một macro sẽ truyền các thuộc tính không bị ghi đè và được kế thừa mà không thay đổi đến biểu tượng quy tắc hoặc macro "chính" mà macro đang bao bọc. Thông thường, hầu hết các thuộc tính được 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ể có các tham số rõ ràng cho một số thuộc tính được kế thừa (thường gặp 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 được kế thừa không bắt buộc.

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 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 kết thúc quy tắc nào xác định, kể cả trình kết thúc này.

• danh sách các 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 Quy tắc (Khởi tạo tuỳ chỉnh nhà cung cấp) để biết nội dung thảo luận và các trường hợp sử dụng trực quan.

Giả sử P là 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 phiên bản của P được tạo bằng cách gọi hàm dựng 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 trống, thì sẽ xảy ra lỗi.
• Nếu tham số fields được chỉ định khi provider() được gọi và nếu kwargs chứa bất kỳ khoá nào không có trong fields, thì sẽ xảy ra lỗi.
• Nếu không, c sẽ trả về một phiên bản 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)

Nhưng 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. Hàm gọi lại được gọi là 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 dự kiến là một từ điển, d, có các khoá là chuỗi tên trường. Nếu không, lỗi sẽ xảy ra.
3. Một phiên bản 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 quá trình đánh giá nội dung của init không thành công (có thể là cố ý thông qua lệnh gọi đến fail()), hoặc nếu giá trị trả về của init không phải là một từ điển có giản đồ dự kiến.

Bằng cách này, lệnh gọi lại init sẽ khái quát hoá 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ế độ này không cho phép bạn lách 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ộ (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ó tên bắt đầu bằng dấu gạch dưới, để chỉ tệp .bzl hiện tại có quyền truy cập trực tiếp vào biến đó:

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

Các thuộc tính được khai báo sẽ chuyển đổi None thành giá trị mặc định.

Các thuộc tính được khai báo sẽ chuyển đổi None thành giá trị mặc định.

Một giản đồ để xác định các đầ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ề các đầ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. Callback hoạt động tương tự như các thuộc tính phụ thuộc được tính toán: Tên tham số của hàm được so khớp với các thuộc tính của quy tắc, vì vậy, ví dụ: nếu bạn truyền outputs = _my_func bằng định nghĩa def _my_func(srcs, deps): ..., hàm sẽ có quyền truy cập vào các thuộc tính srcs và deps. Cho dù từ điển được chỉ định trực tiếp hay thông qua một hàm, từ điển đó sẽ được diễn giải như sau.

Mỗi mục trong từ điển sẽ 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ó dạng chuỗi văn bản được thay thế nguyên văn.
• Các thuộc tính được gắn nhãn sẽ trở thành một phần của nhãn sau gói, trừ phần đuôi tệp. Ví dụ: nhãn "//pkg:a/b.c" sẽ trở thành "a/b".
• Các thuộc tính được nhập theo kiểu sẽ trở thành một phần của nhãn sau gói, bao gồm cả đuôi tệp (đối với ví dụ trên, "a/b.c").
• Tất cả các thuộc tính có kiểu danh sách (ví dụ: attr.label_list) được 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 các phiên bản này giống với phiên bản không có 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 thành những phần đó của nhãn trong quy tắc, ngoại trừ gói. Ví dụ: trong "//pkg:a/b.c", dirname là a và basename là b.c.

Trên 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 là "foo", từ điển đầu ra {"bin": "%{name}.exe"} sẽ khai báo trước một đầu ra có tên là foo.exe có thể truy cập 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 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 trì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 nhà cung cấp cũ được biểu thị bằng tên chuỗi của nhà cung cấp đó.Khi mục tiêu của quy tắc được dùng làm phần phụ thuộc cho mục tiêu khai báo nhà cung cấp bắt buộc, bạn không cần chỉ định nhà cung cấp đó ở đây. Hàm triển khai trả về là đủ. Tuy nhiên, bạn nên chỉ định tham số này (mặc dù không bắt buộc). Tuy nhiên, trường required_providers của khía cạnh 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ó trong các thư viện Starlark cốt lõi. Hãy xem phần Thử nghiệm để biết hướng dẫn.

Nếu được xác định là quy tắc kiểm thử phân tích, thì quy tắc sẽ được phép sử dụng các quá trình 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 sẽ chọn áp dụng một số hạn chế:

• Số lượng phần phụ thuộc bắc cầu mà các mục tiêu của quy tắc này có thể có bị giới hạn.
• Quy tắc này được coi là quy tắc kiểm thử (như thể bạn đã đặt test=True). Giá trị này sẽ thay thế giá trị của test
• Hàm triển khai quy tắc có thể không đăng ký các thao tác. Thay vào đó, 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 phiên bản 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 các thuộc tính chung, ví dụ: tags).

Thao tá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. Những thuộc tính không được trả về sẽ không bị ảnh hưởng. Trả về None dưới dạng giá trị sẽ dẫn đến việc sử dụng giá trị mặc định được chỉ định trong định nghĩa thuộc tính.

Trình khởi tạo được đánh giá trước các giá trị mặc định được chỉ định trong 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ừ phi trả về None).

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

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

Trong trường hợp có các quy tắc mở rộng, tất cả các trình khởi tạo đều được gọi theo thứ tự từ phần tử con đến phần tử 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.

Các quy tắc phụ chỉ có thể có những thuộc tính riêng tư được nhập nhãn (tức là nhãn hoặc danh sách nhãn). Bazel sẽ tự động truyền các giá trị đã phân giải tương ứng với các nhãn này đến 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 cho tất cả các thuộc tính nhãn khác
• [Target] cho tất cả thuộc tính label-list

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, người gọi phải bỏ qua hoàn toàn thuộc tính này.

Quy cách gói có cùng định dạng như đối với package_group, ngoại trừ việc không được phép sử dụng quy cách gói âm. Tức là một quy cách có thể có các dạng sau:

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

Không được dùng cú pháp "@"; mọi 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 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à hợp của các gói do từng quy cách đại diện. (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ì chuỗi đó sẽ được coi như thể là danh sách singleton [value].

Xin lưu ý rằng các 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, còn "//..." luôn được diễn giải là "tất cả các gói trong kho lưu trữ hiện tại".