Quy tắc cho nền tảng và chuỗi công cụ

Tập hợp quy tắc này cho phép bạn lập mô hình các nền tảng phần cứng cụ thể mà bạn đang xây dựng và chỉ định các công cụ cụ thể mà bạn có thể cần để biên dịch mã cho các nền tảng đó. Người dùng phải nắm rõ các khái niệm được giải thích tại đây.

Quy tắc

• constraint_setting
• constraint_value
• nền tảng
• chuỗi công cụ
• toolchain_type

constraint_setting

constraint_setting(name, default_constraint_value, deprecation, distribs, features, licenses, tags, testonly, visibility)

Quy tắc này được dùng để giới thiệu một loại quy tắc ràng buộc mới mà nền tảng có thể chỉ định một giá trị. Ví dụ: bạn có thể xác định một constraint_setting có tên là "glibc_version" để biểu thị khả năng các nền tảng có thể cài đặt nhiều phiên bản thư viện glibc. Để biết thêm thông tin chi tiết, hãy xem trang Nền tảng.

Mỗi constraint_setting có một tập hợp constraint_value được liên kết có thể mở rộng. Thông thường, các giá trị này được xác định trong cùng một gói, nhưng đôi khi một gói khác sẽ giới thiệu các giá trị mới cho một chế độ cài đặt hiện có. Ví dụ: bạn có thể mở rộng chế độ cài đặt @platforms//cpu:cpu được xác định trước bằng một giá trị tuỳ chỉnh để xác định một nền tảng nhắm đến cấu trúc CPU không rõ ràng.

Đối số

constraint_value

constraint_value(name, constraint_setting, deprecation, distribs, features, licenses, tags, testonly, visibility)

Ví dụ:

Phần sau đây sẽ tạo một giá trị mới có thể có cho constraint_value được xác định trước đại diện cho cấu trúc CPU.

constraint_value(
    name = "mips",
    constraint_setting = "@platforms//cpu:cpu",
)

Đối số

platform

platform(name, constraint_values, deprecation, distribs, exec_properties, features, flags, licenses, parents, remote_execution_properties, required_settings, tags, testonly, visibility)

Quy tắc này xác định một nền tảng mới – một tập hợp có tên gồm các lựa chọn ràng buộc (chẳng hạn như cấu trúc CPU hoặc phiên bản trình biên dịch) mô tả một môi trường mà một phần của bản dựng có thể chạy. Để biết thêm thông tin chi tiết, hãy xem trang Nền tảng.

Ví dụ:

Thao tác này xác định một nền tảng mô tả mọi môi trường chạy Linux trên ARM.

platform(
    name = "linux_arm",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)

Cờ nền tảng

Các nền tảng có thể sử dụng thuộc tính flags để chỉ định danh sách cờ sẽ được thêm vào cấu hình bất cứ khi nào nền tảng được dùng làm nền tảng mục tiêu (tức là làm giá trị của cờ --platforms).

Các cờ được đặt từ nền tảng có mức độ ưu tiên cao nhất và ghi đè mọi giá trị trước đó của cờ đó, từ dòng lệnh, tệp rc hoặc quá trình chuyển đổi.

Ví dụ:

platform(
    name = "foo",
    flags = [
        "--dynamic_mode=fully",
        "--//bool_flag",
        "--no//package:other_bool_flag",
    ],
)

Thao tác này xác định một nền tảng có tên là foo. Khi đây là nền tảng mục tiêu (do người dùng chỉ định --platforms//:foo, do một quá trình chuyển đổi đặt cờ //command_line_option:platforms thành ["//:foo"] hoặc do //:foo được dùng làm nền tảng thực thi), thì các cờ đã cho sẽ được đặt trong cấu hình.

Nền tảng và cờ có thể lặp lại

Một số cờ sẽ tích luỹ các giá trị khi chúng được lặp lại, chẳng hạn như --features, --copt, bất kỳ cờ Starlark nào được tạo dưới dạng config.string(repeatable = True). Các cờ này không tương thích với việc đặt cờ từ nền tảng: thay vào đó, tất cả giá trị trước đó sẽ bị xoá và ghi đè bằng các giá trị từ nền tảng.

Ví dụ: với nền tảng sau, lệnh gọi build --platforms=//:repeat_demo --features feature_a --features feature_b sẽ kết thúc bằng giá trị của cờ --feature là ["feature_c", "feature_d"], xoá các tính năng được đặt trên dòng lệnh.

platform(
    name = "repeat_demo",
    flags = [
        "--features=feature_c",
        "--features=feature_d",
    ],
)

Vì lý do này, bạn không nên sử dụng cờ có thể lặp lại trong thuộc tính flags.

Kế thừa nền tảng

Các nền tảng có thể sử dụng thuộc tính parents để chỉ định một nền tảng khác mà từ đó các nền tảng này sẽ kế thừa các giá trị ràng buộc. Mặc dù thuộc tính parents lấy một danh sách, nhưng hiện không hỗ trợ nhiều giá trị và việc chỉ định nhiều thành phần mẹ là một lỗi.

Khi kiểm tra giá trị của chế độ cài đặt quy tắc ràng buộc trong một nền tảng, trước tiên, các giá trị được đặt trực tiếp (thông qua thuộc tính constraint_values) sẽ được kiểm tra, sau đó là các giá trị quy tắc ràng buộc trên thành phần mẹ. Quá trình này tiếp tục đệ quy lên chuỗi các nền tảng mẹ. Theo cách này, mọi giá trị được đặt trực tiếp trên một nền tảng sẽ ghi đè các giá trị được đặt trên nền tảng mẹ.

Các nền tảng kế thừa thuộc tính exec_properties từ nền tảng mẹ. Các mục từ điển trong exec_properties của nền tảng mẹ và con sẽ được kết hợp. Nếu cùng một khoá xuất hiện trong cả exec_properties của phần tử mẹ và phần tử con, thì giá trị của phần tử con sẽ được sử dụng. Nếu nền tảng con chỉ định một chuỗi trống làm giá trị, thì thuộc tính tương ứng sẽ không được đặt.

Các nền tảng cũng có thể kế thừa thuộc tính remote_execution_properties (không dùng nữa) từ nền tảng mẹ. Lưu ý: mã mới nên sử dụng exec_properties. Logic được mô tả bên dưới được duy trì để tương thích với hành vi cũ nhưng sẽ bị xoá trong tương lai. Logic để thiết lập remote_execution_platform như sau khi có nền tảng mẹ:

1. Nếu bạn không đặt remote_execution_property trên nền tảng con, thì remote_execution_properties của nền tảng mẹ sẽ được sử dụng.
2. Nếu remote_execution_property được đặt trên nền tảng con và chứa chuỗi cố định {PARENT_REMOTE_EXECUTION_PROPERTIES}, thì macro đó sẽ được thay thế bằng nội dung của thuộc tính remote_execution_property của thành phần mẹ.
3. Nếu remote_execution_property được đặt trên nền tảng con và không chứa macro, thì remote_execution_property của nền tảng con sẽ được sử dụng không thay đổi.

Vì remote_execution_properties không còn được dùng nữa và sẽ ngừng hoạt động, nên bạn không được phép kết hợp remote_execution_properties và exec_properties trong cùng một chuỗi kế thừa. Ưu tiên sử dụng exec_properties thay vì remote_execution_properties không dùng nữa.

Ví dụ: Giá trị ràng buộc

platform(
    name = "parent",
    constraint_values = [
        "@platforms//os:linux",
        "@platforms//cpu:arm",
    ],
)
platform(
    name = "child_a",
    parents = [":parent"],
    constraint_values = [
        "@platforms//cpu:x86_64",
    ],
)
platform(
    name = "child_b",
    parents = [":parent"],
)

Trong ví dụ này, các nền tảng con có các thuộc tính sau:

• child_a có các giá trị ràng buộc @platforms//os:linux (kế thừa từ thành phần mẹ) và @platforms//cpu:x86_64 (được đặt trực tiếp trên nền tảng).
• child_b kế thừa tất cả giá trị ràng buộc từ thành phần mẹ và không đặt giá trị nào của riêng mình.

Ví dụ: Thuộc tính thực thi

platform(
    name = "parent",
    exec_properties = {
      "k1": "v1",
      "k2": "v2",
    },
)
platform(
    name = "child_a",
    parents = [":parent"],
)
platform(
    name = "child_b",
    parents = [":parent"],
    exec_properties = {
      "k1": "child"
    }
)
platform(
    name = "child_c",
    parents = [":parent"],
    exec_properties = {
      "k1": ""
    }
)
platform(
    name = "child_d",
    parents = [":parent"],
    exec_properties = {
      "k3": "v3"
    }
)

Trong ví dụ này, các nền tảng con có các thuộc tính sau:

• child_a kế thừa "exec_properties" của phần tử mẹ và không đặt thuộc tính riêng.
• child_b kế thừa exec_properties của thành phần mẹ và ghi đè giá trị của k1. exec_properties của lớp này sẽ là: { "k1": "child", "k2": "v2" }.
• child_c kế thừa exec_properties của thành phần mẹ và huỷ thiết lập k1. exec_properties của lớp này sẽ là: { "k2": "v2" }.
• child_d kế thừa exec_properties của thành phần mẹ và thêm một thuộc tính mới. exec_properties của lớp này sẽ là: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Đối số

chuỗi công cụ

toolchain(name, deprecation, distribs, exec_compatible_with, features, licenses, tags, target_compatible_with, target_settings, testonly, toolchain, toolchain_type, visibility)

Quy tắc này khai báo loại và các quy tắc ràng buộc của một chuỗi công cụ cụ thể để có thể chọn chuỗi công cụ đó trong quá trình phân giải chuỗi công cụ. Hãy xem trang Chuỗi công cụ để biết thêm thông tin chi tiết.

Đối số

toolchain_type

toolchain_type(name, compatible_with, deprecation, features, restricted_to, tags, target_compatible_with, testonly, visibility)

Quy tắc này xác định một loại chuỗi công cụ mới – một mục tiêu đơn giản đại diện cho một lớp công cụ đóng vai trò giống nhau cho nhiều nền tảng.

Hãy xem trang Chuỗi công cụ để biết thêm thông tin chi tiết.

Ví dụ:

Thuộc tính này xác định loại chuỗi công cụ cho một quy tắc tuỳ chỉnh.

toolchain_type(
    name = "bar_toolchain_type",
)

Bạn có thể sử dụng tệp này trong tệp bzl.

bar_binary = rule(
    implementation = _bar_binary_impl,
    attrs = {
        "srcs": attr.label_list(allow_files = True),
        ...
        # No `_compiler` attribute anymore.
    },
    toolchains = ["//bar_tools:toolchain_type"]
)

Đối số