Chúng tôi hiện đang nhận đơn đăng ký và CFP cho BazelCon 2025!

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áo cáo vấn đề Xem nguồn Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

Tập hợp quy tắc này giúp bạn mô hình hoá 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 những 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.

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 được dùng để giới thiệu một loại ràng buộc mới mà nền tảng có thể chỉ định 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ó nhiều phiên bản thư viện glibc được cài đặt. Để 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ó 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ẽ 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 đượ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 không rõ ràng.

Đối số

Thuộc tính

name

Tên; bắt buộc

Tên riêng cho mục tiêu này.

default_constraint_value

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

Nhãn của giá trị mặc định cho chế độ cài đặt này, sẽ được dùng nếu không có giá trị nào được cung cấp. Nếu thuộc tính này xuất hiện, thì 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 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 có giá trị ràng buộc nào cho chế độ cài đặt đó, thì điều này cũng giống như khi nền tảng đã chỉ định giá trị mặc định. Nếu không, nếu không có giá trị mặc định, thì chế độ cài đặt ràng buộc sẽ được nền tảng đó coi là chưa được chỉ định. Trong trường hợp đó, nền tảng sẽ không 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

Xem nguồn quy tắc

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

Quy tắc này giới thiệu một giá trị mới cho một loại 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ụ:

Thao tác sau đây sẽ tạo một giá trị có thể có mới 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 vì x86_64, arm, v.v.

Đối số

Thuộc tính

name

Tên; bắt buộc

Tên riêng 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 có thể là một lựa chọn.

platform

Xem nguồn quy tắc

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 về quy tắc 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ụ:

Điều 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ể dùng thuộc tính flags để chỉ định danh sách các 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 đó cho 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 sẽ 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 (hoặc vì người dùng chỉ định --platforms//:foo, vì một quá trình chuyển đổi đặt cờ //command_line_option:platforms thành ["//:foo"] hoặc vì //: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 được lặp lại, chẳng hạn như --features, --copt, mọi cờ Starlark đượ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ả các giá trị trước đó sẽ bị xoá và ghi đè bằng các giá trị từ nền tảng.

Ví dụ: giả sử có nền tảng sau, lệnh gọi build --platforms=//:repeat_demo --features feature_a --features feature_b sẽ kết thúc với 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 dùng các 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à chúng 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 tại, bạn chỉ có thể cung cấp một giá trị duy nhất 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 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ị 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 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ừ trong từ điển ở exec_properties của nền tảng gốc 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 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 dùng exec_properties. Logic được mô tả bên dưới vẫn được duy trì để tương thích với hành vi cũ nhưng sẽ bị xoá trong tương lai. Sau đây là logic để đặt remote_execution_platform khi có một nền tảng mẹ:

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 dùng.
Nếu remote_execution_property được đặt trên nền tảng con và chứa chuỗi ký tự {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ẹ.
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 mà không thay đổi.

Vì remote_execution_properties đã ngừng hoạt động và sẽ bị loại bỏ, 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 hơn 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ả các giá trị ràng buộc từ thành phần mẹ và không đặt bất kỳ giá trị nào của riêng thành phầ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 phần tử mẹ và không đặt thuộc tính riêng.
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ó sẽ là: { "k1": "child", "k2": "v2" }.
child_c kế thừa exec_properties của thành phần mẹ và huỷ đặt k1. exec_properties của nó sẽ là: { "k2": "v2" }.
child_d kế thừa exec_properties của phần tử mẹ và thêm một thuộc tính mới. exec_properties của nó sẽ là: { "k1": "v1", "k2": "v2", "k3": "v3" }.

Đối số

Thuộc tính
`name`	Tên; bắt buộc Tên riêng cho mục tiêu này.
`constraint_values`	Danh sách nhãn; không thể định cấu hình; mặc định là `[]` Sự kết hợp của các lựa chọn về ràng buộc mà nền tảng này bao gồm. Để một nền tảng á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: String -> String; nonconfigurable; mặc định là `{}` Một bản đồ các chuỗi ảnh hưởng đến cách thực thi các hành động từ xa. Bazel không cố gắng diễn giải điều này, nó được coi là dữ liệu không rõ ràng đượ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 đó có 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ùng một khoá, thì các giá trị của nền tảng con sẽ được giữ lại. Mọi khoá được 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 là một thuộc tính thay thế hoàn toàn cho `remote_execution_properties` không được dùng nữa.
`flags`	Danh sách các chuỗi; không thể định cấu hình; mặc định là `[]` Danh sách các cờ sẽ được bật khi nền tảng này được dùng làm nền tảng mục tiêu trong một cấu hình. Bạn chỉ được phép sử dụng những cờ có thể đặt trong hiệu ứng chuyển đổi.
`parents`	Danh sách nhãn; không thể định cấu hình; mặc định là `[]` 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 có một danh sách, nhưng không được có nhiều hơn một nền tảng. Mọi constraint_settings không được đặt trực tiếp trên nền tảng này sẽ nằm trong nền tảng mẹ. Hãy xem phần Kế thừ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; mặc định là `""` KHÔNG DÙNG NỮA. 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ế không cố gắng diễn giải điều này, mà coi đây là dữ liệu không rõ ràng mà một SpawnRunner cụ thể có thể sử dụng. Bạn có thể thê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}". Hãy xem phần về Tính kế thừa của nền tảng để biết thông tin chi tiết.
`required_settings`	Danh sách nhãn; mặc định là `[]` Một danh sách các `config_setting` mà cấu hình mục tiêu phải đáp ứng để nền tảng này được dùng làm nền tảng thực thi trong quá trình phân giải chuỗi công cụ. Các chế độ cài đặt bắt buộc không được kế thừa từ các nền tảng mẹ.

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 loại và các ràng buộc của một chuỗi công cụ cụ thể để có thể chọn trong quá trình phân giải chuỗi công cụ. Hãy xem trang Toolchains (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 riêng cho mục tiêu này.
`exec_compatible_with`	Danh sách nhãn; không thể định cấu hình; mặc định là `[]` Danh sách các `constraint_value` mà một nền tảng thực thi phải đáp ứng để chuỗi công cụ này được chọn cho một mục tiêu xây dựng trên nền tảng đó.
`target_compatible_with`	Danh sách nhãn; không thể định cấu hình; mặc định là `[]` Một danh sách các `constraint_value` mà nền tảng mục tiêu phải đáp ứng để chuỗi công cụ này được chọn 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 để chuỗi công cụ này được chọn 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 công cụ hoặc bộ công cụ thực tế được cung cấp 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` đại diện cho vai trò mà chuỗi công cụ này phục vụ.

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ụ đóng vai trò tương tự cho nhiều nền tảng.

Hãy xem trang Toolchains để biết thêm thông tin chi tiết.

Ví dụ:

Thao tác này xác định một 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 hàm 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 riêng cho mục tiêu này.