Quy tắc của nền tảng

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, exec_compatible_with, exec_properties, features, licenses, tags, testonly, visibility)

Quy tắc này dùng để đưa ra 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 constraint_setting có tên là "glibc_version" để thể hiện khả năng các nền tảng có thể cài đặt nhiều phiên bản của 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 các constraint_value có thể mở rộng được liên kết. 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ẽ đưa ra các giá trị mới cho chế độ cài đặt hiện có. Ví dụ: chế độ cài đặt định sẵn @platforms//cpu:cpu có thể được mở rộng bằng một giá trị tuỳ chỉnh để xác định một nền tảng nhắm mục tiêu đến một cấu trúc cpu không rõ ràng.

Đối số

Thuộc tính
name	Name; required Tên dành riêng cho mục tiêu này.
default_constraint_value	Name; optional; nonconfigurable Nhãn của giá trị mặc định cho chế độ cài đặt này để sử dụng nếu không cung cấp giá trị nào. Nếu có thuộc tính này, constraint_value mà nó trỏ đến phải được xác định trong cùng một gói với constraint_setting này. Nếu một chế độ cài đặt ràng buộc có giá trị mặc định, thì mỗi khi một nền tảng không bao gồm bất kỳ giá trị ràng buộc nào cho chế độ cài đặt đó, thì giá trị đó cũng giống như khi nền tảng đã chỉ định giá trị mặc định. Ngược lại, nếu không có giá trị mặc định, thì nền tảng đó sẽ xem chế độ cài đặt ràng buộc chưa được chỉ định. Trong trường hợp đó, nền tảng sẽ không so khớp với bất kỳ danh sách ràng buộc nào (chẳng hạn như đối với config_setting) yêu cầu một giá trị cụ thể cho chế độ cài đặt đó.

constraint_value

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

Quy tắc này đưa ra một giá trị mới cho một loại quy tắc ràng buộc nhất định. Để biết thêm thông tin chi tiết, hãy xem trang Nền tảng.

Ví dụ:

Đoạn mã sau đây sẽ tạo ra một giá trị mới có thể có cho constraint_value được xác định trước đại diện cho kiến trúc cpu.

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

Sau đó, các nền tảng có thể khai báo rằng chúng có cấu trúc mips thay thế cho x86_64, arm, v.v.

Đối số

Thuộc tính
name	Name; required Tên dành riêng cho mục tiêu này.
constraint_setting	Label; required; nonconfigurable Có thể sử dụng constraint_setting mà constraint_value này.

platform

platform(name, constraint_values, deprecation, distribs, exec_compatible_with, exec_properties, features, licenses, parents, remote_execution_properties, 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ác lựa chọn ràng buộc được đặt tên (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à phần bản dựng có thể chạy trong đó. Để 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 đang chạy Linux trên ARM.

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

Tính kế thừa nền tảng

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

Khi kiểm tra giá trị của một chế độ cài đặt ràng buộc trong một nền tảng, trước tiên, chúng tôi sẽ kiểm tra các giá trị được đặt trực tiếp (thông qua thuộc tính constraint_values), sau đó là các giá trị ràng buộc trên phần tử mẹ. Việc này sẽ tiếp tục đệ quy lên chuỗi nền tảng mẹ. Theo đó, 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ẹ.

Nền tảng kế thừa thuộc tính exec_properties của nền tảng mẹ. Các mục nhập 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ùng một khoá xuất hiện trong cả exec_properties của thành phần mẹ và thành phần con, thì giá trị của thành phần 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ỷ thiết lập.

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 phải 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 để đặt remote_execution_platform như sau khi có một nền tảng mẹ:

1. Nếu bạn không thiết lập 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 giá trị 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 nền tảng 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ẽ không thay đổi.

Vì remote_execution_properties không được dùng nữa và sẽ bị loại bỏ, 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ừ mẫu gốc) 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 của giá trị gốc và không đặt giá trị riêng nào.

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ự đặt.
• child_b kế thừa exec_properties của lớp cha và ghi đè giá trị của k1. exec_properties của mục này sẽ là: { "k1": "child", "k2": "v2" }.
• child_c kế thừa exec_properties của cha mẹ và không đặt k1. exec_properties của mục này sẽ là: { "k2": "v2" }.
• child_d kế thừa exec_properties của lớp cha và thêm một thuộc tính mới. exec_properties của mục này sẽ là: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Đối số

Thuộc tính
name	Name; required Tên dành riêng cho mục tiêu này.
constraint_values	List of labels; optional Sự kết hợp của các lựa chọn ràng buộc mà nền tảng này bao gồm. Để một nền tảng áp dụng được cho một môi trường nhất định, môi trường đó phải có ít nhất các giá trị trong danh sách này. Mỗi constraint_value trong danh sách này phải dành cho một constraint_setting khác nhau. Ví dụ: bạn không thể xác định một nền tảng yêu cầu cấu trúc cpu phải là cả @platforms//cpu:x86_64 và @platforms//cpu:arm.
exec_properties	Dictionary: String -> String; optional Sơ đồ các chuỗi ảnh hưởng đến cách thực thi hành động từ xa. Bazel không diễn giải điều này. Dữ liệu này được coi là dữ liệu mờ được chuyển tiếp thông qua trường Nền tảng của giao thức thực thi từ xa. Trong đó bao gồm mọi dữ liệu từ các thuộc tính exec_properties của nền tảng mẹ. Nếu nền tảng con và nền tảng mẹ xác định cùng một khoá, thì giá trị của nền tảng con sẽ được giữ nguyên. Mọi khoá liên kết với một giá trị là chuỗi trống sẽ bị xoá khỏi từ điển. Thuộc tính này thay thế hoàn toàn cho remote_execution_properties đã ngừng hoạt động.
parents	List of labels; optional Nhãn của mục tiêu platform mà nền tảng này sẽ kế thừa. Mặc dù thuộc tính này sử dụng danh sách, nhưng chỉ được có tối đa một nền tảng. Bạn có thể tìm thấy mọi quy tắc ràng buộc_cài đặt không được thiết lập trực tiếp trên nền tảng này trong nền tảng mẹ. Xem phần Tính kế thừa của nền tảng để biết thông tin chi tiết.
remote_execution_properties	String; optional KHÔNG DÙNG NỮA. Thay vào đó, vui lòng sử dụng thuộc tính exec_properties. Một chuỗi dùng để định cấu hình một nền tảng thực thi từ xa. Các bản dựng thực tế không cố gắng diễn giải điều này. Dữ liệu này được coi là dữ liệu mờ có thể được một SpawnRunner cụ thể sử dụng. Dữ liệu này có thể bao gồm dữ liệu từ thuộc tính "remote_execution_properties" của nền tảng mẹ bằng cách sử dụng macro "{PARENT_REMOTE_EXECUTION_PROPerTIES}". Xem phần Tính kế thừa của nền tảng để biết thông tin chi tiết.

chuỗi công cụ

toolchain(name, deprecation, distribs, exec_compatible_with, exec_properties, 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ể được chọn 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ố

Thuộc tính
name	Name; required Tên dành riêng cho mục tiêu này.
exec_compatible_with	List of labels; optional; nonconfigurable Một danh sách các constraint_value mà nền tảng thực thi phải đáp ứng để có thể chọn chuỗi công cụ này cho một toà nhà mục tiêu trên nền tảng đó.
target_compatible_with	List of labels; optional; nonconfigurable Danh sách các constraint_value mà nền tảng mục tiêu phải đáp ứng để có thể chọn chuỗi công cụ này cho một toà nhà mục tiêu của nền tảng đó.
target_settings	List of labels; optional Danh sách các config_setting mà cấu hình mục tiêu phải đáp ứng để được chọn chuỗi công cụ này trong quá trình phân giải chuỗi công cụ.
toolchain	Name; required Mục tiêu đại diện cho bộ công cụ hoặc bộ công cụ thực tế được cung cấp khi chọn chuỗi công cụ này.
toolchain_type	Label; required; nonconfigurable Nhãn của mục tiêu toolchain_type thể hiện vai trò mà chuỗi công cụ này phục vụ.

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ụ có cùng vai trò trên 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ụ:

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ể sử dụng thành phần 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ố

Thuộc tính
name	Name; required Tên dành riêng cho mục tiêu này.