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

Bộ quy tắc này tồn tại để 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 sử dụng tạo 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 cần làm quen với 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 dùng để ra mắt 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ài đặt các phiên bản khác nhau của thư viện glibc cho các nền tảng. Để biết thêm chi tiết, hãy xem Trang Nền tảng.

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

Đối số

constraint_value

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

Ví dụ:

Thao tác sau sẽ tạo ra một giá trị mới có thể có cho constraint_value được xác định trước biểu thị 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 – tập hợp các lựa chọn quy tắc ràng buộc được đặt tên (chẳng hạn như kiến trúc cpu hoặc phiên bản trình biên dịch) mô tả một môi trường trong phần nào 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ụ:

Định nghĩa này định nghĩa 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ờ trên nền tảng

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

Cờ được đặt từ nền tảng có mức độ ưu tiên cao nhất và sẽ ghi đè mọi cờ trước đó cho cờ đó, từ dòng lệnh, tệp rc hoặc 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 (vì người dùng đã chỉ định --platforms//:foo vì một hiệu ứng chuyển đổi sẽ thiết lập //command_line_option:platforms gắn cờ thành ["//:foo"] hoặc vì //:foo được dùng làm nền tảng thực thi), sau đó các cờ đã cho sẽ được đặt trong .

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

Một số cờ sẽ tích luỹ các giá trị khi đượ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). Những 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ả cờ trước đó sẽ bị loại bỏ 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"], sẽ xoá các tính năng này được thiết lập 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.

Tính kế thừa củ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à họ sẽ kế thừa các giá trị ràng buộc từ đó. Mặc dù thuộc tính parents lấy danh sách, nhưng không hiện có nhiều hơn một giá trị đơn lẻ được hỗ trợ và việc chỉ định nhiều giá trị gốc là một lỗi.

Khi kiểm tra giá trị của một 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) được kiểm tra, sau đó các giá trị ràng buộc trên phần tử mẹ. Thao tác này tiếp tục đệ quy lên chuỗi các nền tảng mẹ. Bằng cách này, bất kỳ các giá trị được thiết lập trực tiếp trên một nền tảng sẽ ghi đè các giá trị được thiết lập trong đơn vị quảng cáo mẹ.

Nền tảng kế thừa thuộc tính exec_properties của nền tảng mẹ. Các mục từ điển trong exec_properties của nền tảng mẹ và nền tảng con sẽ được kết hợp. Nếu có cùng một khoá xuất hiện trong cả exec_properties của nhà xuất bản mẹ và nhà xuất bản con, 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ẽ bị huỷ đặ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 gốc. Lưu ý: mã mới sẽ sử dụng exec_properties. Chiến lược phát hành đĩa đơn logic 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 để đặt remote_execution_platform như sau khi có là nền tảng gốc:

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

Vì remote_execution_properties không được dùng nữa và sẽ bị loại bỏ, nên việc kết hợp remote_execution_properties và exec_properties trong cùng một thiết bị chuỗi kế thừa. Muốn sử dụng exec_properties thay vì những giá trị không dùng nữa remote_execution_properties

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ừ cấp độ gốc) và @platforms//cpu:x86_64 (được đặt trực tiếp trên nền tảng).
• child_b kế thừa mọi giá trị ràng buộc từ cấp độ gốc và không đặt bất kỳ giá trị nào của chính nó.

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 thành phần mẹ và không đặt giá trị của chính nó.
• child_b kế thừa exec_properties của thành phần mẹ và ghi đè phương thức giá trị của k1. exec_properties của thành phần này sẽ là: { "k1": "child", "k2": "v2" }
• child_c kế thừa exec_properties của nhà xuất bản mẹ nhưng không đặt k1. exec_properties của thành phần này sẽ là: { "k2": "v2" }
• child_d kế thừa exec_properties của nhà xuất bản mẹ và thêm một phương thức mới thuộc tính này. exec_properties của thành phần 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 chuỗi công cụ cụ thể và các điều kiện ràng buộc để bạn có thể chọn chuỗi công cụ trong quá trình phân giải chuỗi công cụ. Xem Trang Chuỗi công cụ để tìm hiểu thêm 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ụ đều đóng vai trò như nhau cho các nền tảng khác nhau.

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

Ví dụ:

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

toolchain_type(
    name = "bar_toolchain_type",
)

Bạn có thể dùng mục 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ố