Trang này được dịch bởi Cloud Translation API.

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 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 cần làm quen với các khái niệm được giải thích tại đây.

constraint_setting

Xem nguồn quy tắc

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 constraint_setting có tên là "glibc_version" để thể hiện khả năng cài đặt nhiều phiên bản thư viện glibc cho các nền tảng. Để 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 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ẽ đưa ra 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 được xác định trước @platforms//cpu:cpu bằng một giá trị tuỳ chỉnh để xác định một nền tảng nhắm đến một cấu trúc CPU ít người biết.

Đối số

Thuộc tính

name

Tên; bắt buộc

Tên duy nhất cho mục tiêu này.

default_constraint_value

Tên; không thể định cấu hình; giá trị mặc định là None

Nhãn của giá trị mặc định cho chế độ cài đặt này và sử dụng nếu không có giá trị nào được cung cấp. Nếu có thuộc tính này, constraint_value mà thuộc tính này 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 quy tắc ràng buộc có giá trị mặc định, thì bất cứ khi nào một nền tảng không bao gồm giá trị quy tắc ràng buộc nào cho chế độ cài đặt đó, thì điều đó 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ì chế độ cài đặt quy tắc ràng buộc sẽ được nền tảng đó 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 quy tắc 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

Xem nguồn quy tắc

constraint_value(name, constraint_setting, deprecation, distribs, 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 một giá trị mới có thể sử dụng 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",
)

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 tính

name

Tên; bắt buộc

Tên duy nhất cho mục tiêu này.

constraint_setting

Nhãn; không thể định cấu hình; bắt buộc

constraint_setting mà constraint_value này là một lựa chọn có thể thực hiện.

platform

Xem nguồn quy tắc

platform(name, constraint_values, deprecation, distribs, 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ê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. Để 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",
    ],
)

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à từ đó 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 danh sách, nhưng hiện tại hệ thống không hỗ trợ nhiều giá trị duy nhất và việc chỉ định nhiều giá trị gốc sẽ 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) 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ẹ. 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, mọi 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 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 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 nhà xuất bản mẹ và của nhà xuất bản con, thì giá trị của nhà xuất bả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ỷ đặ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 sẽ sử dụng exec_properties. Logic mô tả dưới đây vẫn đượ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ẹ:

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.
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 thuộc tính remote_execution_property của phần tử mẹ.
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 nhà xuất bản 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ẽ bị loại bỏ, nên việc kết hợp remote_execution_properties và exec_properties trong cùng một chuỗi kế thừa là không được phép. Muố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ừ 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ừ thành phần mẹ và không thiết lập bất kỳ giá trị ràng buộc 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 riêng mình.
child_b kế thừa exec_properties của phần tử mẹ và ghi đè giá trị của k1. exec_properties của đơn vị quảng cáo này sẽ là: { "k1": "child", "k2": "v2" }.
child_c kế thừa exec_properties của nhà xuất bản mẹ và huỷ đặt k1. exec_properties của đơn vị quảng cáo 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 thuộc tính mới. exec_properties của đơn vị quảng cáo này sẽ là: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Đối số

Thuộc tính
`name`	Tên; bắt buộc Tên duy nhất cho mục tiêu này.
`constraint_values`	Danh sách nhãn; không thể định cấu hình; giá trị mặc định là `[]` 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 có thể áp dụng 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. Ví dụ: bạn không thể xác định một nền tảng yêu cầu kiến trúc CPU phải là cả `@platforms//cpu:x86_64` và `@platforms//cpu:arm`.
`exec_properties`	Từ điển: Chuỗi -> Chuỗi; không thể định cấu hình; mặc định là `{}` Sơ đồ liên kết các chuỗi ảnh hưởng đến cách thực thi các thao tác từ xa. Bazel không cố gắng diễn giải điều này. Bazel coi dữ liệu này 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. Dữ liệu này bao gồm mọi dữ liệu từ các thuộc tính `exec_properties` của nền tảng gốc. Nếu nền tảng con và nền tảng mẹ xác định các khoá giống nhau, thì các giá trị của nền tảng con sẽ được giữ lại. 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`	Danh sách nhãn; không thể định cấu hình; giá trị mặc định là `[]` Nhãn của mục tiêu `platform` mà nền tảng này cần kế thừa. Mặc dù thuộc tính này lấy một danh sách, nhưng không được xuất hiện quá một nền tảng. Bạn sẽ tìm thấy mọi Constraintt_settings 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ẹ. Hãy 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`	Chuỗi; không thể định cấu hình; giá trị mặc định là `""` ĐÃ NGỪNG HOẠT ĐỘNG. 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 nền tảng thực thi từ xa. Các bản dựng thực tế sẽ 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ờ mà một SpawnRunner cụ thể 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 gốc, bằng cách sử dụng macro "{PARENT_REMOTE_EXECUTION_PROPERTIES}". Hãy 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ụ

Xem nguồn quy tắ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 một loại chuỗi công cụ cụ thể và các điều kiện ràng buộc để có thể chọn loại chuỗi công cụ đó trong quá trình phân giải chuỗi công cụ. Vui lòng xem trang Chuỗi công cụ để biết thêm thông tin chi tiết.

Đối số

Thuộc tính
`name`	Tên; bắt buộc Tên duy nhất cho mục tiêu này.
`exec_compatible_with`	Danh sách nhãn; không thể định cấu hình; giá trị mặc định là `[]` 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 bản dựng mục tiêu trên nền tảng đó.
`target_compatible_with`	Danh sách nhãn; không thể định cấu hình; giá trị mặc định là `[]` 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 bản dựng mục tiêu cho nền tảng đó.
`target_settings`	Danh sách nhãn; mặc định là `[]` Danh sách các `config_setting` mà cấu hình mục tiêu phải đáp ứng để có thể chọn chuỗi công cụ này trong quá trình phân giải chuỗi công cụ.
`toolchain`	Tên; bắt buộc Mục tiêu đại diện cho bộ công cụ hoặc bộ công cụ thực tế được tạo sẵn khi bạn chọn chuỗi công cụ này.
`toolchain_type`	Nhãn; không thể định cấu hình; bắt buộc Nhãn của mục tiêu `toolchain_type` thể hiện vai trò mà chuỗi công cụ này phân phát.

toolchain_type

Xem nguồn quy tắc

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ụ phục vụ cùng vai trò 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ố

Thuộc tính

name

Tên; bắt buộc

Tên duy nhất cho mục tiêu này.